r3389 2nd round of PCRE work (#262), fix regexps
[racktables] / README
CommitLineData
de8695b2
DO
1Thank you for selecting RackTables as your datacenter management
2solution. Feel free to address your questions to the mailing list
ad592f37 3before contacting the developers directly.
de8695b2 4
ad592f37
DO
5Project homepage: http://racktables.org/
6Project SF page: http://sourceforge.net/projects/racktables/
7Documentation: http://sourceforge.net/apps/mediawiki/racktables/index.php?title=Main_Page
8Users mailing list: <racktables-users/=@=/freelists.org>
9Mailing list archive: http://www.freelists.org/archive/racktables-users
10Developers: <info/=@=/racktables.org>
de8695b2
DO
11
12*******************************************************
13* *
14* INSTALLING RACKTABLES *
15* *
16*******************************************************
17
d3372430 18I. Install dependencies.
de8695b2 19
3ebdbeed 20For database you must have a MySQL server installation
e1ae3fb4
AD
21version 4.x or 5.x. InnoDB support must be enabled.
22It is a good idea to make it use UTF-8 by default.
3ebdbeed
DO
23
24* Fedora 8/9: yum install mysql-server mysql
25put "default-character-set=utf8" into /etc/my.cnf
26
27* ALTLinux Desktop 4.0: apt-get install MySQL-server
28put "CHSET=utf8" into /etc/sysconfig/mysqld
29
3e1c9c67 30* openSUSE 11.0: YaST -> Software -> software management -> Web and LAMP server -> mysql
3ebdbeed 31put "default-character-set=utf8" into /etc/my.cnf
de8695b2 32
9ddee5ea
DO
33For web-frontend you must have Apache and PHP 5 with PDO and multibyte
34extensions:
3ebdbeed
DO
35
36* Fedora 8/9: yum install httpd php php-mysql php-pdo php-gd php-snmp php-mbstring
37
38* ALTLinux Server 4.0: apt-get install apache2-httpd-prefork php5-gd2 \
9ddee5ea 39php5-pdo_mysql php5-pdo apache2-mod_php5 php5-mbstring
c2d46542 40
3ebdbeed 41* openSUSE 11.0: use YaST to apache2-mod_php5, php5-gd, php5-mbstring, php5-mysql,
93bdb7ba 42php5-snmp and php5-ldap
3ebdbeed 43
a3bce64d
DO
44* FreeBSD 7:
45# make -C /usr/ports/www/apache13-modssl install
46# make -C /usr/ports/www/php5-session install
47[X] CLI Build CLI version
48[X] APACHE Build Apache module
49[X] MULTIBYTE Enable zend multibyte support
50# make -C /usr/ports/graphics/php5-gd install
51# make -C /usr/ports/databases/php5-pdo_mysql install
52# make -C /usr/ports/devel/php5-pcre install
53# make -C /usr/ports/converters/php5-mbstring install
54[X] REGEX Enable multibyte regex support
55
56# make -C /usr/ports/net-mgmt/php5-snmp install
57# make -C /usr/ports/net/php5-ldap install
d3372430
DO
58
59II. Prepare the files and database.
de8695b2
DO
601. Unpack the tarball and make it web-accessible, e.g. http://yourcompany.com/racktables
61or http://racktables.mysite.org.
1538b9c9
DO
62
632. Setup MySQL database:
64mysql> CREATE DATABASE racktables_db CHARACTER SET utf8 COLLATE utf8_general_ci;
65mysql> grant all privileges on racktables_db.* to XXX@YYY identified by 'ZZZ';
c2d46542
DO
66
67
d3372430 68III. Finish the installation.
c2d46542
DO
69Open your RackTables URL and follow the instructions. In a suitable
70environment everything should take a minute or so.
71
de8695b2
DO
72*******************************************************
73* *
74* UPGRADING RACKTABLES *
75* *
76*******************************************************
d3372430
DO
77RackTables (since 0.14.6) provides an automatic database upgrade feature.
78If you already have a working installation, the following procedure
79should be sufficient:
de8695b2
DO
80
810. BACKUP YOUR DATABASE
80138748
DO
821. Remove all existing files except inc/secret.php, gateways'
83 configuration (in the gateways directory) and local mod (inc/local.php).
de8695b2 842. Unpack the new tarball into the place.
d3372430
DO
853. Open the RackTables page in your browser. The software detects version
86 mismatch and displays a message telling to log in as admin to finish
87 the upgrade.
884. Do that. Normally, everything should be Ok. If there are
89 errors displayed, copy and send them to us for review.
7fc5565c 90
c2d46542
DO
91*******************************************************
92* *
93* RELEASE NOTES *
94* *
95*******************************************************
96
9ddee5ea
DO
97*** Upgrading to 0.14.12 ***
98
7fc5565c
DO
99The upgrade may show a failed query "alter database character set utf8", in
100this case the user should issue the query manually from the mysql command
101line.
9ddee5ea
DO
102
103*** Upgrading to 0.16.0 ***
104
105This release features a completely new authorization system, RackCode,
106which brings the tags feature (introduced in 0.15.0) to its full potential.
107The old-style user permissions are converted during upgrade automatically,
108but the result may appear not what you would expect. Review the RackCode
109after upgrade (Main page -> Configuration -> Permissions) and adjust,
110if necessary.
111
112Another important change is a new dependency on "multibyte string" PHP
113extension. Normally one should get it working before starting the upgrade,
114this is typically achieved by installing a particular PHP RPM from the
115standard package repository (and restarting Apache after that):
116
117Fedora: yum install php-mbstring
118ALTLinux: apt-get install php5-mbstring
8608b285 119
4d69ff46
DO
120*** Upgrading to 0.16.3 ***
121
122This release fixes a missing UNIQUE KEY in a table. The upgrade script may
123find it necessary first to transform some records. Because of this it is
124normal to see several "update TagStorage ... Duplicate entry" failed queries
125during the upgrade.
30d0a2a3
DO
126
127*** Upgrading to 0.17.0 ***
128
d74ae24c
DO
129One can always install RackTables 0.17.0 from scratch. However, upgrading
130an existing installation to 0.17.0 implies a certain upgrade path. If the
131existing database version is less, than 0.16.4, it must first be upgraded
132to version 0.16.4, 0.16.5 or 0.16.6 (at one's choice) using appropriate
133tar.gz distribution. The resulting 0.16.4+ database can be upgraded to
1340.17.0 (or later version) in a normal way (with tar.gz of the desired 0.17.x
135release).
136
2c9fde3a
DO
137LDAP options have been moved to LDAP_options array. This means, that if you were
138using LDAP authentication for users in version 0.16.x, it will break right after
aca5a846 139upgrade to 0.17.0. To get things working again, adjust existing secret.php file
2c9fde3a
DO
140according to secret-sample.php file provided with 0.17.0 release.
141
3e1c9c67
DO
142This release is the first to take advantage of the foreign key support
143provided by the InnoDB storage engine in MySQL. The installer and
e1ae3fb4
AD
144upgrader scripts check for InnoDB support and cannot complete without it.
145If you have trouble, the first step is to make sure the 'skip-innodb'
146option in my.cnf is commented out.
147
148Another change is the addition of support for file uploads. Files are stored
149in the database. There are several settings in php.ini which you may need to modify:
150 file_uploads - needs to be On
151 upload_max_filesize - max size for uploaded files
3e1c9c67
DO
152 post_max_size - max size of all form data submitted via POST (including files)
153
79b8ad1e 154User accounts used to have 'enabled' flag, which allowed individual blocking and
a476909e
DO
155unblocking of each. This flag was dropped in favor of existing mean of access
156setup (RackCode). An unconditional denying rule is automatically added into RackCode
157for such blocked account, so the effective security policy remains the same.