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