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