fix spelling in release notes
[racktables] / README
1 Thank you for selecting RackTables as your datacenter management solution!
2 If you are looking for documentation or wish to send feedback, please
3 look for the respective links at project's web-site (racktables.org).
4
5 *******************************************************
6 * *
7 * INSTALLING RACKTABLES *
8 * *
9 *******************************************************
10
11 *** I. SERVER ***
12
13 RackTables requires a MySQL server version 5.x built with InnoDB and
14 Unicode support and configured appropriately. It also requires an Apache
15 httpd with PHP 5 module and several PHP extensions. Below is a list of
16 known-good distributions with respective setup notes.
17
18 *** Fedora 8-16
19 * MySQL: yum install mysql-server mysql
20 * Apache/PHP: yum install httpd php php-mysql php-pdo php-gd php-snmp \
21 php-mbstring php-bcmath
22 * To enable Unicode, add "character-set-server=utf8" line to "[mysqld]"
23 section of "/etc/my.cnf" file and restart mysqld.
24
25 *** Debian 6
26 * MySQL: aptitude install mysql-server-5.1
27 * Apache/PHP: aptitude install libapache2-mod-php5 php5-gd php5-mysql php5-snmp
28 * To enable Unicode, add "character-set-server=utf8" line to "[mysqld]"
29 section of "/etc/mysql/my.cnf" file and restart mysqld.
30
31 *** ALTLinux 4.0
32 * MySQL: apt-get install MySQL-server
33 * Apache/PHP: apt-get install apache2-httpd-prefork php5-gd2 \
34 php5-pdo_mysql php5-pdo apache2-mod_php5 php5-mbstring
35 * To enable Unicode, add "CHSET=utf8" line to "/etc/sysconfig/mysqld" file
36 and restart mysqld.
37
38 *** openSUSE 11.0
39 * MySQL: YaST -> Software -> software management -> Web and LAMP server -> mysql
40 * Apache/PHP: use YaST to install apache2-mod_php5, php5-gd, php5-mbstring,
41 php5-mysql, php5-bcmath, php5-snmp and php5-ldap
42 * To enable Unicode, add "default-character-set=utf8" line to "[mysql]"
43 section of "/etc/my.cnf" file and restart mysqld.
44
45 *** Scientific Linux 6
46 * MySQL: yum install mysql-server mysql
47 * Apache/PHP: httpd php php-mysql php-pdo php-gd php-mbstring php-bcmath
48 * To enable Unicode, add "character-set-server=utf8" line to "[mysqld]"
49 section of "/etc/my.cnf" file and restart mysqld.
50
51 *** FreeBSD 8
52 * Apache/PHP:
53 # make -C /usr/ports/www/apache13-modssl install
54 # make -C /usr/ports/www/php5-session install
55 [X] CLI Build CLI version
56 [X] APACHE Build Apache module
57 [X] MULTIBYTE Enable zend multibyte support
58 # make -C /usr/ports/graphics/php5-gd install
59 # make -C /usr/ports/databases/php5-pdo_mysql install
60 # make -C /usr/ports/devel/pcre install
61 !!! Enable UTF-8 support ............ : yes
62 !!! Unicode properties .............. : yes
63 # make -C /usr/ports/devel/php5-pcre install
64 # make -C /usr/ports/converters/php5-mbstring install
65 [X] REGEX Enable multibyte regex support
66
67 # make -C /usr/ports/net-mgmt/php5-snmp install
68 # make -C /usr/ports/net/php5-ldap install
69
70 *** II. FILES ***
71 Unpack distro files to any directory you want and configure Apache to "wwwroot"
72 subdirectory as DocumentRoot. Symlinks to wwwroot or even index.php from your
73 web server root are also possible.
74
75 *** III. INSTALLER ***
76 Open your configured RackTables URL and you will be prompted to configure
77 and initialize the application.
78
79 *******************************************************
80 * *
81 * UPGRADING RACKTABLES *
82 * *
83 *******************************************************
84 RackTables (since 0.14.6) provides an automatic database upgrade feature.
85 If you already have a working installation, the following procedure
86 should be sufficient:
87
88 0. BACKUP YOUR DATABASE and check the release notes (below) before actually
89 starting the upgrade,.
90 1. Remove all existing files except inc/secret.php and the gateways'
91 configuration (in the gateways directory).
92 2. Unpack the new tarball into the place.
93 3. Open your RackTables page in a browser. The software detects version
94 mismatch and displays a message telling to log in as admin to finish
95 the upgrade.
96 4. Do that. Normally, everything should be Ok. If there are
97 errors displayed, send these in a bug report.
98
99 *******************************************************
100 * *
101 * RELEASE NOTES *
102 * *
103 *******************************************************
104
105 *** Upgrading to 0.20.5 ***
106
107 This release introduces the VS groups feature. VS groups is a new way to store
108 and display virtual services configuration. New realm 'ipvs' (VS group) is created.
109 All the existing VS configuration is kept and displayed as-is, but user is free to convert
110 it to the new format, which displays it in more natural way and allows to generate
111 virtual_server_group keepalived configs. To convert a virtual service to the new format,
112 you need to manually create the vs group object and assign IP addresses to it. Then, if you
113 have the old-style VSes configured, the Migrate tab will be displayed on the particular VS group's
114 page. After successfull migration, you can remove the old-style VS objects.
115
116 Old-style VS configuration becomes DEPRECATED. Its support will be removed in one of the following
117 major releases. So it is strongly recommended to convert it to the new format.
118
119 *** Upgrading to 0.20.4 ***
120
121 Please note that some dictionary items of Cisco Catalyst 2960 series switches
122 were renamed to meet official Cisco classification:
123 2960-48TT => 2960-48TT-L
124 2960-24TC => 2960-24TC-L
125 2960-24TT => 2960-24TT-L
126 2960-8TC => 2960-8TC-L
127 2960G-48TC => 2960G-48TC-L
128 2960G-24TC => 2960G-24TC-L
129 2960G-8TC => 2960G-8TC-L
130 C2960-24 => C2960-24-S
131 C2960G-24PC => C2960-24PC-L
132
133 The DATETIME_FORMAT configuration option used in setting date and time output
134 format now uses a different [1] syntax. During upgrade the option is reset to
135 the default value, which is now %Y-%m-%d (YYYY-MM-DD) per ISO 8601.
136
137 This release intoduces two new configuration options:
138 REVERSED_RACKS_LISTSRC and NEAREST_RACKS_CHECKBOX.
139
140 [1] http://php.net/manual/en/function.strftime.php
141
142 *** Upgrading to 0.20.1 ***
143
144 The 0.20.0 release includes bug which breaks IP networks' capacity displaying on
145 32-bit architecture machines. To fix this, this release makes use of PHP's BC
146 Math module. It is a new reqiurement. Most PHP distributions have this module
147 already enabled, but if yours does not - you need yo recompile PHP.
148
149 Security context of 'ipaddress' page now includes tags from the network
150 containing an IP address. This means that you should audit your permission rules
151 to check there is no unintended allows of changing IPs based on network's
152 tagset. Example:
153 allow {client network} and {New York}
154 This rule now not only allows any operation on NY client networks, but also any
155 operation with IP addresses included in those networks. To fix this, you should
156 change the rule this way:
157 allow {client network} and {New York} and not {$page_ipaddress}
158
159 *** Upgrading to 0.20.0 ***
160
161 WARNING: This release have too many internal changes, some of them were waiting
162 more than a year to be released. So this release is considered "BETA" and is
163 recommended only to curiuos users, who agree to sacrifice the stability to the
164 progress.
165
166 Racks and Rows are now stored in the database as Objects. The RackObject table
167 was renamed to Object. SQL views were created to ease the migration of custom
168 reports and scripts.
169
170 New plugins engine instead of local.php file. To make your own code stored in
171 local.php work, you must move the local.php file into the plugins/ directory.
172 The name of this file does not matter any more. You also can store multiple
173 files in that dir, separate your plugins by features, share them and try the
174 plugins from other people just placing them into plugins/ dir, no more merging.
175
176 $path_to_local_php variable has no special meaning any more.
177 $racktables_confdir variable is now used only to search for secret.php file.
178 $racktables_plugins_dir is a new overridable special variable pointing to
179 plugins/ directory.
180
181 Beginning with this version it is possible to delete IP prefixes, VLANs, Virtual
182 services and RS pools from within theirs properties tab. So please inspect your
183 permissions rules to assure there are no undesired allows for deletion of these
184 objects. To ensure this, you could try this code in the beginning of permissions
185 script:
186
187 allow {userid_1} and {$op_del}
188 deny {$op_del} and ({$tab_edit} or {$tab_properties})
189
190 Hardware gateways engine was rewritten in this version of RackTables. This means
191 that the file gateways/deviceconfig/switch.secrets.php is not used any more. To
192 get information about configuring connection properties and credentials in a new
193 way please visit http://wiki.racktables.org/index.php/Gateways
194
195 This also means that recently added features based on old API (D-Link switches
196 and Linux gateway support contributed by Ilya Evseev) are not working any more
197 and waiting to be forward-ported to new gateways API. Sorry for that.
198
199 Two new config variables appeared in this version:
200 - SEARCH_DOMAINS. Comma-separated list of DNS domains which are considered
201 "base" for your network. If RackTables search engine finds multiple objects
202 based on your search input, but there is only one which FQDN consists of
203 your input and one of these search domains, you will be redirected to this
204 object and other results will be discarded. Such behavior was unconditional
205 since 0.19.3, which caused many objections from users. So welcome this
206 config var.
207 - QUICK_LINK_PAGES. Comma-separated list of RackTables pages to display links
208 to them on top. Each user could have his own list.
209
210 Also some of config variables have changed their default values in this version.
211 This means that upgrade script will change their values if you have them in
212 previous default state. This could be inconvenient, but it is the most effective
213 way to encourage users to use new features. If this behavior is not what you
214 want, simply revert these variables' values:
215 - SHOW_LAST_TAB no => yes
216 - IPV4_TREE_SHOW_USAGE yes =>no (networks' usage is still available
217 by click)
218 - IPV4LB_LISTSRC {$typeid_4} => false
219 - FILTER_DEFAULT_ANDOR or => and (this implicitly enables the feature
220 of dynamic tree shrinking)
221 - FILTER_SUGGEST_EXTRA no => yes (yes, we have extra logical filters!)
222 - IPV4_TREE_RTR_AS_CELL yes => no (display routers as simple text, not
223 cell)
224
225 Also please note that variable IPV4_TREE_RTR_AS_CELL now has third special value
226 besides 'yes' and 'no': 'none'. Use 'none' value if you are experiencing low
227 performance on IP tree page. It will completely disable IP ranges scan for
228 used/spare IPs and the speed of IP tree will increase radically. The price is
229 you will not see the routers in IP tree at all.
230
231 *** Upgrading to 0.19.13 ***
232 A new "date" attribute type has been added. Existing date based fields ("HW
233 warranty expiration", "support contract expiration" and "SW warranty
234 expiration") will be converted to this new type but must be in the format
235 "mm/dd/yyyy" otherwise the conversion will fail.
236
237 *** Upgrading to 0.19.2 ***
238
239 This release is different in filesystem layout. The "gateways" directory has
240 been moved from "wwwroot" directory. This improves security a bit. You can also
241 separate your local settings and add-ons from the core RackTables code. To do
242 that, put a single index.php file into the DocumentRoot of your http server:
243
244 <?php
245 $racktables_confdir='/directory/with/secret.php/and/local.php/';
246 require '/directory_where_you_extracted_racktables_distro/wwwroot/index.php';
247 ?>
248
249 No more files are needed to be available directly over the HTTP. Full list of
250 filesystem paths which could be specified in custom index.php or secret.php:
251 $racktables_gwdir: path to the gateways directory;
252 $racktables_staticdir: path to the directory containing 'pix', 'js', 'css'
253 directories;
254 $racktables_confdir: path where secret.php and local.php are located. It is
255 not recommended to define it in secret.php, cause only
256 the path to local.php will be affected;
257 $path_to_secret_php: Ignore $racktables_confdir when locating secret.php and
258 use the specified path;
259 $path_to_local_php: idem for local.php.
260
261 *** Upgrading to 0.19.0 ***
262
263 The files, which are intended for the httpd (web-server) directory, are now in
264 the "wwwroot" directory of the tar.gz archive. Files outside of that directory
265 are not directly intended for httpd environment and should not be copied to the
266 server.
267
268 This release incorporates ObjectLog functionality, which used to be available as
269 a separate plugin. For the best results it is advised to disable (through
270 local.php) external ObjectLog plugin permanently before the new version is
271 installed. All previously accumulated ObjectLog records will be available
272 through the updated standard interface.
273
274 RackTables is now using PHP JSON extension which is included in the PHP core
275 since 5.2.0.
276
277 The barcode attribute was removed. The upgrade script attempts to preserve the
278 data by moving it to either the 'OEM S/N 1' attribute or to a Log entry. You
279 should backup your database beforehand anyway.
280
281 *** Upgrading to 0.18.x ***
282
283 RackTables from its version 0.18.0 and later is not compatible with RHEL/CentOS
284 (at least with versions up to 5.5) Linux distributions in their default
285 installation. There are yet options to work around that:
286 1. Install RackTables on a server with a different distribution/OS.
287 2. Request Linux distribution vendor to fix the bug with PCRE.
288 3. Repair your RHEL/CentOS installation yourself by fixing its PCRE
289 RPM as explained here: http://bugs.centos.org/view.php?id=3252
290
291 *** Upgrading to 0.17.0 ***
292
293 One can always install RackTables 0.17.0 from scratch. However, upgrading an
294 existing installation to 0.17.0 implies a certain upgrade path. If the existing
295 database version is less, than 0.16.4, it must first be upgraded to version
296 0.16.4, 0.16.5 or 0.16.6 (at one's choice) using appropriate tar.gz
297 distribution. The resulting 0.16.4+ database can be upgraded to 0.17.0 (or later
298 version) in a normal way (with tar.gz of the desired 0.17.x release).
299
300 LDAP options have been moved to LDAP_options array. This means, that if you were
301 using LDAP authentication for users in version 0.16.x, it will break right after
302 upgrade to 0.17.0. To get things working again, adjust existing secret.php file
303 according to secret-sample.php file provided with 0.17.0 release.
304
305 This release is the first to take advantage of the foreign key support provided
306 by the InnoDB storage engine in MySQL. The installer and upgrader scripts check
307 for InnoDB support and cannot complete without it. If you have trouble, the
308 first step is to make sure the 'skip-innodb' option in my.cnf is commented out.
309
310 Another change is the addition of support for file uploads. Files are stored in
311 the database. There are several settings in php.ini which you may need to
312 modify:
313 file_uploads - needs to be On
314 upload_max_filesize - max size for uploaded files
315 post_max_size - max size of all form data submitted via POST
316 (including files)
317
318 User accounts used to have 'enabled' flag, which allowed individual blocking and
319 unblocking of each. This flag was dropped in favor of existing mean of access
320 setup (RackCode). An unconditional denying rule is automatically added into
321 RackCode for such blocked account, so the effective security policy remains the
322 same.