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