# install.pod - Torrus installation instructions # Copyright (C) 2002 Stanislav Sinyagin # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. # $Id: install.pod.in,v 1.1 2010-12-27 00:04:36 ivan Exp $ # Stanislav Sinyagin # # =head1 Torrus Installation Instructions =head2 Required Software =over 4 =item * Operating System Any UNIX-like operation system where the required components are working. The author's primary development platform is Cygwin Ehttp://www.cygwin.comE, and the primary testing environments are Sun Solaris/SPARC and FreeBSD. Note to B users: as recommended by Gord Philpott, Linux kernel for guest machine needs to be compiled with the following feature enabled: C Enhanced Real Time Clock Support>. For other guest operating systems (e.g. FreeBSD), in order to let the Torrus collector and monitor run properly, you need to add the following lines to your F: $Torrus::Scheduler::maxSleepTime = 15; $Torrus::Scheduler::ignoreClockSkew = 1; # B package is maintained by Jurij Smakov and is available at # Ehttp://pkg-torrus.alioth.debian.orgE. =item * Perl Perl version C<5.8.1> or higher is required. B is not recommended> because of memory access bugs and unpredictable behaviour. Perl interpreter should be in PATH environment variable when running C<./configure>, otherwise use ./configure PERL=/path/to/perl Torrus also supports Perl multithreading in Device Discovery engine and in the Collector. Minimum requirements are as follows: Perl version 5.8.8 or higher, C module version 1.41 or higher, C module version 1.03 or higher. Older versions had bugs that were leading to severe memory leaks and instability. After installing Perl 5.8.8, you need to upgrade the C and C modules manually from CPAN. If any of the requirements is not met, the installer will automatically disable the threads support in Torrus. =item * RRDtool Round Robin Database Tool is available at: Ehttp://ee-staff.ethz.ch/~oetiker/webtools/rrdtool/E. Both stable version C<1.0.x> and the development version C<1.1.x> are supported. As of this writing, rrdtool version C<1.1.x> is still in its development stage, but it is quite ready for using in production environments. There's a small glitch in legend text alignment, and it will hopefully be fixed. =item * libxml2 libxml2 is the XML parser library from Gnome project Ehttp://www.gnome.orgE, available as a standalone package. Versions C<2.4.23> and above were tested. =item * Berkeley DB version 4.2.52 or later There are two distinct packages with slightly conflicting names: The Berkeley DB from Sleepycat Software Ehttp://www.sleepycat.comE, and C Perl module available from CPAN. We will always refer the latter as I. The Berkeley DB database engine is used for all data storage. Versions C<4.2.52> and above are recommended. Older versions of Berkeley DB had problems with database integrity in concurrent usage. By default, it installs into F. Unfortunately, the BerkeleyDB Perl module cannot find the include and library files in that directory. Thus either configure Berkeley DB with the option C<--prefix=/usr/local>, or you need to edit F in BerkeleyDB Perl module distribution. =item * HTTP Server Torrus requires an HTTP server. It is compatible with the following combinations: =over 8 =item * Apache 1.3 with mod_perl 1.0 =item * Apache 2.x with mod_perl 2.0 =item * lighttpd with FastCGI =item * Apache with FastCGI =back FastCGI is supported in Torrus version 1.0.9 or higher. B Starting from Torrus version 1.0.9, C is no longer required. See I for details on HTTP server configuration. =item * Perl Modules The Perl modules required are listed below. They are all available at CPAN Ehttp://www.cpan.orgE. Some of them require other modules to be installed. You can install all required modules with the following command, executed from within the distribution directory: perl -I `pwd`/setup_tools -MCPAN -e 'install Bundle::Torrus' =over 8 =item * XML::LibXML This is a Perl interface for libxml2, providing DOM standards compliant interface. It is recommended that you use version C<1.54_3> or higher. =item * BerkeleyDB perl module Perl interface to the database software. Version C<0.19> or higher is required. =item * Template-Toolkit This is a powerful set of tools for text template processing. Torrus uses it for HTML files output. See also the project homepage: Ehttp://www.template-toolkit.orgE =item * Proc::Daemon Daemon invocation routines. =item * Net::SNMP SNMP queries and traps interface. Version C<4.0.3> or higher is required. I: Torrus versions prior to 1.0.9 are incompatible with Net::SNMP version 6.0.0. You may need to downgrate the module to 5.2.0. =item * URI::Escape Escape and unescape unsafe characters =item * Apache (mod_perl version 1.0) Mod_perl is a Perl runtime environment integrated into Apache HTTP server. =item * Apache::Session User session tracking helper =item * Date::Parse and Date::Format Module for parsing the user input for date and time. =item * JSON JSON data format support =back =item * HTTP Browser requirements The HTTP browser must be compatible with I and I specifications. The tests were made with the following browsers: IE 5.5, Opera 6.12B1/Solaris, Opera 7.03/Win2K, Netscape 7.02. =back =head2 Recommended Software =over 4 =item * C by Petr Pajas This Perl module implements XUpdate specification Ehttp://www.xmldb.org/xupdate/E. See Torrus User Guide for details. =item * XSH by Petr Pajas Available at Ehttp://xsh.sourceforge.netE. This is a shell wrapper for a set of utilities for XML extraction, browsing, and editing. =item * libxslt from Gnome project C is the XSLT stranslation library from Gnome project Ehttp://www.gnome.orgE, available as a standalone package. It includes a binary executable, C. See Torrus User Guide for examples of its usage. =back =head2 Installation Procedure Create the group C and a user C. The user should be a member of this group. Add your Apache daemon user to the group C. Other users that will run any of Torrus processes must be included in this group. For example, in Solaris (you may need to specify the GID and UID numbers according to your local administration policy): groupadd torrus useradd -c 'Torrus Daemon' -d /usr/local/torrus -g torrus torrus usermod -G www,torrus www Further installation process is mostly as usual: ./configure make make install The default directory layout is described below. Should you need to change it, there is a number of variables and configuration options that you may use as C<./configure> arguments. See C<./configure --help> for details. Alternatively you can utilize the script C<./setup_tools/configure_fhs>, which is designed to provide an FHS compliant setup. The script is equivalent to executing ./configure \ --prefix=/opt \ --mandir=/opt/share/man \ pkghome=/opt/torrus \ sitedir=/etc/opt/torrus Do not try to change any paths by supplying them as C variables, this would most probably break the installation. The only C variable that is supported is C. It may be used for preparing the package for further distribution. For example, the following command would install all Torrus files as if F were the root of the filesystem: make DESTDIR=/tmp/stage install The presence of prerequisite Perl modules is checked during the execution of C<./configure>. You can disable this by giving I<--enable-pkgonly> option. The installer sets up the site configuration files, but only if they don't already exist. Plugin modules should be installed separately, after the Torrus software is successfully installed. For each plugin, unpack the plugin distribution archive to some directory, and execute torrus install_plugin A number of directories is set up by default under the path C, and they must be writable by all Torrus processes, including the Apache web server. You can control these directories' access rights by setting the following environment variables: I, I, I, like follows: ./configure var_group=wwwrun Default values for operating systems other than Cygwin are: I, I, I. Setgid bit is set by default for these directories. If available, you may place these directories on a fast media, for example, a robust disk array. Changing the C variable would be generally enough, for example: ./configure varprefix=/vol1/torrus_var =head2 Torrus directory layout @pkghome@/ Home directory for Torrus distribution files @cfgdefdir@/ torrus-config.pl and other configuration files @pkgbindir@/ Command-line executables @docdir@/ POD and TXT documentation files @exmpdir@/ Miscelaneous example files @perllibdir@/ Perl libraries @pluginsdir@/ Plugins configuration @scriptsdir@/ Scripts @supdir@/ Supplementary files, DTDs, MIBs, color schemas, web plain files @tmpldir@/ Renderer output templates @distxmldir@/ Distrubution XML files @sitedir@/ Site configurable files @siteconfdir@/ Place for torrus-siteconfig.pl and other siteconfigs @siteconfdir@/discovery/ Devdiscover input files @tmpluserdir@/ User-defined Renderer output templates @sitexmldir@/ User XML configuration files @mandir@ Place for man pages. All articles have the prefix C @logdir@/ Daemon logfiles @piddir@ Daemon PID files @cachedir@ Renderer cache @dbhome@ Berkeley DB home @seslockdir@ @sesstordir@ Web interface session files @defrrddir@ Recommended directory for RRD files generated by collectors B RRFW used the path F as the default path for storing the RRD files. According to FHS specification, the recommended path for service data files is recommended to be a subdirectory of F. The path F<@defrrddir@> is used as default by C utility, and you can always change it in the command line or in your DDX files. =head2 Configuring Torrus The datasources are configured with C<%Torrus::Global::treeConfig> hash in F. In this hash, the keys give the tree names. The values for each tree name are pointers to hashes, with the following keys and values: I points to an array of source XML file names; I points to a hash with the names of the daemons that would be automatically launched for the tree; I gives a short line describing the tree contents. Two additional arrays: C<@Torrus::Global::xmlAlwaysIncludeFirst> and C<@Torrus::Global::xmlAlwaysIncludeLast> give a list of source XML files that are included in every tree, in the beginning or in the end of the XML files list. By default, this array consists of two files: F and F. The second one is resided in the user-configurable directory, and you can use it to override any default settings. Example: @Torrus::Global::xmlAlwaysIncludeFirst = ('defaults.xml', 'site-global.xml'); %Torrus::Global::treeConfig = ( 'tree_A' => { 'description' => 'The First Tree', 'xmlfiles' => [qw(a1.xml a2.xml a3.xml)], 'run' => { 'collector' => 1, 'monitor' => 1 } }, 'tree_B' => { 'description' => 'The Second Tree', 'xmlfiles' => ['b1.xml', 'b2.xml'], 'run' => {} } ); XML files are read additively within each tree, in the order as they are listed. The XML compiler searches for the files in several directories, listed in C<@Torrus::Global::xmlDirs>. By default, this list conssists of two paths, one for Torrus distribution files, and the other for user files. Files generated by C usually contain I statements which add the vendor-specific XML files to the compilation. Below follows a short description of some XML files that come with Torrus distribution. Only F is installed in the directory for user-configurable files, all others are placed in the distribution directory. =over 4 =item * defaults.xml Default parameters for the root of the datasources tree. Default view definitions. B this file is automatically overwritten by C. =item * site-global.xml Parameters that you want to change or define for your site. This file will be compiled for every tree after F, and this is the place to override the defaults. The file that is supplied with the Torrus distribution has some useful parameters that you may simply uncomment. B this file is never overwritten by C. =item * snmp-defs.xml SNMP collector defaults. The file defines several templates used for collecting SNMP data. Do not change this file. You may redefine the needed parameters in your site-specific files and templates. =item * vendor/EvendorE.EproductE[.EsubsystemE].xml SNMP collector definitions and templates for various hardware vendors and products. C includes some of these files automatically in the configuration. =item * generic/*.xml SNMP collector definitions and templates for vendor-independent MIBs. Most files are named after corresponding RFC numbers. =back In addition, the distribution package contains several example files. For more details about XML configuration, see I and I. =head2 Site configuration options In addition to I<%Torrus::Global::treeConfig>, you may wish to set some other parameters in your site configuration file (F). See F for the complete list of varaibes that you may override in your site config. Among them, most interesting are: =over 4 =item * C<$Torrus::Renderer::companyName> The text that you specify here will appear in the top left corner of all HTML pages. =item * C<$Torrus::Renderer::companyURL> The company name text will be clickable with the URL specified in this variable. =back =head2 Apache HTTP server configuration Torrus web interface is designed to run under mod_perl environment (Ehttp://perl.apache.orgE). See the I document for detailed instructions on Apache configuration. In short, typical Apache configuration for mod_perl version 1.0 would look like follows: Alias /torrus/plain "@webplaindir@" PerlRequire "@cfgdefdir@/webmux.pl" SetHandler perl-script PerlHandler Torrus::ApacheHandler SetHandler default-handler Options None =head2 Access Control Lists By default, Torrus web interface requires user authentication. You can disable this by changing C<$Torrus::CGI::authorizeUsers> to zero in your F. ACLs are controlled by C utility. See I for detailed description. Example: torrus acledit --addgroup=staff --permit=DisplayTree --for='*' torrus acledit --addgroup=staff --permit=GlobalSearch --for='*' torrus acledit --adduser=jsmith --password=mysecretpassword \ --cn="John Smith" --addtogroup=staff torrus acledit --addgroup=admin \ --permit=DisplayTree --permit=DisplayAdmInfo --for='*' =head2 Cron Job In order to clean old HTTP session data, it is recommended to run F script in a cron job, once per day: #min hour mday month wday who command 5 3 * * * root @pkgbindir@/cleanup =head2 Startup script The Torrus distriubution provides a startup script which you can install in the init scripts directory (/etc/init.d on most Unixes or /usr/local/etc/rc.d/ on FreeBSD). The script C is created during the installation process in the subdirectory of the distribution directory. The init script reads some parameters from F<@cfgdefdir@/initscript.conf>, and F<@siteconfdir@/initscript.siteconf> if the latter exists. By default, it makes the monitor daemons sleep for 20 minutes when they are launched simultaneously with collector daemons. =head2 Upgrade Procedure Follow these instructions when upgrading from previous Torrus release. In the previous distribution directory, look up the F file. It contains the configure options that you used in previous installation. Unpack the new release distribution. Run C<./configure> with the same options you used before. Stop the collector and monitor processes (usually by C). Stop Apache process. Run C. Start the collector and monitor processes. Start Apache process. Also it is recommended to re-compile your XML configuration. If you prefer not to do this, it's recommended that you clear the Web interface cache both in your browser and in Torrus: torrus clearcache =head2 Planning the disk space In a typical Torrus setup, there are two disk space consuming entities: the RRDtool data storage and the Berkeley DB database. RRDtool data files (or RRD's) are used to store the values that are gathered by the collector daemons. These are the most intensively updated files, so the disk speed is important here. If possible, it is better to spread the RRD files across several physical disks. Berkeley DB database is used to keep all the configuratiuon data for your datasource trees, and it also keeps some live status information. It's intensively updated during XML compilation only. During normal Torrus working cycle, there are only few updates, not very critical in time. The database is read quite intensively during collector initialization, but usually it's the CPU speed that causes more delay. For a typical Torrus installation with standard RRD creation parameters, the rough estimation is as follows: the Berkeley DB database occupies from 10 to 13 KB per collector datasource, and the RRD storage takes approximately 80 to 85 KB per datasource. For a medium-sized system, few hundred megabytes for the Berkeley DB database and several gigabytes for RRD storage would be sufficient. Larger systems require a thorough design and staging work. See I for more details. =head2 Network performance tuning In large installations, the SNMP collector experiences quite intensive input traffic bursts. Thus the UDP socket receive buffers should be adapted to sustain the load. By default, Torrus sets the UDP receiving buffer size, SO_RCVBUF, to 131071 bytes. This should fit most of installations. However, it's useful to check the network statistics if there are any UDP buffer overflows. On most systems, the commands C or C should show you these counters. The maximum buffer size is usually limited by a system kernel variable, and can be increased if needed. See C<$Torrus::Collector::SNMP::RxBuffer> and its comments in F for more details. =head1 Author Copyright (c) 2002-2007 Stanislav Sinyagin Essinyagin@yahoo.comE