torrus/doc/rrfw_torrus_migration.pod.in

   1 #  webintf.pod - Torrus web interface reference
   2 #  Copyright (C) 2002  Stanislav Sinyagin
   3 #
   4 #  This program is free software; you can redistribute it and/or modify
   5 #  it under the terms of the GNU General Public License as published by
   6 #  the Free Software Foundation; either version 2 of the License, or
   7 #  (at your option) any later version.
   8 #
   9 #  This program is distributed in the hope that it will be useful,
  10 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 #  GNU General Public License for more details.
  13 #
  14 #  You should have received a copy of the GNU General Public License
  15 #  along with this program; if not, write to the Free Software
  16 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  17
  18 # $Id: rrfw_torrus_migration.pod.in,v 1.1 2010-12-27 00:04:32 ivan Exp $
  19 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  20 #
  21 #
  22
  23 =head1 RRFW to Torrus migration guide
  24
  25
  26
  27 =head2 Introduction
  28
  29 Torrus is the new marketing name for RRFW (Round-robin Database Framework),
  30 a robust and flexible software package for data series processing.
  31 The last release of RRFW is 0.1.8. The upcoming release 1.0.0 of Torrus
  32 will introduce some significant changes and design improvements.
  33
  34 The directory structure of Torrus is more standards-compliant, and more
  35 convenient for system adminisrators. The user files are strictly separated
  36 from the distribution files. The XML configurations and HTML templates
  37 are being searched in multiple directories, thus there will be no longer a
  38 mixture of site-specific files with the ones from distribution.
  39
  40 In addition, Torrus introduces a commandline wrapper that is installed in
  41 a generic directory for user executables (by default, F</usr/local/bin>).
  42 This greatly simplifies the site administrator's tasks.
  43
  44 The plugins infrastructure is completely redesigned.
  45 The plugin installation procedure is separated from the main software
  46 installation. In addition, plugin installers set up their initialization
  47 scripts in special directories, so that there's no need for plugin
  48 initialization in F<torrus-siteconfig.pl> and other files.
  49
  50 Further on, we assume that RRFW is installed in its default directory,
  51 F</usr/local/rrfw-0.1>, and Torrus is installed with default paths. These
  52 paths may differ in your installation.
  53 We refer to TORRUS_DISTR as the unpacked Torrus distribution path.
  54
  55
  56
  57 =head2 Software installation
  58
  59 Create a new user: C<torrus> and group: C<torrus>. The user ID that is
  60 used by Apache process must be a member of this group. Depending on the
  61 system, this user may be named as C<www>, C<httpd>, C<nobody> etc. Consult
  62 your Apache configuration for details.
  63
  64 Install Torrus. If your system already runs RRFW release 0.1.8,
  65 all prerequisites should be already in place. Then you simply unpack
  66 the Torrus distribution, and from its directory execute
  67
  68   ./configure
  69   make install
  70
  71 If required, download and unpack the Torrus plugins. Then for each plugin,
  72 execute
  73
  74   torrus install_plugin <UNPACKED_PLUGIN_DIR>
  75
  76
  77
  78 =head2 The Perl configuration files
  79
  80 Te distribution contains a short Shell script called
  81 C<TORRUS_DISTR/setup_tools/replace_rrfw.sh>. This script takes one file name
  82 as an argument, replaces all occurrences of I<RRFW> to I<Torrus> and I<rrfw>
  83 to I<torrus>, and finally replaces the specified file with the new one.
  84
  85 Copy the site configuration files from RRFW to Torrus directory:
  86
  87   cd /usr/local/etc/torrus/
  88   cp /usr/local/rrfw-0.1/share/rrfw/rrfw-siteconfig.pl \
  89     conf/torrus-siteconfig.pl
  90   TORRUS_DISTR/setup_tools/replace_rrfw.sh conf/torrus-siteconfig.pl
  91
  92 If needed, follow the same procedure for F<devdiscover-siteconfig.pl>
  93 and other site configs.
  94
  95
  96
  97 =head2 XML configuration files
  98
  99 The format of XML fles has not changed, so you simply copy
 100 all locally defined files into F</usr/local/etc/torrus/xmlconfig>.
 101
 102 The following Shell commands might be of help. They copy all XML files that
 103 do not occur in F</usr/local/torrus/xmlconfig>, the default path for
 104 distribution supplied files:
 105
 106   cd /usr/local/rrfw-0.1/share/rrfw/xmlconfig/
 107
 108   find . -name '*.xml' -exec test ! -f /usr/local/torrus/xmlconfig/'{}' ';' \
 109     -print | cpio --create --file=/tmp/allxml.cpio
 110
 111   cd /usr/local/etc/torrus/xmlconfig/
 112
 113   cpio --extract --make-directories --preserve-modification-time \
 114     --file=/tmp/allxml.cpio
 115
 116 After copying XML files, compile them in Torrus:
 117
 118   torrus compilexml --all --verbose
 119
 120
 121
 122 =head2 Monitor actions
 123
 124 If you utilize the monitor daemon, you will most probably need
 125 to change the action statements.
 126
 127 In the action of type C<exec>, the C<command> parameter should be edited.
 128 RRFW was usually referencing the email notification command as
 129 I<$RRFW_HOME/bin/action_printemail>. In Torrus, this command should be
 130 referred as I<$TORRUS_BIN/action_printemail>.
 131
 132
 133
 134 =head2 SNMP discovery files
 135
 136   cd /usr/local/etc/torrus/
 137   cp /usr/local/rrfw-0.1/share/rrfw/discovery/*.ddx discovery/
 138
 139 The treatment of C<output-file> parameter has slightly changed.
 140 In RRFW, relative filename meant relative to the current working directory,
 141 and C<$XMLCONFIG> macro was used for referring the default XML files directory.
 142 In Torrus, C<$XMLCONFIG> is still supported, but it is advisory to get rid
 143 of it. Now the relative filenames refer to the user's XML directory,
 144 F</usr/local/torrus/xmlconfig>. Absolute filenames are used as they are.
 145
 146 In addition, C<torrus devdiscover> acepts the relative input file names,
 147 and searches for them in F</usr/local/torrus/discovery>.
 148
 149
 150
 151 =head2 Web interface ACLs
 152
 153   cd /usr/local/etc/torrus/
 154   /usr/local/rrfw-0.1/bin/acledit --export=acl.xml
 155   torrus acledit --import=acl.xml
 156
 157
 158
 159 =head2 Site-specific text templates
 160
 161 If you used some custom templates (HTML templates for the Web interface,
 162 or text templates for e-mail notifications), copy them to
 163 F</usr/local/etc/torrus/templates>. This directory should contain only
 164 your custom templates. Those delivered with the distribution packages are
 165 located in F</usr/local/torrus/templates>.
 166
 167
 168
 169 =head2 Apache configuration
 170
 171 Follow the Torrus Web interface guide and configure Apache accordingly.
 172 If needed, use the following Apache command to redirect the users which
 173 use the old URL:
 174
 175   Redirect /rrfw http://host.domain.com/torrus
 176
 177 After changing the configuration, stop and start Apache.
 178
 179
 180
 181 =head2 Stop RRFW collector and monitor processes
 182
 183 Depending on your system configuration, the command would look like
 184
 185   /etc/init.d/rrfw stop
 186
 187 Make sure that all old processes are stopped. Then remove the RRFW startup
 188 script from all rc.d directories.
 189
 190
 191
 192 =head2 Change the RRD files ownership
 193
 194 Depending on your system configuration, the paths for RRD files might be
 195 different.
 196
 197   chown torrus:torrus /var/snmpcollector/*
 198
 199
 200
 201 =head2 Test and run processes
 202
 203 For testing purposes, you might want to try launching the collector and
 204 monitor processes, as follows:
 205
 206   torrus collector --tree=mytree --runonce --debug
 207
 208 Then copy the Torrus startup script to your system's init directory and setup
 209 new symbolic links, if required. The following example should work for
 210 Sun Solaris:
 211
 212   cp TORRUS_DISTR/init.d/torrus /etc/init.d
 213   cd /etc/rc3.d
 214   ln -s S90torrus ../init.d/torrus
 215   cd /etc/rc0.d
 216   ln -s K90torrus ../init.d/torrus
 217
 218 Run the startup script and verify that RRD files get updated.
 219
 220
 221
 222 =head2 Update the cron jobs
 223
 224 RRFW's cron job F</usr/local/rrfw-0.1/bin/cleanup> should be replaced with
 225 the analogous job from Torrus: F</usr/local/torrus/bin/cleanup>
 226
 227
 228
 229 =head2 Update documentation
 230
 231 Update your site operational manuals to reflect the new software name,
 232 paths and URLs.
 233
 234
 235
 236 =head1 Author
 237
 238 Copyright (c) 2004 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>