diff options
Diffstat (limited to 'torrus/doc/userguide.pod.in')
| -rw-r--r-- | torrus/doc/userguide.pod.in | 869 |
1 files changed, 869 insertions, 0 deletions
diff --git a/torrus/doc/userguide.pod.in b/torrus/doc/userguide.pod.in new file mode 100644 index 000000000..1e170c937 --- /dev/null +++ b/torrus/doc/userguide.pod.in @@ -0,0 +1,869 @@ +# userguide.pod - Torrus user guide +# Copyright (C) 2003 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: userguide.pod.in,v 1.1 2010-12-27 00:04:32 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 Torrus User Guide + + +=head2 Quick start guide + +The steps below will explain you how to make the thing running. + +B<Install Torrus>. Follow the I<Torrus Installation Instructions> document, +all prerequisits and necessary steps are described there. + +B<What is where>. The executables reside in +F<@pkgbindir@/>. You normally don't need to access this +directory, because the commandline wrapper, C<torrus>, is installed +in a usual execution path (F<@bindir@>). +All site-specific behaviour is controlled by +configuration files in F<@siteconfdir@/>. +Usually you need to change F<torrus-siteconfig.pl> only. In this file, you +must list your XML configuration sources. The datasource trees configuration +is read out of XML files. They are searched in several directories, +normally F<@distxmldir@/> and F<@sitexmldir@/>. The first one contains +files that come with Torrus distribution, and the second one is for your local +site-specific XML files. Global site-specific XML configuration parameters +may be defined in F<site-global.xml>. +XML configuration is compiled into internal database representation +by C<torrus compilexml> command. The database itself is resided in +F<@dbhome@/>, and must be writable by your Apache server +(normally the installer takes care of it). It is safe to re-compile the +configuration while the Torrus daemons are running. + +B<The datasource trees>. Torrus configuration consists of a number of I<trees>. +Each tree is independent from the others. A tree may run one Collector and +one Monitor process. Also the web interface access control lists +differentiate the user rights by datasource trees. + +B<Inside the tree>. A tree defines the hierarchy of Torrus datasources. +The structure of the tree is solely defined by XML configuration files. +The tree consists of I<nodes>, each being either a I<subtree> or a I<leaf>. +Subtrees contain child subtrees and/or leaves. The leaf represents a +datasource: normally this is a numerical value that changes over time. +The leaf is the entity that may be presented as a graph. +There are leaves of special type: I<multigraph>. +They are not numerical values, and are designed for +drawing several values in one graph. Each node has I<path>, a +string that consists of slashes and node names, and uniquely identifies this +node. The path of a subtree always ends with slash, and the root of the tree +has the path consisting of a single slash. + +B<Trees configuration>. The trees are defined in F<torrus-siteconfig.pl>. +See I<Torrus Installation Instructions> for a basic example of tree +configuration. + +B<Round-robin databases>. Currently only one type of data storage is +supported: Round-robin database (RRD) files. See I<RRDtool> manuals +for more details. Each leaf represents a datasource stored in an +RRD file. Of course, several leaves may refer to different datasources within +the same RRD file. Even more, more than one leaf may refer to the same +datasource within an RRD file. RRD files are created and updated either by +C<collector>, or by some other external programs. + +B<Define the targets>. If you only want to collect SNMP counters +from some network devices' interfaces, there's a couple of tools +called C<torrus genddx> and C<torrus devdisover>. +The first one creates a basic discovery instructions file, and the second +one uses the discovery instructions to explore the SNMP device capabilities +and information: interface names, input/output counters, +CPU and memory usage, temperature sensors (for Cisco devices), and many +other vendor-specific statistics sources. + +Torrus is much more than just an SNMP collector. So, when you decide +to use it in a more advanced way, you will have to read the whole bit of +this guide, and also I<Torrus XML Configuration Guide> and probably some +other documents too. + +B<Build the hierarchy>. By default, C<torrus genddx> will put all your +devices into one hierarchy: C</Routers/E<lt>hostnameE<gt>/...>. +The subtree name, C<Routers>, may be changed with a command line option +of C<torrus genddx>. This program may also read the device names +(or IP addresses in case if you don't use DNS) from space-delimited text files. + + torrus genddx \ + --hostfile=myrouters.txt \ + --domain=example.net \ + --community=MySecretSNMPCommunity \ + --out=myrouters.ddx \ + --discout=myrouters.xml \ + --subtree=/My_Routers \ + --datadir=/data1/torrus/collector_rrd + + torrus genddx \ + --hostfile=myswitches.txt \ + --domain=example.net \ + --community=MySecretSNMPCommunity \ + --out=myswitches.ddx \ + --discout=myswitches.xml \ + --subtree=/My_Switches \ + --datadir=/data1/torrus/collector_rrd + + torrus devdiscover --in=myrouters.ddx + + torrus devdiscover --in=myswitches.ddx + +In the example above, the routers' and switches' names are read from +F<myrouters.txt> and F<myswitches.txt> in the user's current directory. +They form a hierarchy with two subtrees: C</My_Routers/> and C</My_Switches/>. +C<genddx> creates the discovery instruction XML files into +F<myrouters.ddx> and F<myswitches.ddx> accordingly. By default, +you would find them in F<@sitedir@/discovery/>. +The result of C<devdiscover> is the Torrus configuration files: +F<myrouters.xml> and F<myswitches.xml>, placed into +F<@sitexmldir@/>. The C<collector> will place the +RRD files into F</data1/torrus/collector_rrd>. Make sure that this directory +exists, has enough free space, and is writable by C<torrus> user. + +B<Note:> the C<genddx> utility is designed as a one-time helper, so +that you create your basic discovery instructions files from scratch. +Further on, the discovery files should be maintained separately. + +Another useful utility is called C<ttproclist>. It can be used to generate +a DDX file from a template and a list of SNMP hosts. It is very useful if +you want to monitor many devices of similar type or function. + +You can also define a I<bundle> file in your DDX file. C<Genddx> will +create it after all devices would discovered, and it will contain +E<lt>includeE<gt> statements for all XML files. This makes it practical to +use one XML file per SNMP host, and use the bundle file for inclusion +in the tree configuration. + +B<Add your XML files to the tree configuration>. For each tree, +F<@siteconfdir@/torrus-siteconfig.pl> lists the XML files that have to be +compiled for it. In the example above, you would add F<myrouters.xml> and +F<myswitches.xml> into C<xmlfiles> array in the tree configuration. + +See I<Torrus SNMP Discovery User Guide> for more details on how +C<genddx> and C<devdisover> interact and how you can customize +the discovery process. + +B<Tip>: in most cases, your hierarchy division will be different. +It might be arranged by geographical locations, or by customer names. +There is a configuration statement that allows you to include other +XML files into configuration, thus giving you a big flexibility +in building the data hierarchies. + +B<Compile the configuration>. After the XML configuration is prepared, +you need to execute the compiler: + + torrus compile --tree=treename --verbose + +For most of the processes that you run within Torrus, you need to specify +the tree name with C<--tree> option. Some proramms accept C<--all> option, +which causes them to process all existing trees. +With C<--verbose> option, the compiler tells you about the files being +processed, and about some other actions that may take quite a long time. +It will also tell you if there's any error in your configuration. + +B<Build the search database>. The search database is updated by executing +the following command: + + torrus bs --global --verbose + +For users that are allowed to display all the trees, you can enable the +global search across all trees: + + torrus acledit --addgroup=staff --permit=GlobalSearch --for='*' + +B<Launch the collector>. Assuming that compilation went smoothly, +you may now launch the data collector: + + torrus collector --tree=treename + +Without additional options, the collector will fork as a daemon +process, and write only error messages in its log file, +F<@logdir@/collector.treename.log>. + +There is a file that is created by C<./configure>, called F<init.d/torrus>. +You may place it into a directory where your system looks for startup scripts +(F</etc/init.d/> on Solaris and some Linuxes, F</usr/local/etc/rc.d/> +on FreeBSD). Probably you need to rename and edit the script before using. +Note that it also executes another daemon, C<monitor>. + +The C<monitor> daemon is used for monitoring the thresholds in the +data files. For more details, see the I<Torrus XML configuration guide>, +in the section about monitor definitions. + +B<Define the ACLs>. By default, user authentication is enabled in the web +interface. You can change this by setting +C<$Torrus::CGI::authorizeUsers = 0> in your F<torrus-siteconfig.pl>. +In order to get use of user authentication, you need to create I<groups> +and I<user> accounts. Each user belongs to one or more groups, and each group +has access to a set of datasource trees. See +I<Torrus Installation Instructions> for a basic example. + +B<Browse with your browser>. Provided that you followed the +installation guide to the end, and your HTTP server is running, +your Torrus hierarchy must be visible with your favorite web browser. + + +=head2 Configuration guidelines + +In complete detail, the XML configuration is described in +I<Torrus XML Configuration Guide>. The guidelines below will help +you to read that document. + +B<Tree structure>. The tree structure is defined by the structure of +C<E<lt>subtreeE<gt>> and C<E<lt>leafE<gt>> XML elements. The rule is simple: +child XML elements of a C<E<lt>subtreeE<gt>> element define the child +nodes in the configuration tree. + +B<Parameters>. Each node has a number of parameters. They are defined +by C<E<lt>paramE<gt>> XML element. Parameters are inherited: +the child node has all its parent's parameters, some of which may be +overridden. + +B<Additive configuration>. The whole XML configuration is additive. +It means that you may define your subtree several times across +your XML configuration, and the new parameters and child nodes will +be added to previously defined ones. + +B<Templates>. Some pieces of configuration may be written as templates, +and then re-used in multiple places. + +The C<configsnapshot> utility generates one large XML file back from +the compiled configuration. Its main purpose is backup of the configuration, +but it can also be used for studying the relationships between templates +and input files. + +=head2 Handling SNMP errors + +During SNMP discovery process, some SNMP devices may not be reachable. +By default, C<devdiscover> reports the error, and does not write the output +XML file containing that device. It also skips writing the bundle files that +contain the output file affected. + +When C<devdiscover> is executed with C<--forcebundle> option, the bundle +files are written, and the output files related to the unreachable +devices are skipped from the bundles. This ensures that we always get +a configuration that may compile and run the collector. + +Another option, C<--fallback=DAYS>, if given together with C<--forcebundle>, +tells the discovery engine to reuse old XML files if the related SNMP devices +are not reachable and the files are not older than DAYS. + +If an SNMP device is unreachable by the moment of the collector initialization, +the collector reports the error and waits for a period of time specified in +C<$Torrus::Collector::SNMP::unreachableRetryDelay>, which is 10 minutes by +default. It then tries to reach the device with the specified retry interval +during some period of time, defined in +C<$Torrus::Collector::SNMP::unreachableTimeout>, by default 6 hours. +If the device is not available within the specified timeout, it is excluded +from collection. It would be tried again on collector initialization +only (at the collector process start or after recompiling the configuration). + +If a device is not reachable during the normal collector running cycle, +it is retried in every collector's cycle (usually every 5 minutes), +during the period defined in C<$Torrus::Collector::SNMP::unreachableTimeout>. +It will be then excluded from configuration after the timeout. + +If a device hardware configuration changes after the C<devdiscover> +execution, the collector may not find some values in SNMP tables, +such as interface names in ifTable. It then excludes such datasources from +collection immediately. + + + + +=head2 Tips and tricks + + +=head3 Comments, descriptions, and legends + +C<torrus devdiscover> will extract some useful information from +your SNMP devices, and place it in the XML configuration: + +=over 4 + +=item * Interface descriptions + +The value of the SNMP variable C<ifAlias> (C<1.3.6.1.2.1.31.1.1.1.18>) +will be used as interface comment. In Cisco IOS, this is controlled by +C<description> interface configuration command. + +=item * Location and contact + +Two other SNMP values: C<sysLocation> (C<1.3.6.1.2.1.1.6.0>) and +C<sysContact> (C<1.3.6.1.2.1.1.4.0>) will be used in the legend text +for each device. In Cisco IOS, their values are controlled by +C<snmp-server location> and C<snmp-server contact> global configuration +commands. + +=back + + +=head3 Grouping the datasources alternatively + +In most cases, you would want to have several different groupings of +your datasources. + +For instance, the default C<devdiscover> gives only one level of freedom: +the subtree name above the host level. It's reasonable to use this name for +grouping by geographical location . Thus, the hierarchy +would be characterised as +C</[location]/[hostname]/[interface]/[counter]>. + +Let's say you would like to have alternative grouping, such as: + +=over 4 + +=item * by customer connection: + +Each customer is identified by name, and you'd like to see statistics +for all interfaces connected to a given customer; + +=item * by service: + +Your network is designed to provide various services, and you'd like to +group your devices or interfaces by service; + +=item * by customer and location: + +For each customer, group the connection by geographical location. + +=back + +Torrus provides three different ways for organising your datasources: + +=over 4 + +=item * Aliases. + +With C<E<lt>aliasE<gt>> statement, you can add symbolic names to your +nodes. If the new alias is defined as a reference to non-existing subtree, +the new subtrees are created. Alias is only a symbolic link: when you click +to the alias name in your browser, Torrus redirects it to the real datasource +in its normal subtree. See the example in I<Torrus XML Configuration Guide>. + +=item * ds-type=rrd-file + +You can create a leaf in some arbitrary place of your hierarchy that +points to an existing RRD file. This RRD file may be updated by +other datasource in your hierarchy. The advantage of such approach is +that this leaf may have its own I<legend> and I<comment> parameters, +alternative view parameters, etc. + + <leaf name="FoobarIn"> + <param name="ds-type" value="rrd-file" /> + <param name="leaf-type" value="rrd-def" /> + <param name="data-file" value="rtr01_Fa0_1.rrd" /> + <param name="rrd-cf" value="AVERAGE" /> + <param name="rrd-ds" value="locIfInBitsSec" /> + <param name="comment" + value="Foobar input traffic"/> + <param name="graph-legend" value="Bits in" /> + <param name="legend"> + Switch name: rtr01; Interface: Fa0/1; + </param> + </leaf> + +In the example above, this leaf is defined somewhere in the hierarchy. +It refers to the RRD file updated by Torrus SNMP collector. +For more examples, see the template I<read-cisco-interface-counters> +in F<vendor/cisco.ios.xml>. + +=item * Tokensets + +Tokenset is an arbitrary collection of datasource leaves. It is characterised +by its name and description. There are two ways to add a leaf to a tokenset: +by the parameter I<tokenset-member>, or by defining a monitor action. +A tokenset is normally displayed in compact form: by default, 6-hour graphs +are put by two in a row. + +=back + + +=head3 Amending autogenerated XML files with XUpdate + +Sometimes there is a need to modify the configuration generated by +C<devdiscover>. Modifying the generated XML files by hand would not be +a good option: it would need some manual work every time you update +your hardware setup. A better approach would be to have the tools +that would automate such configuration update. + +One of the possibilities for such automation would be XSLT +E<lt>http://www.w3.org/TR/xsltE<gt>. But it's rather +complicated task to use XSLT for slight changes in XML files. + +A good approach has been made by XUpdate Working Group +E<lt>http://www.xmldb.org/xupdate/E<gt>. Their Working Draft document +describes a language for XML editing commands. It allows to perform +small updates to an existing XML document, like insertion of elements, +updating of existing elements, or deleting. The only drawback is +that the specification hasn't been updated since September 2000, +and it contains some unclear statements, which make it difficult to +implement compatible applications. In addition, there has been +not enough efforts to adopt XUpdate as a W3C standard. +However, this is the only kind-of-a-standard language for such tasks as +XML editing commands. + +Thanks to Petr Pajas, there is an XUpdate implementaytion in Perl. +C<XML::XUpdate::LibXML> module is available at CPAN, and it installs +a small commandline utility, C<xupdate>. In addition, Petr has created +a set of utilities integrated into a single shell wrapper: +E<lt>http://xsh.sourceforge.netE<gt>. It is very useful for many different +things, such as XPath expressions testing, and many others. + +A typical XUpdate instructions file would looke like follows: + + <?xml version="1.0"?> + <xupdate:modifications version="1.0" + xmlns:xupdate="http://www.xmldb.org/xupdate"> + + <!-- Insert additional creator-info after the last one --> + <xupdate:insert-after + select="/configuration/creator-info[not(following-sibling::creator-info)]"> + <creator-info> + This file was modified with XUpdate script setmonitor.xupdate.xml + </creator-info> + </xupdate:insert-after> + + <!-- For every ifError leaf, set the monitor --> + <xupdate:append select="//subtree[apply-template[@name='iftable-errors']]"> + <xupdate:element name="subtree"> + <xupdate:attribute name="name">ifErrors</xupdate:attribute> + <param name="monitor" value="check-iferrors"/> + </xupdate:element> + </xupdate:append> + + </xupdate:modifications> + +This example is part of Torrus distribution, and the file is named +F<examples/setmonitor.xupdate.xml>. Your commands to apply these XUpdate +instructions would be like + + torrus devdiscover --in=routers.ddx --out=routers.xml + + cd @sitexmldir@ + xupdate -j @exmpdir@/setmonitor.xupdate.xml \ + routers.xml > routers1.xml + +More XUpdate examples will be included in the future. + + +=head3 Extracting the configuration skeleton + +Another aproach to amending the autogenerated confguration is as follows. + +Torrus distribution has a special-purpose XSLT template, +F<extract-skeleton.xsl>, designed to strip all parameters and template +applications from a given XML configuration, and leave the tree structure +only. Given that F<routers.xml> is some autogenerated configuration, +you may run + + xsltproc @scriptsdir@/xml/extract-skeleton.xsl routers.xml | \ + xmllint --format --output routers-skeleton.xml - + +You can add your changes to the new file, F<routers-skeleton.xml>, and add +it to your Torrus configuration. These changes may be performed manually +or by means of XUpdate technique described above. + + +=head3 Automating XML generation + +It is quite common task that you want Torrus to monitor certain set of +devices, and C<devdiscover> does not (yet) support them. Of course, +it's quite a pain to maintain a manually written XML file, especially if +the there are more than one devices of the same type. + +In such case you may benefit from the approach suggested by +Christian Schnidrig: + +Imagine you have 50 I<gizmos> which are able to speak SNMP and which you would +like to put into some Torrus tree structure. A good designer's approach would +be to keep the data and the presentation separately. In addition, changing +the presentation once would produce 50 changes accordingly. +To do that, let's create two files: F<gizmos.data> and F<gizmos.tmpl>. +The first one would contain data about our devices: + + [% + gizmos = [ + { + name => 'atwork' + color => 'blue', + location => 'Javastrasse 2, 8604 Hegnau' + description => 'My gizmo @ Sun' + community => 'blabla', + hands => [ + {name => 'Left'} + {name => 'Right'} + ], + } + { + name => 'athome' + color => 'gray', + location => 'Riedstrasse 120, 8604 Hegnau' + description => 'My gizmo @ Home' + community => 'blabla', + hands => [ + {name => 'Upper'} + {name => 'Lower'} + ], + } + ] + + %] + +Then F<gizmos.tmpl> would contain the XML template that would produce +the Torrus configuration file: + + [% PROCESS $data %] + <?xml version="1.0"?> + <configuration> + <datasources> + <subtree name="SNMP"> + <subtree name="Gizmos"> + [% FOREACH g = gizmos %] + <!-- ******************************************************* --> + <!-- [% g.name %] --> + <subtree name="[% g.color %]"> + <alias>/ByName/[% g.name %]/</alias> + + <param name="snmp-community" value="[% g.community %]" /> + <param name="comment" value="[% g.description %]" /> + <param name="snmp-host" value="[% g.name %]" /> + <param name="legend"> + Description: [% g.description %] + Location: [% g.location %] + </param> + + [% FOREACH h=$g.hands %] + <leaf name="[% h.name %]Hand"> + <!-- do something, my fantasy exhausted here --> + </leaf> + </subtree> + [% END %] + </subtree> + </subtree> + </datasources> + </configuration> + +See F<xmlconfig/examples/servers.data> and F<xmlconfig/examples/servers.tmpl> +for a more useful example of the described approach. + +At the end, you will generate the Torrus config with the C<tpage> utility, +which is the standard part of Template-Toolkit package: + + tpage --define data=gizmos.data gizmos.tmpl > gizmos.xml + + +=head3 Several Torrus instances on one server + +Sometimes it is necessary to have a separate instance of Torrus for testing +purposes on the same server as the production installation. +In the example below, a completely autonomous installation of Torrus is +installed in F</usr/testtorrus> directory on a FreeBSD system. + +=over 4 + +=item * Directory structure + +All files are located in subdirectories of F</usr/testtorrus>. No other +directories are affected. This ensures that deinstallation would be easy +and safe. + +Four subdirectories are created: + +=over 8 + +=item * F</usr/testtorrus/apache> + +This directory contains Apache HTTP daemon configuration and logs. Create 3 +subdirectories here: F<etc>, F<htdocs>, and F<var>. + +=item * F</usr/testtorrus/home> + +This is the installation directory of Torrus. + +=item * F</usr/testtorrus/etc> + +Directory for configuration files. + +=item * F</usr/testtorrus/var> + +Directory for logs, database and PID files. + +=item * F</usr/testtorrus/collector_rrd> + +Collector will store RRD files here. + +=item * F</usr/testtorrus/src> + +Distribution files will be stored and unpacked here. + +=back + + +=item * Installation procedure + + cd /usr/testtorrus/src + gzip -dc torrus-1.0.0.tar.gz | tar xvf - + cd torrus-1.0.0 + ./configure pkghome=/usr/testtorrus/home \ + sitedir=/usr/testtorrus/etc \ + logdir=/usr/testtorrus/var/log \ + piddir=/usr/testtorrus/var/run \ + varprefix=/usr/testtorrus/var \ + wrapperdir=/usr/testtorrus + make install + +=item * Devdiscover configuration + +Use devdiscover as usual. Place your discovery instruction files in +F</usr/testtorrus/etc/discovery/>, and make sure that +C<data-dir> is set to F</usr/testtorrus/collector_rrd>. + +=item * Apache configuration + +We reuse the same binaries and libraries as the main installation of Apache, +but the daemon is launched with our special configuration. +We assume that Apache is pre-configured for mod_perl. SSL support is not +included in this example, but it's quite straightforward to implement +if you need it. + +Create a copy of F<httpd.conf> and place it in F</usr/testtorrus/apache/etc>. +With a text editor, replace the configutration options with the values +given below: + + # Leave server root as it was in the original config. Apache uses + # it for modules loading + ServerRoot "/usr/local" + + # make sure that everything that apache writes + # goes into our directories + PidFile /usr/testtorrus/apache/var/httpd.pid + ScoreBoardFile /usr/testtorrus/apache/var/httpd.scoreboard + + # Optional: limit the memory and CPU impact + MinSpareServers 2 + MaxSpareServers 5 + StartServers 3 + MaxClients 10 + + # We open our HTTP service on TCP port 8123. Choose other + # port if this one is occupied + Port 8123 + + # Not really necessary, but you might want to use it someday + DocumentRoot "/usr/testtorrus/apache/htdocs" + + # Find the Directory options for the old htdocs, and + # replace the path if you changed DocumentRoot above + <Directory "/usr/testtorrus/apache/htdocs"> + ... some default stuff here ... + </Directory> + + # Make sure the logs are written where we expect them to. + ErrorLog /usr/testtorrus/apache/var/httpd-error.log + CustomLog /usr/testtorrus/apache/var/httpd-access.log combined + + # TCP port number as above + NameVirtualHost *:8123 + + # Quite standard virtual server configuration. Replace fake + # domain names with your real ones. + <VirtualHost *:8123> + ServerAdmin root@myserver.com + DocumentRoot /usr/testtorrus/home/web + ServerName torrus.myserver.com + CustomLog /usr/testtorrus/apache/var/torrus.myserver.com.log "combined" + PerlModule Apache::PerlRun + PerlRequire "/usr/testtorrus/home/conf_defaults/webmux.pl" + Alias /plain/ "/usr/testtorrus/home/sup/webplain" + <Location /> + SetHandler perl-script + PerlHandler Torrus::ApacheHandler + </Location> + <Location /plain/> + SetHandler default-handler + Options None + </Location> + </VirtualHost> + +=item * Apache startup script + +Save the following script as F</usr/testtorrus/apache/testtorrus.sh>: + + #!/bin/sh + case "$1" in + start) + /usr/local/sbin/httpd -f /usr/testtorrus/apache/etc/httpd.conf && \ + echo 'apache started' + ;; + stop) + [ -r /usr/testtorrus/apache/var/httpd.pid ] && \ + kill `cat /usr/testtorrus/apache/var/httpd.pid` && \ + echo 'apache stopped' + ;; + *) + echo "Usage: `basename $0` {start|stop}" >&2 + ;; + esac + exit 0 + +=back + + +=head3 Changing the default short graph + +The default small graph in overviews and tokenset listings shows last 6 hours +of data. It might be more convenient for you to graph last 24 hours, +or even longer. To do so, you only need to change one parameter, +C<rrgraph-views>. You may change it on the top of the datasource tree, or +even only for some parts of the tree. + +In F<defaults.xml>, there's a view defiition called C<last24h-small>. It is +exactly the same size as the 6-hours' C<short> view, but it shows 24-hour +graph. Somewhere in Torrus configuration, you may have: + + <datasources> + <param name="rrgraph-views"> + last24h-small,last24h,lastweek,lastmonth,lastyear + </param> + </datasources> + +The best place for this would be F<site-global.xml>. + + +=head3 Watching the collector failures + +There is a script in Torrus distribution in F<examples/rrdup_notify.sh>, +which provides a simple way of telling if the collector runs right: it checks +the modification time of RRD files, and if any file is older than given +threshold, it sends an e-mail warning. + +Copy the script file to some place in your system and edit it so that it fits +your requirements: you might want to change the maximum age +parameter (default is 1 hour), the notification e-mail address, and the +directory paths where to look for RRD files. Then I<chmod> it so that it's +executable, and add it to I<crontab>. Depending on your operation requirements, +it might run every hour, or few times a day, or even at business hours only. + +The script writes the number of aged files in the e-mail subject, and lists +the file names in the body. In case of relatively large installation, +you might want to amend the script, in order to avoid too large email messages. + + +=head3 Viewing external RRD files + +Some external program may create its own RRD files, and you +may want to display and monitor them in Torrus. + +Also some collector-generated RRDs may become outdated -- for example, after +a module is removed from a router, and the interface counters not +being updated any more. + +The easiest way to use such files would be to utilize the +C<torrus rrddir2xml> command. It generates the XML configuration file +that represents all RRD files found in a given directory. It can also +scan the directory recursively. + +See also few examples in Torrus distribution. There are some +templates for use with Smokeping, OpenNMS, and Flowscan. + + +=head2 Torrus usage scenarios + + +=head3 Scenario 1. Netflow Traffic Analyser + +Cisco routers are capable of exporting the traffic statistics +data in I<Netflow> UDP packets. + +A I<cflowd> or I<flow-tools> daemon collects Netflow packets into flow files. + +I<FlowScan> software analyses the flow files and stores the +statistics into numerous RRD files. + +Torrus is used to monitor the thresholds and diplay the graphs +in convenient form. + + +=head3 Scenario 2. Backbone Traffic Statistics + +I<CiscoWorks2000> or I<NMSTOOLS> software is used to provide +the list of all devices in the network. + +Torrus's C<devdiscover> buids the XML configuration to monitor the +router interfaces, CPU and memory usage, and temperature sensors. + +Data importing scripts generate configuration for alternative +grouping of the datasources: by location; by customer connection; +by device type; by service type; etc... + + +=head2 Troubleshooting guidelines + +=head3 SNMP Error: Received tooBig(1) + +For some devices, the collector may issue the following error messages: + + [27-May-2004 10:15:17*] SNMP Error for XX.XX.XX.XX:161:public: Received + tooBig(1) error-status at error-index 0 + +For better performance, SNMP collector sends several SNMP requests in one +UDP datagram. The SNMP agent then tries to send the reply to all requests +in a single datagram, and this error indicates the failure. In most cases, +this is caused by the agent software limitations or bugs. + +The number of requests per datagram is controlled by the parameter +C<snmp-oids-per-pdu>, and it may be set in the discovery input XML or +in Torrus configuration XML. The default value is 40, and setting it to 10 +generally works. + +=head3 Database lock troubleshooting + +It may happen sometimes, that a process accessing Torrus database +terminates incorrectly, and the database becomes blocked. +A typical symptom of this is that the command +C<torrus compilexml --all --verbose> +does not print anything and stays running forever, occupying zero +percent of CPU. + +The nice, and the preferred way to solve the problem is +to use C<db_recover> utility from BerkeleyDB package. +The brutal way is just to remove the databases and re-compile +all the configuration. I<Note:> The ACL database is not automatically +backed up, and you need to take care of its backup before deleting +the contents of the database. + + ## The nice way uses BerkeleyDB db_recover + ## (might be located in /usr/local/BerkeleyDB.4.1/bin/) + /etc/init.d/apache stop + /etc/init.d/torrus stop + db_recover -h @dbhome@ + torrus compilexml --verbose --all + /etc/init.d/torrus start + /etc/init.d/apache start + + ## The brutal way + /etc/init.d/apache stop + /etc/init.d/torrus stop + cd @dbhome@ + rm -r * + torrus compilexml --verbose + /etc/init.d/torrus start + /etc/init.d/apache start + +=head1 Author + +Copyright (c) 2002-2007 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> |