src/doc/manpages/torrus_configsnapshot.pod.in

   1 #  Copyright (C) 2004  Stanislav Sinyagin
   2 #
   3 #  This program is free software; you can redistribute it and/or modify
   4 #  it under the terms of the GNU General Public License as published by
   5 #  the Free Software Foundation; either version 2 of the License, or
   6 #  (at your option) any later version.
   7 #
   8 #  This program is distributed in the hope that it will be useful,
   9 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 #  GNU General Public License for more details.
  12 #
  13 #  You should have received a copy of the GNU General Public License
  14 #  along with this program; if not, write to the Free Software
  15 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  16
  17 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  18 #
  19 #
  20
  21 =head1 NAME
  22
  23 configsnapshot - Generates a configuration snapshot for a Torrus tree.
  24
  25 =head1 SYNOPSIS
  26
  27 B<torrus configsnapshot> --tree=I<TREENAME> [I<options...>]
  28
  29 =head1 DESCRIPTION
  30
  31 This command generates a configuration snapshot from current
  32 datasources for tree I<TREENAME>. The output is an XML file, ready for
  33 compilation, representing all datasources, monitors and tokensets of a
  34 given tree. The snapshot does not include view definitions. Templates
  35 and file patterns are expanded inside the file. It does not require
  36 any other XML configuration files, except for F<defaults.xml> and your
  37 custom view definitions.
  38
  39 B<Warning:> C<configsnapshot> from RRFW release 0.1.5 will not work
  40 correctly with databases from previous releases. Use RRFW release
  41 C<0.1.4bf2> instead.  C<configsnapshot> utility from RRFW release 0.1.4bf2
  42 does not preserve aliases.
  43
  44 This utility is useful in Torrus upgrade process. In case when RRD files
  45 structure is changing in Torrus default templates, and user(s) demand to
  46 preserve the historical data, the following steps could be done:
  47
  48 =over 4
  49
  50 =item *
  51
  52 Stop the collector and monitor processes.
  53
  54 =item *
  55
  56 Install newest Torrus software and do not run C<compilexml> immediately.
  57
  58 =item *
  59
  60 Create snapshots of the trees that you want to preserve for historical reasons:
  61
  62   torrus configsnapshot --tree=myrouters \
  63     --out=@sitexmldir@/myrouters-snapshot.xml
  64
  65 =item *
  66
  67 If needed, move the existing RRD files into different directory. Then
  68 change the C<data-dir> parameters in the snapshot XML accordingly.
  69
  70 =item *
  71
  72 Create a new tree with only the snapshot file in it. Compile the tree.
  73
  74 =item *
  75
  76 At this stage, it is up to the user to decide wether to continue running the
  77 collector and monitor daemons for this new tree. The old data may be preserved
  78 for historical reference, and collector may be run with the newest tree
  79 structure and definitions.
  80
  81 =back
  82
  83 =head1 OPTIONS
  84
  85 =over 4
  86
  87 =item B<--tree>=I<TREE>
  88
  89 Mandatory parameter specifying the tree name.
  90
  91 =item B<--out>=I<FILE>
  92
  93 Sets the output file to I<FILE>. Default is F<snapshot.xml>.
  94
  95 =item B<--param>=I<PARAM>  B<--value>=I<VALUE>
  96
  97 Sets the filter on datasource leaves that have to be included in the snapshot.
  98 I<PARAM> specifies the name of the datasource parameter, and I<VALUE>
  99 sets the matching value. By default the numeric comparison is performed.
 100
 101 =item B<--op>=I<OPERATOR>
 102
 103 Sets the fiter comparison operator. Accepted values: B<=> (numeric),
 104 B<eq> (text string comparison), and B<re> (regular expression match). Default
 105 is numeric comparison.
 106
 107
 108 =item B<--verbose>
 109
 110 Displays some extra information.
 111
 112 =item B<--help>
 113
 114 Displays a help message.
 115
 116 =back
 117
 118 =head1 FILES
 119
 120 =over 4
 121
 122 =item F<@distxmldir@/defaults.xml>
 123
 124 XML configuration file with default settings for the datasources and
 125 tokensets, as well as default view definitions.
 126
 127 =item F<snapshot.xml>
 128
 129 Default B<configsnapshot> output file.
 130
 131 =back
 132
 133 =head1 SEE ALSO
 134
 135 L<torrus(@mansec_usercmd@)>, L<torrus_compilexml(@mansec_usercmd@)>
 136
 137 =head1 NOTES
 138
 139 See more documentation at Torrus home page: http://torrus.org
 140
 141 =head1 AUTHOR
 142
 143 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>