torrus/doc/manpages/torrus_ttproclist.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_ttproclist.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $
  18 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  19 #
  20 #
  21
  22 =head1 NAME
  23
  24 ttproclist - Process a template with a nodelist
  25
  26 =head1 SYNOPSIS
  27
  28 B<torrus ttproclist> --tmpl=I<TFILE> --out=I<OFILE>
  29 --nodes=I<NFILE> [I<options...>]
  30
  31 =head1 DESCRIPTION
  32
  33 This command takes a Template-Toolkit template and a list of nodes
  34 (usually SNMP devices) as input. The output file is a result of
  35 template substitution, according to the specified options.
  36 Command-line options B<--tmpl>, B<--out> and B<--nodes> are mandatory.
  37
  38 This utility can be used to generate the discovery instructions XML out of
  39 a predefined template and a dynamically generated list of devices.
  40 Alternatively, it can produce Torrus XML configuration for a given list
  41 of objects, etc.
  42
  43 The following variables are predefined when the template is processed:
  44
  45 =over 4
  46
  47 =item * C<nodes>
  48
  49 Hash array of nodes. Hash keys are the node names. Values are symbolic
  50 names. If symbolic names are not defined, values are the same as keys.
  51
  52 =item * C<param>
  53
  54 Hash array of command-line parameters given in B<--param> option.
  55
  56 =item * C<nodesfile>, C<creator>
  57
  58 Informative variables. They can be used to produce the creation
  59 note in the resulting files. C<nodesfile> returns the file name of nodes,
  60 and C<creator> returns a detailed information how the file was generated,
  61 with timestamp and command line options.
  62
  63 =back
  64
  65 =head1 OPTIONS
  66
  67 =over 4
  68
  69 =item B<--tmpl>=I<TFILE>
  70
  71 The file name of the input template. Relative names are looked in
  72 the current directory and in F<@tmpluserdir@>. The file name may also be
  73 an absolute path.
  74
  75 =item B<--out>=I<OFILE>
  76
  77 Output file name. If no absolute path given, the file is written in the current
  78 directory.
  79
  80 =item B<--nodes>=I<NFILE>
  81
  82 The name of the nodes list. Nodes should be separated by space or tab
  83 character or newline. Additional information, referred to as symbolic name,
  84 can be supplied after a colon, of the form NODENAME:SYMBOLICNAME.
  85
  86 =item B<--param>=I<NAME:VALUE,NAME:VALUE...>
  87
  88 List of optional parameters that may be used in the template.
  89
  90 =back
  91
  92 =head1 EXAMPLES
  93
  94 The following example gerenates C<devdiscover> input file from a template.
  95 The template is as follows:
  96
  97  <?xml version="1.0" encoding="UTF8"?>
  98  <snmp-discovery>
  99  >>> usual DDX parameters here, like SNMP community and data-dir
 100   <param name="snmp-community" value="private"/>
 101   <param...
 102  >>> This loop generates per-host entries
 103   [% FOREACH n = nodes.keys.sort %]
 104   <host>
 105     <param name="snmp-host" value="[% n %]"/>
 106     <param name="symbolic-name" value="[% nodes.$n %]"/>
 107     <param name="output-file" value="nodes/[% n %].xml"/>
 108   </host>
 109   [% END %]
 110  >>> Generate the bundle file, so that you need only one
 111  >>> entry in torrus-site-config.pl
 112   <param name="output-bundle" value="[% param.BUNDLE %].xml"/>
 113  </snmp-discovery>
 114
 115 The following command would generate F<MY.ddx> from template file F<MY.ddtmpl>
 116 as described above. The file F<MY.nodes> is a list of SNMP devices, one per
 117 line. Then C<devdiscover> is launched with F<MY.ddx> as input. Note also the
 118 short form of the command line wrapper.
 119
 120  torrus ttproclist --tmpl=MY.ddtmpl \
 121    --nodes=MY.nodes \
 122    --out=/usr/local/etc/torrus/discovery/MY.ddx \
 123    --param=BUNDLE:MYNODES
 124
 125  torrus dd --in=MY.ddx --verbose
 126
 127 In addition, you may put some common parameters in Template BLOCK
 128 statement in a separate file, and INCLUDE it in your templates. See the
 129 Template-Toolkit documentation for more detail.
 130
 131
 132 =head1 NOTES
 133
 134 See more documentation at Torrus home page: http://torrus.org
 135
 136 =head1 SEE ALSO
 137
 138 Template-Toolkit documentation: http://template-toolkit.org/
 139
 140 L<torrus(@mansec_usercmd@)>, L<torrus_devdiscover(@mansec_usercmd@)>
 141
 142 =head1 AUTHOR
 143
 144 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>