r2169 - add some comments for future reference
[racktables] / README
diff --git a/README b/README
index 77049e1c0182da2cadc7e79ae800ea9a098077fc..ca809d402674933632c0a4bd787237f63592b5dd 100644 (file)
--- a/README
+++ b/README
@@ -16,34 +16,58 @@ Authors: <info/=@=/racktables.org>
 
 I. Dependencies.
 
 
 I. Dependencies.
 
-For database you must have a MySQL server installation version 4.x or 5.x:
-Fedora Core 6: yum install mysql-server mysql
-Fedora 8: yum install mysql-server mysql
-ALTLinux Compact 3.0: apt-get install MySQL-server MySQL-client
-ALTLinux Desktop 4.0: apt-get install MySQL-server 
+For database you must have a MySQL server installation
+version 4.x or 5.x. It is a good idea to make it use UTF-8
+by default.
 
 
-For web-frontend you must have Apache and PHP 5 with PDO extension:
-Fedora Core 6: # yum install httpd php php-mysql php-pdo php-gd
-Fedora 8: yum install httpd php php-mysql php-pdo php-gd php-snmp
+* Fedora 8/9: yum install mysql-server mysql
+put "default-character-set=utf8" into /etc/my.cnf
 
 
-II. Layout
+* ALTLinux Desktop 4.0: apt-get install MySQL-server 
+put "CHSET=utf8" into /etc/sysconfig/mysqld
+
+*openSUSE 11.0: YaST -> Software -> software management -> Web and LAMP server -> mysql
+put "default-character-set=utf8" into /etc/my.cnf
+
+For web-frontend you must have Apache and PHP 5 with PDO and multibyte
+extensions:
+
+* Fedora 8/9: yum install httpd php php-mysql php-pdo php-gd php-snmp php-mbstring
+
+* ALTLinux Server 4.0: apt-get install apache2-httpd-prefork php5-gd2 \
+php5-pdo_mysql php5-pdo apache2-mod_php5 php5-mbstring
+
+* openSUSE 11.0: use YaST to apache2-mod_php5, php5-gd, php5-mbstring, php5-mysql,
+php2-snmp and php5-ldap
+
+II. Prepare the server.
 1. Unpack the tarball and make it web-accessible, e.g. http://yourcompany.com/racktables
 or http://racktables.mysite.org.
 1. Unpack the tarball and make it web-accessible, e.g. http://yourcompany.com/racktables
 or http://racktables.mysite.org.
-2. Edit install/init-auth.sql and change admin password
+2. mysql> create database_name; grant all privileges on database_name.* to XXX@YYY identified by 'ZZZ';
+
 
 
-III. Database setup
-mysql> create database_name;
+There are two mutually exclusive ways to install RackTables, they are described as III-A and III-B.
+
+
+III-A. HTTP installation (starting with 0.14.12 release)
+Open your RackTables URL and follow the instructions. In a suitable
+environment everything should take a minute or so.
+
+
+III-B. Manual installation.
+1. Edit install/init-auth.sql and change admin password
+
+2. Init database.
 mysql> use database_name;
 mysql> source install/init-structure.sql
 mysql> source install/init-auth.sql
 $ rm -f install/init-auth.sql
 mysql> source install/init-dictbase.sql
 mysql> source install/init-dictvendors.sql
 mysql> use database_name;
 mysql> source install/init-structure.sql
 mysql> source install/init-auth.sql
 $ rm -f install/init-auth.sql
 mysql> source install/init-dictbase.sql
 mysql> source install/init-dictvendors.sql
-mysql> grant all privileges on database_name.* to XXX@YYY identified by 'ZZZ';
 
 
-Make sure your inc/secret.php matches real values you used in the above request.
+3. Edit inc/secret.php
 
 
-IV. $ rm -f install/init-auth.sql
+4. $ rm -f install/init-auth.sql
 (Just to be sure you did.)
 
 *******************************************************
 (Just to be sure you did.)
 
 *******************************************************
@@ -63,7 +87,51 @@ procedure should be sufficient:
 4. Follow instructions. Normally, everything should be Ok. If it
    is not so, write down the failed quieries for further investigation.
 
 4. Follow instructions. Normally, everything should be Ok. If it
    is not so, write down the failed quieries for further investigation.
 
-Upgrading to 0.14.12
+*******************************************************
+*                                                     *
+*                   RELEASE NOTES                     *
+*                                                     *
+*******************************************************
+
+*** Upgrading to 0.14.12 ***
+
 The upgrade may show a failed query "alter database character set utf8", in
 this case the user should issue the query manually from the mysql command
 line.
 The upgrade may show a failed query "alter database character set utf8", in
 this case the user should issue the query manually from the mysql command
 line.
+
+*** Upgrading to 0.16.0 ***
+
+This release features a completely new authorization system, RackCode,
+which brings the tags feature (introduced in 0.15.0) to its full potential.
+The old-style user permissions are converted during upgrade automatically,
+but the result may appear not what you would expect. Review the RackCode
+after upgrade (Main page -> Configuration -> Permissions) and adjust,
+if necessary.
+
+Another important change is a new dependency on "multibyte string" PHP
+extension. Normally one should get it working before starting the upgrade,
+this is typically achieved by installing a particular PHP RPM from the
+standard package repository (and restarting Apache after that):
+
+Fedora: yum install php-mbstring
+ALTLinux: apt-get install php5-mbstring
+
+*** Upgrading to 0.16.1 ***
+This release fixes a missing UNIQUE key in the database. However, this fix
+may sometimes fail, if the table contains duplicate records. If the
+0.16.0-0.16.1 upgrade batch completed without errors, no action needs to be
+taken. If you see a failed ADD UNIQUE query during upgrade, the only solution
+is to delete the duplicates manually. To do this, open a MySQL console and
+issue the failed query again:
+
+mysql> alter table IPVirtualService ADD UNIQUE endpoint (vip, vport, proto);
+
+The IP address of the duplicate VS will be known from the "Duplicate entry"
+message. For example, to decode "Duplicate entry '180879877-80-TCP' for key
+2" error message, issue:
+
+mysql> select inet_ntoa(180879877);
+
+Then go to "virtual services" web-interface page and adjust the data as
+necessary. You would need to get rid of the duplicates accurately one by
+one, repeating the ADD UNIQUE query until it succeeds.