renderMuninServersEditor(): reformat some code
[racktables] / README.md
CommitLineData
2797f2c7
DO
1# Welcome!
2Thank you for selecting RackTables as your datacenter management solution!
3If you are looking for documentation or wish to send feedback, please
4look for the respective links at [project's web-site](http://racktables.org).
5
fde823aa
DO
6# How to install RackTables
7
8## 1. Prepare the server
9
10RackTables uses a web-server with PHP (5.2.10 or newer) for front-end and a
11MySQL/MariaDB server version 5 for back-end. The most commonly used web-server
12for RackTables is Apache httpd.
13
14### 1.1. Install MySQL server
15
16| Distribution | How to do |
17| ------------------ | ----------------------------------------------------------------------- |
18| ALTLinux 4.0 | `apt-get install MySQL-server` |
19| CentOS 5 | `yum install mysql-server mysql` |
20| Debian 6 | `aptitude install mysql-server-5.1` |
21| Debian 7 | `aptitude install mysql-server-5.1` |
22| Fedora 8-16 | `yum install mysql-server mysql` |
23| Fedora 23 | `dnf install mariadb-server mariadb` |
3425beb7 24| FreeBSD 10 | `pkg install mysql56-server` |
fde823aa 25| openSUSE 11.0 | YaST -> Software -> software management -> Web and LAMP server -> mysql |
38fd042d 26| openSUSE 42.1 | `zypper install mysql-community-server` |
fde823aa
DO
27| Scientific Linux 6 | `yum install mysql-server mysql` |
28| Ubuntu 14.04 | `apt-get install mysql-server` |
a4b869c7 29| Ubuntu 16.04 | `apt-get install mysql-server` |
fde823aa
DO
30
31### 1.2. Enable Unicode in the MySQL server
32
33| Distribution | How to do |
34| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
35| ALTLinux 4.0 | add `CHSET=utf8` line to `/etc/sysconfig/mysqld` file and restart mysqld |
36| CentOS 5 | add `character-set-server=utf8` line to `[mysqld]` section of `/etc/my.cnf` file and restart mysqld |
37| Debian 6 | add `character-set-server=utf8` line to `[mysqld]` section of `/etc/mysql/my.cnf` file and restart mysqld |
38| Debian 7 | add `character-set-server=utf8` line to `[mysqld]` section of `/etc/mysql/my.cnf` file and restart mysqld |
39| Fedora 8-16 | add `character-set-server=utf8` line to `[mysqld]` section of `/etc/my.cnf` file and restart mysqld |
40| Fedora 23 | ```printf "[mysqld]\ncharacter-set-server=utf8\n" > /etc/my.cnf.d/mysqld-charset.cnf; systemctl restart mariadb``` |
41| openSUSE 11.0 | add `default-character-set=utf8` line to `[mysql]` section of `/etc/my.cnf` file and restart mysqld |
38fd042d 42| openSUSE 42.1 | No action required, comes configured for UTF-8 by default. |
fde823aa
DO
43| Scientific Linux 6 | add `character-set-server=utf8` line to `[mysqld]` section of `/etc/my.cnf` file and restart mysqld |
44| Ubuntu 14.04 | ```printf "[mysqld]\ncharacter-set-server=utf8\n" > /etc/mysql/conf.d/charset.cnf; service mysql restart``` |
a4b869c7 45| Ubuntu 16.04 | ```printf "[mysqld]\ncharacter-set-server=utf8\n" > /etc/mysql/conf.d/charset.cnf; service mysql restart``` |
fde823aa
DO
46
47### 1.3. Install PHP and Apache httpd (or nginx)
48
49| Distribution | How to do |
50| ------------------ | ------------------------------------------------------------------------------------ |
d32867b3
DO
51| ALTLinux 4.0 | `apt-get install apache2-httpd-prefork php5-gd2 php5-pdo_mysql php5-pdo apache2-mod_php5 php5-mbstring`
52| CentOS 5 | `yum install httpd php53 php53-mysql php53-pdo php53-gd php53-mbstring php53-bcmath` |
fde823aa
DO
53| Debian 6 | `aptitude install libapache2-mod-php5 php5-gd php5-mysql php5-snmp` |
54| Debian 7 (nginx) | `aptitude install nginx php5-fpm` **(see note below)** |
d32867b3
DO
55| Fedora 8-16 | `yum install httpd php php-mysql php-pdo php-gd php-snmp php-mbstring php-bcmath` |
56| Fedora 23 | `dnf install httpd php php-mysql php-pdo php-gd php-snmp php-mbstring php-bcmath` |
57| FreeBSD 8 | see note below |
3425beb7 58| FreeBSD 10 | see note 1.3.c |
fde823aa 59| openSUSE 11.0 | use YaST to install apache2-mod_php5, php5-gd, php5-mbstring, php5-mysql, php5-bcmath, php5-snmp and php5-ldap
38fd042d 60| openSUSE 42.1 | `zypper install apache2-mod_php5 php5-gd php5-mbstring php5-mysql php5-bcmath` |
fde823aa 61| Scientific Linux 6 | `yum install httpd php php-mysql php-pdo php-gd php-mbstring php-bcmath` |
d32867b3 62| Ubuntu 14.04 | `apt-get install apache2-bin libapache2-mod-php5 php5-gd php5-mysql php5-snmp` |
e5c4b20b 63| Ubuntu 16.04 | `apt-get install apache2-bin libapache2-mod-php7.0 php7.0-gd php7.0-mysql php7.0-mbstring php7.0-bcmath php7.0-json php7.0-snmp`
fde823aa
DO
64
65#### 1.3.a. Debian 7 with nginx
2797f2c7
DO
66Remember to adjust `server_name` in `server {}` section, otherwise your logout link
67will point to localhost (and thus fail).
68Notice, that fpm.sock is advised, keep the rest on default configuration, or
69tweak to your needs. You may need to set `fastcgi_read_timeout 600;` if you use
70some external addons like fping, which may take some time in certain situations.
71Please note that setting aggresive caching for php scripts may result in stale
72content - so maximum of 60 seconds is advised, but by default it is not enabled.
73
fde823aa 74#### 1.3.b. FreeBSD 8
2797f2c7
DO
75```
76# make -C /usr/ports/www/apache13-modssl install
77# make -C /usr/ports/www/php5-session install
78[X] CLI Build CLI version
79[X] APACHE Build Apache module
80[X] MULTIBYTE Enable zend multibyte support
81# make -C /usr/ports/graphics/php5-gd install
82# make -C /usr/ports/databases/php5-pdo_mysql install
83# make -C /usr/ports/devel/pcre install
84!!! Enable UTF-8 support ............ : yes
85!!! Unicode properties .............. : yes
86# make -C /usr/ports/devel/php5-pcre install
87# make -C /usr/ports/converters/php5-mbstring install
88[X] REGEX Enable multibyte regex support
89
90# make -C /usr/ports/net-mgmt/php5-snmp install
91# make -C /usr/ports/net/php5-ldap install
92```
93
3425beb7 94#### 1.3.c. FreeBSD
95There are 3 different ways how you can install RackTables and its dependencies on FreeBSD.
96
97######A. use pkg (Binary Package Management) ( not always the newest version )
98```
99# pkg install racktables
100# pkg install mod_php56 mysql56-server
101```
102As of May 2016 this will install RackTables Version 0.20.10 and its dependencies ( php 5.6, mysql-server 5.6 and apache 2.4)
103
104######B. use the ports system ( possibly more recent than pkg )
105```
106# cd /usr/ports/sysutils/racktables
107# make install
108# pkg install mod_php56 mysql56-server
109```
110As of May 2016 this will install RackTables Version 0.20.11 and build and install its dependencies ( php 5.6, mysql-server 5.6 and apache 2.4)
111
112######C. manual ( newest version )
113Install dependencies with pkg:
114```
115# pkg install php70-bcmath php70-curl php70-filter php70-gd php70-gmp php70-json php70-mbstring php70-openssl php70-pdo php70-pdo_mysql php70-session php70-simplexml php70-snmp php70-sockets
510ae82b 116# pkg install mod_php70 mysql56-server
3425beb7 117```
118
119unpack tar.gz/zip archive to /usr/local/www
120
121symblink racktables dir
122```
123# cd /usr/local/www
124# ln -s RackTables-0.20.xx racktables
125```
126
127##### Common install steps
128Apache users should create a racktables.conf file under their apache
129Includes directory with the following contents:
130```
131AddType application/x-httpd-php .php
132AddType application/x-httpd-php-source .phps
133
134<Directory /usr/local/www/racktables/wwwroot>
135 DirectoryIndex index.php
136 Require all granted
137</Directory>
138Alias /racktables /usr/local/www/racktables/wwwroot
139```
140
141Start services:
142```
143#echo 'apache24_enable="YES"' >> /etc/rc.conf
144#service apache24 start
145
146#echo 'mysql_enable="YES"' >> /etc/rc.conf
147#service mysql-server start
148```
149
0ed66a4d 150Browse to http://address.to.your.server/racktables/index.php and follow the instructions.
3425beb7 151
152Note: set secret.php permissions when prompted.
153```
154# chown www:www /usr/local/www/racktables/wwwroot/inc/secret.php
155# chmod 400 /usr/local/www/racktables/wwwroot/inc/secret.php
156```
157
158
fde823aa 159## 2. Copy the files
2797f2c7
DO
160Unpack the tar.gz/zip archive to a directory of your choice and configure Apache
161httpd to use `wwwroot` subdirectory as a new DocumentRoot. Alternatively,
162symlinks to `wwwroot` or even to `index.php` from an existing DocumentRoot are
163also possible and often adisable (see `README.Fedora`).
164
fde823aa 165## 3. Run the installer
2797f2c7
DO
166Open the configured RackTables URL and you will be prompted to configure
167and initialize the application.
168
8c5b4ba3
DO
169| Distribution | Apache httpd UID:GID | MySQL UNIX socket path |
170| --------------- | ----------------------- | -------------------------------- |
171| Fedora 23 | `apache:apache` | `/var/lib/mysql/mysql.sock` |
38fd042d 172| openSUSE 42.1 | `wwwrun:www` | `/var/run/mysql/mysql.sock` |
8c5b4ba3 173| Ubuntu 14.04 | `www-data:www-data` | `/var/run/mysqld/mysqld.sock` |
d1c79f04 174| Ubuntu 16.04 | `www-data:www-data` | `/var/run/mysqld/mysqld.sock` |
8c5b4ba3 175
fde823aa 176# How to upgrade RackTables
2797f2c7
DO
177
1780. **Backup your database** and check the release notes below before actually
179 starting the upgrade.
1801. Remove all existing files except configuration (the `inc/secret.php` file)
181 and local plugins (in the `plugins/` directory).
1822. Put the contents of the new tar.gz/zip archive into the place.
1833. Open the RackTables page in a browser. The software will detect version
184 mismatch and display a message telling to log in as admin to finish
185 the upgrade.
1864. Do that and report any errors to the bug tracker or the mailing list.
187
188## Release notes
189
c5c39ee5
AA
190### Upgrading to 0.20.11
191
d40d136a 192New `IPV4_TREE_SHOW_UNALLOCATED` configuration option introduced to disable
c5c39ee5 193dsplaying unallocated networks in IPv4 space tree. Setting it also disables
e1e193fe 194the "knight" feature.
c5c39ee5 195
2797f2c7
DO
196### Upgrading to 0.20.7
197
198From now on the minimum (oldest) release of PHP that can run RackTables is
1995.2.10. In particular, to continue running RackTables on CentOS 5 it is
200necessary to replace its php* RPM packages with respective php53* packages
201before the upgrade (except the JSON package, which PHP 5.3 provides internally).
202
203Database triggers are used for some data consistency measures. The database
204user account must have the 'TRIGGER' privilege, which was introduced in
205MySQL 5.1.7.
206
207The `IPV4OBJ_LISTSRC` configuration option is reset to an expression which enables
208the IP addressing feature for all object types except those listed.
209
210Tags could now be assigned on the Edit/Properties tab using a text input with
211auto-completion. Type a star '*' to view full tag tree in auto-complete menu.
212It is worth to add the following line to the permissions script if the
213old-fashioned 'Tags' tab is not needed any more:
214```
215 deny {$tab_tags} # this hides 'Tags' tab
216```
217
218This release converts collation of all DB fields to the `utf8_unicode_ci`. This
219procedure may take some time, and could fail if there are rows that differ only
220by letter case. If this happen, you'll see the failed SQL query in upgrade report
221with the "Duplicate entry" error message. Feel free to continue using your
222installation. If desired so, you could eliminate the case-duplicating rows
223and re-apply the failed query.
224
225### Upgrading to 0.20.6
226
227New `MGMT_PROTOS` configuration option replaces the `TELNET_OBJS_LISTSRC`,
228`SSH_OBJS_LISTSRC` and `RDP_OBJS_LISTSRC` options (converting existing settings as
229necessary). `MGMT_PROTOS` allows to specify any management protocol for a
230particular device list using a RackCode filter. The default value
231(`ssh: {$typeid_4}, telnet: {$typeid_8}`) produces `ssh://server.fqdn` for
232servers and `telnet://switch.fqdn` for network switches.
233
234### Upgrading to 0.20.5
235
236This release introduces the VS groups feature. VS groups is a new way to store
237and display virtual services configuration. There is a new "ipvs" (VS group)
238realm. All previously existing VS configuration remains functional and user
239is free to convert it to the new format, which displays it in a more natural way
240and allows to generate virtual_server_group keepalived configs. To convert a
241virtual service to the new format, it is necessary to manually create a VS group
242object and assign IP addresses to it. The VS group will display a "Migrate" tab
243to convert the old-style VS objects, which can be removed after a successful
244conversion.
245
246The old-style VS configuration becomes **deprecated**. Its support will be removed
247in a future major release. So it is strongly recommended to convert it to the
248new format.
249
250### Upgrading to 0.20.4
251
252Please note that some dictionary items of Cisco Catalyst 2960 series switches
253were renamed to meet official Cisco classification:
254
255old name | new name
256------------|---------
2572960-48TT | 2960-48TT-L
2582960-24TC | 2960-24TC-L
2592960-24TT | 2960-24TT-L
2602960-8TC | 2960-8TC-L
2612960G-48TC | 2960G-48TC-L
2622960G-24TC | 2960G-24TC-L
2632960G-8TC | 2960G-8TC-L
264C2960-24 | C2960-24-S
265C2960G-24PC | C2960-24PC-L
266
267The `DATETIME_FORMAT` configuration option used in setting date and time output
268format now uses a [different](http://php.net/manual/en/function.strftime.php)
269syntax. During upgrade the option is reset to
270the default value, which is now %Y-%m-%d (YYYY-MM-DD) per ISO 8601.
271
272This release intoduces two new configuration options:
273`REVERSED_RACKS_LISTSRC` and `NEAREST_RACKS_CHECKBOX`.
274
275### Upgrading to 0.20.1
276
277The 0.20.0 release includes bug which breaks IP networks' capacity displaying on
27832-bit architecture machines. To fix this, this release makes use of PHP's BC
279Math module. It is a new reqiurement. Most PHP distributions have this module
280already enabled, but if yours does not - you need yo recompile PHP.
281
282Security context of 'ipaddress' page now includes tags from the network
283containing an IP address. This means that you should audit your permission rules
284to check there is no unintended allows of changing IPs based on network's
285tagset. Example:
286```
287 allow {client network} and {New York}
288```
289This rule now not only allows any operation on NY client networks, but also any
290operation with IP addresses included in those networks. To fix this, you should
291change the rule this way:
292```
293 allow {client network} and {New York} and not {$page_ipaddress}
294```
295
296### Upgrading to 0.20.0
297
298WARNING: This release have too many internal changes, some of them were waiting
299more than a year to be released. So this release is considered "BETA" and is
300recommended only to curiuos users, who agree to sacrifice the stability to the
301progress.
302
303Racks and Rows are now stored in the database as Objects. The RackObject table
304was renamed to Object. SQL views were created to ease the migration of custom
305reports and scripts.
306
307New plugins engine instead of `local.php` file. To make your own code stored in
308`local.php` work, you must move the `local.php` file into the `plugins/` directory.
309The name of this file does not matter any more. You also can store multiple
310files in that dir, separate your plugins by features, share them and try the
311plugins from other people just placing them into `plugins/` dir, no more merging.
312
313* `$path_to_local_php` variable has no special meaning any more.
314* `$racktables_confdir` variable is now used only to search for `secret.php` file.
315* `$racktables_plugins_dir` is a new overridable special variable pointing to `plugins/` directory.
316
317Beginning with this version it is possible to delete IP prefixes, VLANs, Virtual
318services and RS pools from within theirs properties tab. So please inspect your
319permissions rules to assure there are no undesired allows for deletion of these
320objects. To ensure this, you could try this code in the beginning of permissions
321script:
322```
323allow {userid_1} and {$op_del}
324deny {$op_del} and ({$tab_edit} or {$tab_properties})
325```
326
327Hardware gateways engine was rewritten in this version of RackTables. This means
328that the file `gateways/deviceconfig/switch.secrets.php` is not used any more. To
329get information about configuring connection properties and credentials in a new
330way please read [this](http://wiki.racktables.org/index.php/Gateways).
331
332This also means that recently added features based on old API (D-Link switches
333and Linux gateway support contributed by Ilya Evseev) are not working any more
334and waiting to be forward-ported to new gateways API. Sorry for that.
335
336Two new config variables appeared in this version:
337 - `SEARCH_DOMAINS`. Comma-separated list of DNS domains which are considered
338 "base" for your network. If RackTables search engine finds multiple objects
339 based on your search input, but there is only one which FQDN consists of
340 your input and one of these search domains, you will be redirected to this
341 object and other results will be discarded. Such behavior was unconditional
342 since 0.19.3, which caused many objections from users. So welcome this
343 config var.
344 - `QUICK_LINK_PAGES`. Comma-separated list of RackTables pages to display links
345 to them on top. Each user could have his own list.
346
347Also some of config variables have changed their default values in this version.
348This means that upgrade script will change their values if you have them in
349previous default state. This could be inconvenient, but it is the most effective
350way to encourage users to use new features. If this behavior is not what you
351want, simply revert these variables' values:
352
353variable | old | new | comment
354------------------------|-------------|-------|--------
355`SHOW_LAST_TAB` | no | yes
356`IPV4_TREE_SHOW_USAGE` | yes | no | Networks' usage is still available by click.
357`IPV4LB_LISTSRC` | {$typeid_4} | false
358`FILTER_DEFAULT_ANDOR` | or | and | This implicitly enables the feature of dynamic tree shrinking.
359`FILTER_SUGGEST_EXTRA` | no | yes | Yes, we have extra logical filters!
360`IPV4_TREE_RTR_AS_CELL` | yes | no | Display routers as simple text, not cell.
361
362Also please note that variable `IPV4_TREE_RTR_AS_CELL` now has third special value
363besides 'yes' and 'no': 'none'. Use 'none' value if you are experiencing low
364performance on IP tree page. It will completely disable IP ranges scan for
365used/spare IPs and the speed of IP tree will increase radically. The price is
366you will not see the routers in IP tree at all.