RRFW Installation Instructions

These are the Round Robin Database Framework installation instructions.

Required Software

Recommended Software

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:

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

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.


  @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.

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:

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 /rrfw/plain/>
    SetHandler default-handler
    Options None

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:



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