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