r2138 - add an index to RackSpace table (suggested by Aaron)
[racktables] / README
1 Thank you for selecting RackTables as your datacenter management
2 solution. Feel free to address your questions to the mailing list
3 before contacting the authors directly. The project web-site
4 (http://racktables.org/) is usually kept up to date with the
5 current version and URLs.
6
7 Mailing list: <racktables-users/=@=/freelists.org>
8 Bug tracker and Wiki: http://racktables.org/trac
9 Authors: <info/=@=/racktables.org>
10
11 *******************************************************
12 * *
13 * INSTALLING RACKTABLES *
14 * *
15 *******************************************************
16
17 I. Dependencies.
18
19 For database you must have a MySQL server installation
20 version 4.x or 5.x. It is a good idea to make it use UTF-8
21 by default.
22
23 * Fedora 8/9: yum install mysql-server mysql
24 put "default-character-set=utf8" into /etc/my.cnf
25
26 * ALTLinux Desktop 4.0: apt-get install MySQL-server
27 put "CHSET=utf8" into /etc/sysconfig/mysqld
28
29 *openSUSE 11.0: YaST -> Software -> software management -> Web and LAMP server -> mysql
30 put "default-character-set=utf8" into /etc/my.cnf
31
32 For web-frontend you must have Apache and PHP 5 with PDO and multibyte
33 extensions:
34
35 * Fedora 8/9: yum install httpd php php-mysql php-pdo php-gd php-snmp php-mbstring
36
37 * ALTLinux Server 4.0: apt-get install apache2-httpd-prefork php5-gd2 \
38 php5-pdo_mysql php5-pdo apache2-mod_php5 php5-mbstring
39
40 * openSUSE 11.0: use YaST to apache2-mod_php5, php5-gd, php5-mbstring, php5-mysql,
41 php2-snmp and php5-ldap
42
43 II. Prepare the server.
44 1. Unpack the tarball and make it web-accessible, e.g. http://yourcompany.com/racktables
45 or http://racktables.mysite.org.
46 2. mysql> create database_name; grant all privileges on database_name.* to XXX@YYY identified by 'ZZZ';
47
48
49 There are two mutually exclusive ways to install RackTables, they are described as III-A and III-B.
50
51
52 III-A. HTTP installation (starting with 0.14.12 release)
53 Open your RackTables URL and follow the instructions. In a suitable
54 environment everything should take a minute or so.
55
56
57 III-B. Manual installation.
58 1. Edit install/init-auth.sql and change admin password
59
60 2. Init database.
61 mysql> use database_name;
62 mysql> source install/init-structure.sql
63 mysql> source install/init-auth.sql
64 $ rm -f install/init-auth.sql
65 mysql> source install/init-dictbase.sql
66 mysql> source install/init-dictvendors.sql
67
68 3. Edit inc/secret.php
69
70 4. $ rm -f install/init-auth.sql
71 (Just to be sure you did.)
72
73 *******************************************************
74 * *
75 * UPGRADING RACKTABLES *
76 * *
77 *******************************************************
78 RackTables now provides an automatic database upgrade feature.
79 If you already have a working installation, the following
80 procedure should be sufficient:
81
82 0. BACKUP YOUR DATABASE
83 1. Remove all existing files except inc/secret.php and gateways'
84 configuration (in the gateways directory).
85 2. Unpack the new tarball into the place.
86 3. Open the RackTables page in your browser.
87 4. Follow instructions. Normally, everything should be Ok. If it
88 is not so, write down the failed quieries for further investigation.
89
90 *******************************************************
91 * *
92 * RELEASE NOTES *
93 * *
94 *******************************************************
95
96 *** Upgrading to 0.14.12 ***
97
98 The upgrade may show a failed query "alter database character set utf8", in
99 this case the user should issue the query manually from the mysql command
100 line.
101
102 *** Upgrading to 0.16.0 ***
103
104 This release features a completely new authorization system, RackCode,
105 which brings the tags feature (introduced in 0.15.0) to its full potential.
106 The old-style user permissions are converted during upgrade automatically,
107 but the result may appear not what you would expect. Review the RackCode
108 after upgrade (Main page -> Configuration -> Permissions) and adjust,
109 if necessary.
110
111 Another important change is a new dependency on "multibyte string" PHP
112 extension. Normally one should get it working before starting the upgrade,
113 this is typically achieved by installing a particular PHP RPM from the
114 standard package repository (and restarting Apache after that):
115
116 Fedora: yum install php-mbstring
117 ALTLinux: apt-get install php5-mbstring
118
119 *** Upgrading to 0.16.1 ***
120 This release fixes a missing UNIQUE key in the database. However, this fix
121 may sometimes fail, if the table contains duplicate records. If the
122 0.16.0-0.16.1 upgrade batch completed without errors, no action needs to be
123 taken. If you see a failed ADD UNIQUE query during upgrade, the only solution
124 is to delete the duplicates manually. To do this, open a MySQL console and
125 issue the failed query again:
126
127 mysql> alter table IPVirtualService ADD UNIQUE endpoint (vip, vport, proto);
128
129 The IP address of the duplicate VS will be known from the "Duplicate entry"
130 message. For example, to decode "Duplicate entry '180879877-80-TCP' for key
131 2" error message, issue:
132
133 mysql> select inet_ntoa(180879877);
134
135 Then go to "virtual services" web-interface page and adjust the data as
136 necessary. You would need to get rid of the duplicates accurately one by
137 one, repeating the ADD UNIQUE query until it succeeds.