1 # webintf.pod - Torrus web interface reference
2 # Copyright (C) 2002 Stanislav Sinyagin
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.
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.
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.
18 # Stanislav Sinyagin <ssinyagin@yahoo.com>
22 =head1 RRFW to Torrus migration guide
28 Torrus is the new marketing name for RRFW (Round-robin Database Framework),
29 a robust and flexible software package for data series processing.
30 The last release of RRFW is 0.1.8. The upcoming release 1.0.0 of Torrus
31 will introduce some significant changes and design improvements.
33 The directory structure of Torrus is more standards-compliant, and more
34 convenient for system adminisrators. The user files are strictly separated
35 from the distribution files. The XML configurations and HTML templates
36 are being searched in multiple directories, thus there will be no longer a
37 mixture of site-specific files with the ones from distribution.
39 In addition, Torrus introduces a commandline wrapper that is installed in
40 a generic directory for user executables (by default, F</usr/local/bin>).
41 This greatly simplifies the site administrator's tasks.
43 The plugins infrastructure is completely redesigned.
44 The plugin installation procedure is separated from the main software
45 installation. In addition, plugin installers set up their initialization
46 scripts in special directories, so that there's no need for plugin
47 initialization in F<torrus-siteconfig.pl> and other files.
49 Further on, we assume that RRFW is installed in its default directory,
50 F</usr/local/rrfw-0.1>, and Torrus is installed with default paths. These
51 paths may differ in your installation.
52 We refer to TORRUS_DISTR as the unpacked Torrus distribution path.
56 =head2 Software installation
58 Create a new user: C<torrus> and group: C<torrus>. The user ID that is
59 used by Apache process must be a member of this group. Depending on the
60 system, this user may be named as C<www>, C<httpd>, C<nobody> etc. Consult
61 your Apache configuration for details.
63 Install Torrus. If your system already runs RRFW release 0.1.8,
64 all prerequisites should be already in place. Then you simply unpack
65 the Torrus distribution, and from its directory execute
70 If required, download and unpack the Torrus plugins. Then for each plugin,
73 torrus install_plugin <UNPACKED_PLUGIN_DIR>
77 =head2 The Perl configuration files
79 Te distribution contains a short Shell script called
80 C<TORRUS_DISTR/setup_tools/replace_rrfw.sh>. This script takes one file name
81 as an argument, replaces all occurrences of I<RRFW> to I<Torrus> and I<rrfw>
82 to I<torrus>, and finally replaces the specified file with the new one.
84 Copy the site configuration files from RRFW to Torrus directory:
86 cd /usr/local/etc/torrus/
87 cp /usr/local/rrfw-0.1/share/rrfw/rrfw-siteconfig.pl \
88 conf/torrus-siteconfig.pl
89 TORRUS_DISTR/setup_tools/replace_rrfw.sh conf/torrus-siteconfig.pl
91 If needed, follow the same procedure for F<devdiscover-siteconfig.pl>
92 and other site configs.
96 =head2 XML configuration files
98 The format of XML fles has not changed, so you simply copy
99 all locally defined files into F</usr/local/etc/torrus/xmlconfig>.
101 The following Shell commands might be of help. They copy all XML files that
102 do not occur in F</usr/local/torrus/xmlconfig>, the default path for
103 distribution supplied files:
105 cd /usr/local/rrfw-0.1/share/rrfw/xmlconfig/
107 find . -name '*.xml' -exec test ! -f /usr/local/torrus/xmlconfig/'{}' ';' \
108 -print | cpio --create --file=/tmp/allxml.cpio
110 cd /usr/local/etc/torrus/xmlconfig/
112 cpio --extract --make-directories --preserve-modification-time \
113 --file=/tmp/allxml.cpio
115 After copying XML files, compile them in Torrus:
117 torrus compilexml --all --verbose
121 =head2 Monitor actions
123 If you utilize the monitor daemon, you will most probably need
124 to change the action statements.
126 In the action of type C<exec>, the C<command> parameter should be edited.
127 RRFW was usually referencing the email notification command as
128 I<$RRFW_HOME/bin/action_printemail>. In Torrus, this command should be
129 referred as I<$TORRUS_BIN/action_printemail>.
133 =head2 SNMP discovery files
135 cd /usr/local/etc/torrus/
136 cp /usr/local/rrfw-0.1/share/rrfw/discovery/*.ddx discovery/
138 The treatment of C<output-file> parameter has slightly changed.
139 In RRFW, relative filename meant relative to the current working directory,
140 and C<$XMLCONFIG> macro was used for referring the default XML files directory.
141 In Torrus, C<$XMLCONFIG> is still supported, but it is advisory to get rid
142 of it. Now the relative filenames refer to the user's XML directory,
143 F</usr/local/torrus/xmlconfig>. Absolute filenames are used as they are.
145 In addition, C<torrus devdiscover> acepts the relative input file names,
146 and searches for them in F</usr/local/torrus/discovery>.
150 =head2 Web interface ACLs
152 cd /usr/local/etc/torrus/
153 /usr/local/rrfw-0.1/bin/acledit --export=acl.xml
154 torrus acledit --import=acl.xml
158 =head2 Site-specific text templates
160 If you used some custom templates (HTML templates for the Web interface,
161 or text templates for e-mail notifications), copy them to
162 F</usr/local/etc/torrus/templates>. This directory should contain only
163 your custom templates. Those delivered with the distribution packages are
164 located in F</usr/local/torrus/templates>.
168 =head2 Apache configuration
170 Follow the Torrus Web interface guide and configure Apache accordingly.
171 If needed, use the following Apache command to redirect the users which
174 Redirect /rrfw http://host.domain.com/torrus
176 After changing the configuration, stop and start Apache.
180 =head2 Stop RRFW collector and monitor processes
182 Depending on your system configuration, the command would look like
184 /etc/init.d/rrfw stop
186 Make sure that all old processes are stopped. Then remove the RRFW startup
187 script from all rc.d directories.
191 =head2 Change the RRD files ownership
193 Depending on your system configuration, the paths for RRD files might be
196 chown torrus:torrus /var/snmpcollector/*
200 =head2 Test and run processes
202 For testing purposes, you might want to try launching the collector and
203 monitor processes, as follows:
205 torrus collector --tree=mytree --runonce --debug
207 Then copy the Torrus startup script to your system's init directory and setup
208 new symbolic links, if required. The following example should work for
211 cp TORRUS_DISTR/init.d/torrus /etc/init.d
213 ln -s S90torrus ../init.d/torrus
215 ln -s K90torrus ../init.d/torrus
217 Run the startup script and verify that RRD files get updated.
221 =head2 Update the cron jobs
223 RRFW's cron job F</usr/local/rrfw-0.1/bin/cleanup> should be replaced with
224 the analogous job from Torrus: F</usr/local/torrus/bin/cleanup>
228 =head2 Update documentation
230 Update your site operational manuals to reflect the new software name,
237 Copyright (c) 2004 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>