X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=torrus%2Fdoc%2Finstall.pod.in;fp=torrus%2Fdoc%2Finstall.pod.in;h=3815dadb4f4390da50cc85ab9bb4144494c1f914;hp=0000000000000000000000000000000000000000;hb=74e058c8a010ef6feb539248a550d0bb169c1e94;hpb=35359a73152b3d7a9ad5e3d37faf81f6fedb76e8 diff --git a/torrus/doc/install.pod.in b/torrus/doc/install.pod.in new file mode 100644 index 000000000..3815dadb4 --- /dev/null +++ b/torrus/doc/install.pod.in @@ -0,0 +1,630 @@ +# 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