• RRFW Installation Instructions
• Required Software
• Recommended Software
• Installation Procedure
• Configuring RRFW
• Site configuration options
• Apache HTTP server configuration
• Access Control Lists
• Cron Job
• Upgrade Procedure
• Author

RRFW Installation Instructions

These are the Round Robin Database Framework installation instructions.

Required Software

• Operating System
  
Any UNIX-like operation system where the required components are working. The author's primary development platform is Cygwin <http://www.cygwin.com>, and the primary testing environments are Sun Solaris/SPARC and FreeBSD.

Note to VmWare users: as recommended by Gord Philpott, Linux kernel for guest machine needs to be compiled with the following feature enabled: Character devices ---> Enhanced Real Time Clock Support. For other guest operating systems (e.g. FreeBSD), in order to let the RRFW collector and monitor run properly, you need to add the following lines to your $RRFW_HOME/share/rrfw/rrfw-siteconfig.pl:

  $RRFW::Scheduler::maxSleepTime = 15;
  $RRFW::Scheduler::ignoreClockSkew = 1;

Debian package is maintained by Jurij Smakov and is available at <http://pkg-rrfw.alioth.debian.org>.

• Perl
  
Perl version 5.8.1 or higher is required. Version 5.8.0 is not recommended because of memory access bugs and unpredictable behaviour. Perl interpreter must be in PATH environment variable when running ./configure.
• RRDtool
  
Round Robin Database Tool is available at: <http://ee-staff.ethz.ch/~oetiker/webtools/rrdtool/>. Both stable version 1.0.x and the development version 1.1.x are supported.

As of this writing, rrdtool version 1.1.x is still in its development stage, but it is ready to use in production. There's a small glitch in legend text alignment, and it will hopefully be fixed.

• libxml2
  
libxml2 is the XML parser library from Gnome project <http://www.gnome.org>, available as a standalone package. Versions 2.4.23 and above were tested.
• Berkeley DB version 4.2.52 or later
  
The Berkeley DB from Sleepycat Software <http://www.sleepycat.com> is used for all data storage. Versions 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 /usr/local/BerkeleyDB.4.2/. Unfortunately, Perl module BerkeleyDB cannot find the include and library files in that directory. So, it either needs --prefix=/usr/local configure option, or you need to edit config.in in BerkeleyDB distribution.
• HTTP Server
  
This software requires Apache HTTP server (<http://httpd.apache.org>) and mod_perl (<http://perl.apache.org>).

Apache version 1.3 and mod_perl version 1.0 are supported by ApacheHandler.

Apache version 2.0 and mod_perl 2.0 are supported by Apache2Handler. Minimum supported mod_perl 2.0 version is 1.99_15. The handler also requires libapreq2 library, see the note below.

Plain CGI interface is no longer supported since RRFW version 0.1.1. See RRFW Web Interface Reference for details on mod_perl configuration.

• Perl Modules
  
The Perl modules required are listed below. They are all available at CPAN <http://www.cpan.org>. 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`/lib -MCPAN -e 'install Bundle::RRFW'

• XML::LibXML
  
This is a Perl interface for libxml2, providing DOM standards compliant interface. It is recommended that you use version 1.54_3 or higher.
• BerkeleyDB
  
Perl interface to the database software. Version 0.19 or higher is required.
• Template-Toolkit
  
This is a powerful set of tools for text template processing. RRFW uses it for HTML files output. See also the project homepage: <http://www.template-toolkit.org>
• Proc::Daemon
  
Daemon invocation routines.
• Net::SNMP
  
SNMP queries and traps interface. Version 4.0.3 is required.
• URI::Escape
  
Escape and unescape unsafe characters
• Apache (mod_perl version 1.0)
  
Mod_perl is a Perl runtime environment integrated into Apache HTTP server.
• Apache::Session
  
User session tracking helper

• libapreq2 Perl library
  
Apache 2.0 handler requires an additional Perl library, libapreq2. It is available from CPAN <http://search.cpan.org/>, and only in development version. You need to download and install it manually in order for Apache2Handler to work.
• HTTP Browser requirements
  
The HTTP browser must be compatible with HTML 4.01 Strict and CSS2 specifications. The tests were made with: IE 5.5, Opera 6.12B1/Solaris, Opera 7.03/Win2K, Netscape 7.02.

Recommended Software

• XML::XUpdate::LibXML by Petr Pajas
  
This Perl module implements XUpdate specification <http://www.xmldb.org/xupdate/>. See RRFW User Guide for details.
• XSH by Petr Pajas
  
Available at <http://xsh.sourceforge.net>. This is a shell wrapper for a set of utilities for XML extraction, browsing, and editing.
• libxslt from Gnome project
  
libxslt is the XSLT stranslation library from Gnome project <http://www.gnome.org>, available as a standalone package. It includes a binary executable, xsltproc. See RRFW User Guide for examples of its usage.

Installation Procedure

Create the group rrfw and a user rrfw belonging to that group. Add your Apache daemon user to the group rrfw. Other users that will run any of RRFW 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 rrfw
  useradd -c 'RRFW Daemon' -d /usr/local/rrfw-0.0 -g rrfw rrfw
  usermod -G www,rrfw www

Further installation process is mostly as usual:

  ./configure
  make
  make install

The package is installed by default in the directory /usr/local/rrfw-X.Y where X.Y.Z is the release version. Further on, we reference this directory as $RRFW_HOME.

Prerequisite Perl modules are checked at the time of ./configure. You can disable this by giving --disable-modcheck option.

The only files that are not overwritten during make install are $RRFW_HOME/share/rrfw/rrfw-siteconfig.pl and $RRFW_HOME/share/rrfw/xmlconfig/site-global.xml.

The following directories and their contents must be writable by your RRFW processes, including the HTTP server (usually Apache web server):

• $RRFW_HOME/var/cache/
  
The placeholder directory for Renderer cache files. These are PNG and HTML files ready for display by Apache handler.
• $RRFW_HOME/var/db/
  
The home directory for Berkeley DB environment. Here all the databases are stored.
• /var/snmpcollector/
  
This is the default directory for SNMP collector RRD files. It may be changed with the --datadir option of devdiscover.

You can control these directories' access rights by setting the following environment variables: var_user, var_group, var_mode, like follows:

  ./configure var_group=wwwrun

Default values for a non-Cygwin OS are: var_user=rrfw, var_group=rrfw, var_mode=775. Setgid bit is set by default for these directories.

If available, you may place these directories onto a faster media, by changing the --localstatedir=DIR option of ./configure.

Additional third-party components (plugins) may be included in your installation. These components must be designed for this use. Before running ./configure, unpack the plugin distribution archives into some directory:

  gzip -dc rrfw-plugin-ABC-0.0.1.tar.gz | tar xvf -
  gzip -dc rrfw-plugin-XYZ-0.0.1.tar.gz | tar xvf -

Then, specify the plugin distribution paths separated by colon (:) in the option --with-plugins of ./configure:

  ./configure [VARIABLE=VALUE...] \
    --with-plugins=../rrfw-plugin-ABC-0.0.1:../rrfw-plugin-XYZ-0.0.1 \
    [other options...]

After that, make install will install RRFW together with the specified plugins.

From the RRFW home page, you may download an example plugin called rrfw-plugin-dummy, and use it as a template for your own add-ons.

Configuring RRFW

The datasources are configured with %RRFW::Global::treeConfig hash in $RRFW_HOME/share/rrfw/rrfw-siteconfig.pl.

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: xmlfiles points to an array of source XML files; run points to a hash with the names of the daemons that would be automatically launched for the tree; desription gives a short line describing the tree contents.

Two additional arrays: @RRFW::Global::xmlAlwaysIncludeFirst and @RRFW::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.

Example:

  @RRFW::Global::xmlAlwaysIncludeFirst =
      ('defaults.xml', 'site-global.xml');

  %RRFW::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.

By default, only defaults.xml and site-global.xml need to be included in compilation. The XML files with vendor and MIB definitions are automatically included by XML files produced with devdiscover.

• defaults.xml
  
Default parameters for the root of the datasources tree. Default view definitions. Note: this file is automatically overwritten by make install.
• site-global.xml
  
Parameters that you want to change or define for your site. This file will be compiled for every tree after defaults.xml, and this is the place to override the defaults. The file that is supplied with the RRFW distribution has some useful parameters that you may simply uncomment. Note: this file is never overwritten by make install.
• 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.
• vendor/<vendor>.<product>[.<subsystem>].xml
  
SNMP collector definitions and templates for various hardware vendors and products. devdiscover includes some of these files automatically into configuration.
• generic/*.xml
  
SNMP collector definitions and templates for vendor-independent MIBs. Most files are named after corresponding RFC numbers.

In addition, the directory $RRFW_HOME/share/rrfw/xmlconfig/examples contains several example files.

For more details about XML configuration, see RRFW User Guide and RRFW XML Configuration Guide.

Site configuration options

In addition to %RRFW::Global::treeConfig, you may wish to set some other parameters in your site configuration file ($RRFW_HOME/share/rrfw/rrfw-siteconfig.pl).

See $RRFW_HOME/share/rrfw/rrfw-config.pl for the complete list of varaibes that you may override in your site config. Among them, most interesting are:

• $RRFW::Renderer::companyName
  
The text that you specify here will appear in the top left corner of all HTML pages.
• $RRFW::Renderer::companyURL
  
The company name text will be clickable with the URL specified in this variable.
• $RRFW::Renderer::stylingProfile
  
This variable should point to a file containing all default coloring and line styles for the graphs. The name of the file is the name of the profile with .pl suffix. The file is normally resided in $RRFW_HOME/share/rrfw/styling directory. See $RRFW_HOME/share/rrfw/styling/rrfw-original.pl for reference and examples.

Apache HTTP server configuration

RRFW web interface is designed to run under mod_perl environment (<http://perl.apache.org>).

See the RRFW Web Interface Reference document for detailed instructions on Apache configuration.

In short, typical Apache configuration would look like follows:

  Alias /rrfw "/usr/local/rrfw-0.1/web"
  PerlRequire "/usr/local/rrfw-0.1/share/rrfw/webmux.pl"
  <Location /rrfw>
    SetHandler perl-script
    PerlHandler RRFW::ApacheHandler
  </Location>
  <Location /rrfw/plain/>
    SetHandler default-handler
    Options None
  </Location>

Access Control Lists

By default, RRFW web interface requires user authentication. You can disable this by changing $RRFW::ApacheHandler::authorizeUsers to zero in your $RRFW_HOME/share/rrfw/rrfw-siteconfig.pl.

ACLs are controlled by acledit utility. See RRFW Manual pages for detailed description. Example:

  cd /usr/local/rrfw-0.1
  ./bin/acledit --addgroup=staff --permit=DisplayTree --for='*'
  ./bin/acledit --adduser=jsmith --password=mysecretpassword \
    --cn="John Smith" --addtogroup=staff
  ./bin/acledit --addgroup=admin \
    --permit=DisplayTree --permit=DisplayAdmInfo --for='*'

Cron Job

In order to clean old HTTP session data, it is recommended to run $RRFW_HOME/bin/cleanup in a cron job, once per day:

 #min hour mday month wday    who     command
 5    3    *    *     *       root    /usr/local/rrfw-0.1/bin/cleanup

Upgrade Procedure

Follow these instructions when upgrading from previous RRFW release.

In the previous distribution directory, look up the config.log file. It contains the configure options that you used in previous installation.

Unpack the new release distribution.

Run ./configure with the same options you used before.

Stop the collector and monitor processes (usually by /etc/init.d/rrfw stop).

Run make install.

Start the collector and monitor processes.

If using mod_perl, stop and start the Apache HTTP server.

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 RRFW:

  /usr/local/rrfw-0.0/bin/clearcache

Author

Copyright (c) 2002-2003 Stanislav Sinyagin <ssinyagin@yahoo.com>