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