Update README with nginx and php5-fpm conf
[racktables-incomplete-works] / 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. By default RackTables is
15 developed on Apache httpd with PHP 5 module and several PHP extensions.
16 Below is a list of 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 *** Debian 7 with nginx
32 * MySQL: aptitude install mysql-server-5.1
33 * nginx: aptitude install nginx php5-fpm
34 * Remember to adjust server_name in server {} section, otherwise your logout link
35 * will point to localhost (and thus fail).
36 * Notice, that fpm.sock is advised, keep the rest on default configuration, or
37 * tweak to your needs. You may need to set fastcgi_read_timeout 600; if you use
38 * some external addons like fping, which may take some time in certain situations.
39 * Please note that setting aggresive caching for php scripts may result in stale
40 * content - so maximum of 60 seconds is advised, but by default it is not enabled.
41 * To enable Unicode, add "character-set-server=utf8" line to "[mysqld]"
42 section of "/etc/mysql/my.cnf" file and restart mysqld.
43
44 *** ALTLinux 4.0
45 * MySQL: apt-get install MySQL-server
46 * Apache/PHP: apt-get install apache2-httpd-prefork php5-gd2 \
47 php5-pdo_mysql php5-pdo apache2-mod_php5 php5-mbstring
48 * To enable Unicode, add "CHSET=utf8" line to "/etc/sysconfig/mysqld" file
49 and restart mysqld.
50
51 *** openSUSE 11.0
52 * MySQL: YaST -> Software -> software management -> Web and LAMP server -> mysql
53 * Apache/PHP: use YaST to install apache2-mod_php5, php5-gd, php5-mbstring,
54 php5-mysql, php5-bcmath, php5-snmp and php5-ldap
55 * To enable Unicode, add "default-character-set=utf8" line to "[mysql]"
56 section of "/etc/my.cnf" file and restart mysqld.
57
58 *** Scientific Linux 6
59 * MySQL: yum install mysql-server mysql
60 * Apache/PHP: httpd php php-mysql php-pdo php-gd php-mbstring php-bcmath
61 * To enable Unicode, add "character-set-server=utf8" line to "[mysqld]"
62 section of "/etc/my.cnf" file and restart mysqld.
63
64 *** CentOS 5
65 * MySQL: yum install mysql-server mysql
66 * Apache/PHP: httpd php53 php53-mysql php53-pdo php53-gd php53-mbstring \
67 php53-bcmath
68 * To enable Unicode, add "character-set-server=utf8" line to "[mysqld]"
69 section of "/etc/my.cnf" file and restart mysqld.
70
71 *** FreeBSD 8
72 * Apache/PHP:
73 # make -C /usr/ports/www/apache13-modssl install
74 # make -C /usr/ports/www/php5-session install
75 [X] CLI Build CLI version
76 [X] APACHE Build Apache module
77 [X] MULTIBYTE Enable zend multibyte support
78 # make -C /usr/ports/graphics/php5-gd install
79 # make -C /usr/ports/databases/php5-pdo_mysql install
80 # make -C /usr/ports/devel/pcre install
81 !!! Enable UTF-8 support ............ : yes
82 !!! Unicode properties .............. : yes
83 # make -C /usr/ports/devel/php5-pcre install
84 # make -C /usr/ports/converters/php5-mbstring install
85 [X] REGEX Enable multibyte regex support
86
87 # make -C /usr/ports/net-mgmt/php5-snmp install
88 # make -C /usr/ports/net/php5-ldap install
89
90 *** II. FILES ***
91 Unpack the tar.gz/zip archive to a directory of your choice and configure Apache
92 httpd to use "wwwroot" subdirectory as a new DocumentRoot. Alternatively,
93 symlinks to "wwwroot" or even to "index.php" from an existing DocumentRoot are
94 also possible and often adisable (see README.Fedora).
95
96 *** III. INSTALLER ***
97 Open the configured RackTables URL and you will be prompted to configure
98 and initialize the application.
99
100 *******************************************************
101 * *
102 * UPGRADING RACKTABLES *
103 * *
104 *******************************************************
105
106 0. BACKUP YOUR DATABASE and check the release notes below before actually
107 starting the upgrade.
108 1. Remove all existing files except configuration (the "inc/secret.php" file)
109 and local plugins (in the "plugins" directory).
110 2. Put the contents of the new tar.gz/zip archive into the place.
111 3. Open the RackTables page in a browser. The software will detect version
112 mismatch and display a message telling to log in as admin to finish
113 the upgrade.
114 4. Do that and report any errors to the bug tracker or the mailing list.
115
116 *******************************************************
117 * *
118 * RELEASE NOTES *
119 * *
120 *******************************************************
121
122 *** Upgrading to 0.20.7 ***
123
124 From now on the minimum (oldest) release of PHP that can run RackTables is
125 5.2.10. In particular, to continue running RackTables on CentOS 5 it is
126 necessary to replace its php* RPM packages with respective php53* packages
127 before the upgrade (except the JSON package, which PHP 5.3 provides internally).
128
129 Database triggers are used for some data consistency measures. The database
130 user account must have the 'TRIGGER' privilege, which was introduced in
131 MySQL 5.1.7.
132
133 The IPV4OBJ_LISTSRC configuration option is reset to an expression which enables
134 the IP addressing feature for all object types except those listed.
135
136 Tags could now be assigned on the Edit/Properties tab using a text input with
137 auto-completion. Type a star '*' to view full tag tree in auto-complete menu.
138 It is worth to add the following line to the permissions script if the
139 old-fashioned 'Tags' tab is not needed any more:
140 deny {$tab_tags} # this hides 'Tags' tab
141
142 This release converts collation of all DB fields to the utf8_unicode_ci. This
143 procedure may take some time, and could fail if there are rows that differ only
144 by letter case. If this happen, you'll see the failed SQL query in upgrade report
145 with the "Duplicate entry" error message. Feel free to continue using your
146 installation. If desired so, you could eliminate the case-duplicating rows
147 and re-apply the failed query.
148
149 *** Upgrading to 0.20.6 ***
150
151 New MGMT_PROTOS configuration option replaces the TELNET_OBJS_LISTSRC,
152 SSH_OBJS_LISTSRC and RDP_OBJS_LISTSRC options (converting existing settings as
153 necessary). MGMT_PROTOS allows to specify any management protocol for a
154 particular device list using a RackCode filter. The default value
155 ("ssh: {$typeid_4}, telnet: {$typeid_8}") produces "ssh://server.fqdn" for
156 servers and "telnet://switch.fqdn" for network switches.
157
158 *** Upgrading to 0.20.5 ***
159
160 This release introduces the VS groups feature. VS groups is a new way to store
161 and display virtual services configuration. There is a new "ipvs" (VS group)
162 realm. All previously existing VS configuration remains functional and user
163 is free to convert it to the new format, which displays it in a more natural way
164 and allows to generate virtual_server_group keepalived configs. To convert a
165 virtual service to the new format, it is necessary to manually create a VS group
166 object and assign IP addresses to it. The VS group will display a "Migrate" tab
167 to convert the old-style VS objects, which can be removed after a successful
168 conversion.
169
170 The old-style VS configuration becomes DEPRECATED. Its support will be removed
171 in a future major release. So it is strongly recommended to convert it to the
172 new format.
173
174 *** Upgrading to 0.20.4 ***
175
176 Please note that some dictionary items of Cisco Catalyst 2960 series switches
177 were renamed to meet official Cisco classification:
178 2960-48TT => 2960-48TT-L
179 2960-24TC => 2960-24TC-L
180 2960-24TT => 2960-24TT-L
181 2960-8TC => 2960-8TC-L
182 2960G-48TC => 2960G-48TC-L
183 2960G-24TC => 2960G-24TC-L
184 2960G-8TC => 2960G-8TC-L
185 C2960-24 => C2960-24-S
186 C2960G-24PC => C2960-24PC-L
187
188 The DATETIME_FORMAT configuration option used in setting date and time output
189 format now uses a different [1] syntax. During upgrade the option is reset to
190 the default value, which is now %Y-%m-%d (YYYY-MM-DD) per ISO 8601.
191
192 This release intoduces two new configuration options:
193 REVERSED_RACKS_LISTSRC and NEAREST_RACKS_CHECKBOX.
194
195 [1] http://php.net/manual/en/function.strftime.php
196
197 *** Upgrading to 0.20.1 ***
198
199 The 0.20.0 release includes bug which breaks IP networks' capacity displaying on
200 32-bit architecture machines. To fix this, this release makes use of PHP's BC
201 Math module. It is a new reqiurement. Most PHP distributions have this module
202 already enabled, but if yours does not - you need yo recompile PHP.
203
204 Security context of 'ipaddress' page now includes tags from the network
205 containing an IP address. This means that you should audit your permission rules
206 to check there is no unintended allows of changing IPs based on network's
207 tagset. Example:
208 allow {client network} and {New York}
209 This rule now not only allows any operation on NY client networks, but also any
210 operation with IP addresses included in those networks. To fix this, you should
211 change the rule this way:
212 allow {client network} and {New York} and not {$page_ipaddress}
213
214 *** Upgrading to 0.20.0 ***
215
216 WARNING: This release have too many internal changes, some of them were waiting
217 more than a year to be released. So this release is considered "BETA" and is
218 recommended only to curiuos users, who agree to sacrifice the stability to the
219 progress.
220
221 Racks and Rows are now stored in the database as Objects. The RackObject table
222 was renamed to Object. SQL views were created to ease the migration of custom
223 reports and scripts.
224
225 New plugins engine instead of local.php file. To make your own code stored in
226 local.php work, you must move the local.php file into the plugins/ directory.
227 The name of this file does not matter any more. You also can store multiple
228 files in that dir, separate your plugins by features, share them and try the
229 plugins from other people just placing them into plugins/ dir, no more merging.
230
231 $path_to_local_php variable has no special meaning any more.
232 $racktables_confdir variable is now used only to search for secret.php file.
233 $racktables_plugins_dir is a new overridable special variable pointing to
234 plugins/ directory.
235
236 Beginning with this version it is possible to delete IP prefixes, VLANs, Virtual
237 services and RS pools from within theirs properties tab. So please inspect your
238 permissions rules to assure there are no undesired allows for deletion of these
239 objects. To ensure this, you could try this code in the beginning of permissions
240 script:
241
242 allow {userid_1} and {$op_del}
243 deny {$op_del} and ({$tab_edit} or {$tab_properties})
244
245 Hardware gateways engine was rewritten in this version of RackTables. This means
246 that the file gateways/deviceconfig/switch.secrets.php is not used any more. To
247 get information about configuring connection properties and credentials in a new
248 way please visit http://wiki.racktables.org/index.php/Gateways
249
250 This also means that recently added features based on old API (D-Link switches
251 and Linux gateway support contributed by Ilya Evseev) are not working any more
252 and waiting to be forward-ported to new gateways API. Sorry for that.
253
254 Two new config variables appeared in this version:
255 - SEARCH_DOMAINS. Comma-separated list of DNS domains which are considered
256 "base" for your network. If RackTables search engine finds multiple objects
257 based on your search input, but there is only one which FQDN consists of
258 your input and one of these search domains, you will be redirected to this
259 object and other results will be discarded. Such behavior was unconditional
260 since 0.19.3, which caused many objections from users. So welcome this
261 config var.
262 - QUICK_LINK_PAGES. Comma-separated list of RackTables pages to display links
263 to them on top. Each user could have his own list.
264
265 Also some of config variables have changed their default values in this version.
266 This means that upgrade script will change their values if you have them in
267 previous default state. This could be inconvenient, but it is the most effective
268 way to encourage users to use new features. If this behavior is not what you
269 want, simply revert these variables' values:
270 - SHOW_LAST_TAB no => yes
271 - IPV4_TREE_SHOW_USAGE yes =>no (networks' usage is still available
272 by click)
273 - IPV4LB_LISTSRC {$typeid_4} => false
274 - FILTER_DEFAULT_ANDOR or => and (this implicitly enables the feature
275 of dynamic tree shrinking)
276 - FILTER_SUGGEST_EXTRA no => yes (yes, we have extra logical filters!)
277 - IPV4_TREE_RTR_AS_CELL yes => no (display routers as simple text, not
278 cell)
279
280 Also please note that variable IPV4_TREE_RTR_AS_CELL now has third special value
281 besides 'yes' and 'no': 'none'. Use 'none' value if you are experiencing low
282 performance on IP tree page. It will completely disable IP ranges scan for
283 used/spare IPs and the speed of IP tree will increase radically. The price is
284 you will not see the routers in IP tree at all.
285
286 *** Upgrading to 0.19.13 ***
287 A new "date" attribute type has been added. Existing date based fields ("HW
288 warranty expiration", "support contract expiration" and "SW warranty
289 expiration") will be converted to this new type but must be in the format
290 "mm/dd/yyyy" otherwise the conversion will fail.
291
292 *** Upgrading to 0.19.2 ***
293
294 This release is different in filesystem layout. The "gateways" directory has
295 been moved from "wwwroot" directory. This improves security a bit. You can also
296 separate your local settings and add-ons from the core RackTables code. To do
297 that, put a single index.php file into the DocumentRoot of your http server:
298
299 <?php
300 $racktables_confdir='/directory/with/secret.php/and/local.php/';
301 require '/directory_where_you_extracted_racktables_distro/wwwroot/index.php';
302 ?>
303
304 No more files are needed to be available directly over the HTTP. Full list of
305 filesystem paths which could be specified in custom index.php or secret.php:
306 $racktables_gwdir: path to the gateways directory;
307 $racktables_staticdir: path to the directory containing 'pix', 'js', 'css'
308 directories;
309 $racktables_confdir: path where secret.php and local.php are located. It is
310 not recommended to define it in secret.php, cause only
311 the path to local.php will be affected;
312 $path_to_secret_php: Ignore $racktables_confdir when locating secret.php and
313 use the specified path;
314 $path_to_local_php: idem for local.php.
315
316 *** Upgrading to 0.19.0 ***
317
318 The files, which are intended for the httpd (web-server) directory, are now in
319 the "wwwroot" directory of the tar.gz archive. Files outside of that directory
320 are not directly intended for httpd environment and should not be copied to the
321 server.
322
323 This release incorporates ObjectLog functionality, which used to be available as
324 a separate plugin. For the best results it is advised to disable (through
325 local.php) external ObjectLog plugin permanently before the new version is
326 installed. All previously accumulated ObjectLog records will be available
327 through the updated standard interface.
328
329 RackTables is now using PHP JSON extension which is included in the PHP core
330 since 5.2.0.
331
332 The barcode attribute was removed. The upgrade script attempts to preserve the
333 data by moving it to either the 'OEM S/N 1' attribute or to a Log entry. You
334 should backup your database beforehand anyway.
335
336 *** Upgrading to 0.18.x ***
337
338 RackTables from its version 0.18.0 and later is not compatible with RHEL/CentOS
339 (at least with versions up to 5.5) Linux distributions in their default
340 installation. There are yet options to work around that:
341 1. Install RackTables on a server with a different distribution/OS.
342 2. Request Linux distribution vendor to fix the bug with PCRE.
343 3. Repair your RHEL/CentOS installation yourself by fixing its PCRE
344 RPM as explained here: http://bugs.centos.org/view.php?id=3252