add Ubuntu-specific notes
[racktables] / README
CommitLineData
fedf925b
DO
1Thank you for selecting RackTables as your datacenter management solution!
2If you are looking for documentation or wish to send feedback, please
3look for the respective links at project's web-site (racktables.org).
de8695b2
DO
4
5*******************************************************
6* *
7* INSTALLING RACKTABLES *
8* *
9*******************************************************
10
fedf925b 11*** I. SERVER ***
de8695b2 12
fedf925b 13RackTables requires a MySQL server version 5.x built with InnoDB and
cd183ce0
MS
14Unicode support and configured appropriately. By default RackTables is
15developed on Apache httpd with PHP 5 module and several PHP extensions.
16Below is a list of known-good distributions with respective setup notes.
3ebdbeed 17
570f1df4 18*** Fedora 8-16
fedf925b 19* MySQL: yum install mysql-server mysql
65ccc533
DO
20* Apache/PHP: yum install httpd php php-mysql php-pdo php-gd php-snmp \
21 php-mbstring php-bcmath
fedf925b 22* To enable Unicode, add "character-set-server=utf8" line to "[mysqld]"
13e458dc 23 section of "/etc/my.cnf" file and restart mysqld.
3ebdbeed 24
e8be2f81
DO
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]"
13e458dc 29 section of "/etc/mysql/my.cnf" file and restart mysqld.
e8be2f81 30
cd183ce0
MS
31*** Debian 7 with nginx
32* MySQL: aptitude install mysql-server-5.1
33* nginx: aptitude install nginx php5-fpm
13e458dc
DO
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.
cd183ce0 41* To enable Unicode, add "character-set-server=utf8" line to "[mysqld]"
13e458dc 42 section of "/etc/mysql/my.cnf" file and restart mysqld.
cd183ce0 43
70234bb5
DO
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
fedf925b
DO
55*** ALTLinux 4.0
56* MySQL: apt-get install MySQL-server
57* Apache/PHP: apt-get install apache2-httpd-prefork php5-gd2 \
13e458dc 58 php5-pdo_mysql php5-pdo apache2-mod_php5 php5-mbstring
fedf925b 59* To enable Unicode, add "CHSET=utf8" line to "/etc/sysconfig/mysqld" file
13e458dc 60 and restart mysqld.
fedf925b
DO
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,
13e458dc 65 php5-mysql, php5-bcmath, php5-snmp and php5-ldap
fedf925b 66* To enable Unicode, add "default-character-set=utf8" line to "[mysql]"
13e458dc 67 section of "/etc/my.cnf" file and restart mysqld.
fedf925b 68
1c433d1e
DO
69*** Scientific Linux 6
70* MySQL: yum install mysql-server mysql
9dedb20f 71* Apache/PHP: httpd php php-mysql php-pdo php-gd php-mbstring php-bcmath
36492caa 72* To enable Unicode, add "character-set-server=utf8" line to "[mysqld]"
13e458dc 73 section of "/etc/my.cnf" file and restart mysqld.
36492caa
DO
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
1c433d1e 79* To enable Unicode, add "character-set-server=utf8" line to "[mysqld]"
13e458dc 80 section of "/etc/my.cnf" file and restart mysqld.
1c433d1e 81
fedf925b
DO
82*** FreeBSD 8
83* Apache/PHP:
a3bce64d
DO
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
c20f01f4
DO
91# make -C /usr/ports/devel/pcre install
92!!! Enable UTF-8 support ............ : yes
93!!! Unicode properties .............. : yes
a3bce64d
DO
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
d3372430 100
fedf925b 101*** II. FILES ***
b8433971
DO
102Unpack the tar.gz/zip archive to a directory of your choice and configure Apache
103httpd to use "wwwroot" subdirectory as a new DocumentRoot. Alternatively,
104symlinks to "wwwroot" or even to "index.php" from an existing DocumentRoot are
105also possible and often adisable (see README.Fedora).
c2d46542 106
fedf925b 107*** III. INSTALLER ***
b8433971 108Open the configured RackTables URL and you will be prompted to configure
fedf925b 109and initialize the application.
c2d46542 110
de8695b2
DO
111*******************************************************
112* *
113* UPGRADING RACKTABLES *
114* *
115*******************************************************
b8433971
DO
116
1170. BACKUP YOUR DATABASE and check the release notes below before actually
118 starting the upgrade.
1191. Remove all existing files except configuration (the "inc/secret.php" file)
120 and local plugins (in the "plugins" directory).
1212. Put the contents of the new tar.gz/zip archive into the place.
1223. 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
d3372430 124 the upgrade.
b8433971 1254. Do that and report any errors to the bug tracker or the mailing list.
7fc5565c 126
c2d46542
DO
127*******************************************************
128* *
129* RELEASE NOTES *
130* *
131*******************************************************
132
25355e1d
AD
133*** Upgrading to 0.20.7 ***
134
ae9ada40
DO
135From now on the minimum (oldest) release of PHP that can run RackTables is
1365.2.10. In particular, to continue running RackTables on CentOS 5 it is
137necessary to replace its php* RPM packages with respective php53* packages
138before the upgrade (except the JSON package, which PHP 5.3 provides internally).
139
7740234b
AD
140Database triggers are used for some data consistency measures. The database
141user account must have the 'TRIGGER' privilege, which was introduced in
142MySQL 5.1.7.
143
25355e1d
AD
144The IPV4OBJ_LISTSRC configuration option is reset to an expression which enables
145the IP addressing feature for all object types except those listed.
146
23e52760
AA
147Tags could now be assigned on the Edit/Properties tab using a text input with
148auto-completion. Type a star '*' to view full tag tree in auto-complete menu.
149It is worth to add the following line to the permissions script if the
150old-fashioned 'Tags' tab is not needed any more:
151 deny {$tab_tags} # this hides 'Tags' tab
152
b4bc5582
TU
153This release converts collation of all DB fields to the utf8_unicode_ci. This
154procedure may take some time, and could fail if there are rows that differ only
155by letter case. If this happen, you'll see the failed SQL query in upgrade report
156with the "Duplicate entry" error message. Feel free to continue using your
157installation. If desired so, you could eliminate the case-duplicating rows
158and re-apply the failed query.
159
ceebebb9 160*** Upgrading to 0.20.6 ***
a7390942 161
b8433971
DO
162New MGMT_PROTOS configuration option replaces the TELNET_OBJS_LISTSRC,
163SSH_OBJS_LISTSRC and RDP_OBJS_LISTSRC options (converting existing settings as
164necessary). MGMT_PROTOS allows to specify any management protocol for a
165particular device list using a RackCode filter. The default value
166("ssh: {$typeid_4}, telnet: {$typeid_8}") produces "ssh://server.fqdn" for
167servers and "telnet://switch.fqdn" for network switches.
fd3ef4e7 168
eacc0983
AA
169*** Upgrading to 0.20.5 ***
170
171This release introduces the VS groups feature. VS groups is a new way to store
b8433971
DO
172and display virtual services configuration. There is a new "ipvs" (VS group)
173realm. All previously existing VS configuration remains functional and user
174is free to convert it to the new format, which displays it in a more natural way
175and allows to generate virtual_server_group keepalived configs. To convert a
176virtual service to the new format, it is necessary to manually create a VS group
177object and assign IP addresses to it. The VS group will display a "Migrate" tab
178to convert the old-style VS objects, which can be removed after a successful
179conversion.
180
181The old-style VS configuration becomes DEPRECATED. Its support will be removed
182in a future major release. So it is strongly recommended to convert it to the
183new format.
eacc0983 184
ef550f27
AA
185*** Upgrading to 0.20.4 ***
186
65ccc533
DO
187Please note that some dictionary items of Cisco Catalyst 2960 series switches
188were renamed to meet official Cisco classification:
ef550f27
AA
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
2a943f85
DO
199The DATETIME_FORMAT configuration option used in setting date and time output
200format now uses a different [1] syntax. During upgrade the option is reset to
201the default value, which is now %Y-%m-%d (YYYY-MM-DD) per ISO 8601.
202
a7192a34
AA
203This release intoduces two new configuration options:
204REVERSED_RACKS_LISTSRC and NEAREST_RACKS_CHECKBOX.
205
2a943f85 206[1] http://php.net/manual/en/function.strftime.php
ef550f27 207
038739ac
AA
208*** Upgrading to 0.20.1 ***
209
65ccc533
DO
210The 0.20.0 release includes bug which breaks IP networks' capacity displaying on
21132-bit architecture machines. To fix this, this release makes use of PHP's BC
212Math module. It is a new reqiurement. Most PHP distributions have this module
213already enabled, but if yours does not - you need yo recompile PHP.
d76549bc 214
65ccc533
DO
215Security context of 'ipaddress' page now includes tags from the network
216containing an IP address. This means that you should audit your permission rules
217to check there is no unintended allows of changing IPs based on network's
218tagset. Example:
038739ac 219 allow {client network} and {New York}
65ccc533
DO
220This rule now not only allows any operation on NY client networks, but also any
221operation with IP addresses included in those networks. To fix this, you should
222change the rule this way:
038739ac
AA
223 allow {client network} and {New York} and not {$page_ipaddress}
224
9b8174d7
AD
225*** Upgrading to 0.20.0 ***
226
65ccc533
DO
227WARNING: This release have too many internal changes, some of them were waiting
228more than a year to be released. So this release is considered "BETA" and is
229recommended only to curiuos users, who agree to sacrifice the stability to the
230progress.
d1a9e5cf
AA
231
232Racks and Rows are now stored in the database as Objects. The RackObject table
233was renamed to Object. SQL views were created to ease the migration of custom
9b8174d7
AD
234reports and scripts.
235
65ccc533
DO
236New plugins engine instead of local.php file. To make your own code stored in
237local.php work, you must move the local.php file into the plugins/ directory.
238The name of this file does not matter any more. You also can store multiple
239files in that dir, separate your plugins by features, share them and try the
240plugins from other people just placing them into plugins/ dir, no more merging.
241
d1a9e5cf 242$path_to_local_php variable has no special meaning any more.
dd14756b 243$racktables_confdir variable is now used only to search for secret.php file.
65ccc533
DO
244$racktables_plugins_dir is a new overridable special variable pointing to
245 plugins/ directory.
dd14756b 246
65ccc533
DO
247Beginning with this version it is possible to delete IP prefixes, VLANs, Virtual
248services and RS pools from within theirs properties tab. So please inspect your
249permissions rules to assure there are no undesired allows for deletion of these
250objects. To ensure this, you could try this code in the beginning of permissions
251script:
d1a9e5cf
AA
252
253 allow {userid_1} and {$op_del}
254 deny {$op_del} and ({$tab_edit} or {$tab_properties})
255
65ccc533
DO
256Hardware gateways engine was rewritten in this version of RackTables. This means
257that the file gateways/deviceconfig/switch.secrets.php is not used any more. To
258get information about configuring connection properties and credentials in a new
259way please visit http://wiki.racktables.org/index.php/Gateways
d1a9e5cf 260
65ccc533
DO
261This also means that recently added features based on old API (D-Link switches
262and Linux gateway support contributed by Ilya Evseev) are not working any more
263and waiting to be forward-ported to new gateways API. Sorry for that.
d1a9e5cf
AA
264
265Two new config variables appeared in this version:
65ccc533
DO
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.
d1a9e5cf
AA
275
276Also some of config variables have changed their default values in this version.
65ccc533
DO
277This means that upgrade script will change their values if you have them in
278previous default state. This could be inconvenient, but it is the most effective
279way to encourage users to use new features. If this behavior is not what you
280want, simply revert these variables' values:
d1a9e5cf 281 - SHOW_LAST_TAB no => yes
65ccc533
DO
282 - IPV4_TREE_SHOW_USAGE yes =>no (networks' usage is still available
283 by click)
d1a9e5cf 284 - IPV4LB_LISTSRC {$typeid_4} => false
65ccc533
DO
285 - FILTER_DEFAULT_ANDOR or => and (this implicitly enables the feature
286 of dynamic tree shrinking)
d1a9e5cf 287 - FILTER_SUGGEST_EXTRA no => yes (yes, we have extra logical filters!)
65ccc533
DO
288 - IPV4_TREE_RTR_AS_CELL yes => no (display routers as simple text, not
289 cell)
d1a9e5cf
AA
290
291Also please note that variable IPV4_TREE_RTR_AS_CELL now has third special value
65ccc533
DO
292besides 'yes' and 'no': 'none'. Use 'none' value if you are experiencing low
293performance on IP tree page. It will completely disable IP ranges scan for
294used/spare IPs and the speed of IP tree will increase radically. The price is
295you will not see the routers in IP tree at all.
7ec03062 296
86ff26ae 297*** Upgrading to 0.19.13 ***
65ccc533
DO
298A new "date" attribute type has been added. Existing date based fields ("HW
299warranty expiration", "support contract expiration" and "SW warranty
86ff26ae
DO
300expiration") will be converted to this new type but must be in the format
301"mm/dd/yyyy" otherwise the conversion will fail.
302
36efe434
DO
303*** Upgrading to 0.19.2 ***
304
65ccc533
DO
305This release is different in filesystem layout. The "gateways" directory has
306been moved from "wwwroot" directory. This improves security a bit. You can also
307separate your local settings and add-ons from the core RackTables code. To do
308that, put a single index.php file into the DocumentRoot of your http server:
4f5aea8a
AA
309
310<?php
65ccc533 311$racktables_confdir='/directory/with/secret.php/and/local.php/';
4f5aea8a
AA
312require '/directory_where_you_extracted_racktables_distro/wwwroot/index.php';
313?>
314
65ccc533
DO
315No more files are needed to be available directly over the HTTP. Full list of
316filesystem paths which could be specified in custom index.php or secret.php:
4f5aea8a 317 $racktables_gwdir: path to the gateways directory;
65ccc533
DO
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;
4f5aea8a 325 $path_to_local_php: idem for local.php.
36efe434 326
841a5b54 327*** Upgrading to 0.19.0 ***
6f542dde 328
65ccc533
DO
329The files, which are intended for the httpd (web-server) directory, are now in
330the "wwwroot" directory of the tar.gz archive. Files outside of that directory
331are not directly intended for httpd environment and should not be copied to the
332server.
65e557dd 333
65ccc533
DO
334This release incorporates ObjectLog functionality, which used to be available as
335a separate plugin. For the best results it is advised to disable (through
336local.php) external ObjectLog plugin permanently before the new version is
337installed. All previously accumulated ObjectLog records will be available
338through the updated standard interface.
8489d2af 339
65ccc533
DO
340RackTables is now using PHP JSON extension which is included in the PHP core
341since 5.2.0.
841a5b54 342
65ccc533
DO
343The barcode attribute was removed. The upgrade script attempts to preserve the
344data by moving it to either the 'OEM S/N 1' attribute or to a Log entry. You
345should backup your database beforehand anyway.
81659c05 346
1679ddbd
DO
347*** Upgrading to 0.18.x ***
348
65ccc533
DO
349RackTables 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
351installation. There are yet options to work around that:
1679ddbd
DO
3521. Install RackTables on a server with a different distribution/OS.
3532. Request Linux distribution vendor to fix the bug with PCRE.
3543. Repair your RHEL/CentOS installation yourself by fixing its PCRE
65ccc533 355 RPM as explained here: http://bugs.centos.org/view.php?id=3252