plugins/easytarget/tp-easytarget.pod.in

   1 =head1 EasyTarget, quick Torrus config generator
   2
   3 EastTarget is a Torrus plugin designed for those users who need
   4 to add some specific SNMP OIDs to Torrus collector, without
   5 having to edit the complex XML files. EasyTarget is a quick way to
   6 add a few new objects without too much efforts.
   7
   8 =head2 Installation
   9
  10 Follow the Torrus installation guide for the main software installation.
  11
  12 Install two Perl modules from CPAN:
  13
  14   perl -MCPAN -e 'install Config::Tiny'
  15   perl -MCPAN -e 'install Config::Any'
  16
  17 Unpack the plugin distribution package in some directory:
  18
  19   gzip -dc tp-easytarget-1.X.tar.gz | tar xvf -
  20
  21 Then run the Torrus plugin installation utility, pointing to the
  22 unpacked plugin directory:
  23
  24   torrus install_plugin tp-easytarget-1.X
  25
  26
  27 =head2 Quick steps
  28
  29 EasyTarget accepts input files in Windows-style INI format. It is important
  30 that the file extension is exactly ".ini". By default, the files are searched
  31 in the current directpoy and then in F<@sitedir@/easytarget>.
  32
  33 The input file consists of sections, each representing a leaf or a subtree
  34 of Torrus datasource tree. You define the default parameters at the top of
  35 the file in global section, and then create a section for
  36 each tree element that you want to define. Here is a minimalistic example:
  37
  38  OUTXML = mydevices.xml
  39
  40  [/EasyTarget/dev1]
  41  snmp-host = 10.0.0.1
  42  snmp-community = public
  43  snmp-object = 1.3.6.1.4.1.5655.4.2.2.1.1.1.1.1.1
  44
  45  [/EasyTarget/dev2]
  46  snmp-host = 10.0.0.2
  47  snmp-community = public
  48  snmp-object = 1.3.6.1.4.1.5655.4.2.2.1.1.1.1.1.1
  49
  50 Here's a more complex example:
  51
  52  OUTXML = mydevices.xml
  53
  54  [/EasyTarget/Myrouter/]
  55  snmp-host = 10.0.0.1
  56  snmp-community = public
  57
  58  [/EasyTarget/Myrouter/data1]
  59  snmp-object = 1.3.6.1.4.1.5655.4.2.2.1.1.1.1.1.1
  60
  61  [/EasyTarget/Myrouter/data2]
  62  snmp-object = 1.3.6.1.4.1.5655.4.2.2.1.1.1.1.2.1
  63
  64 Next step is to feed the input file to EasyTarget:
  65
  66  torrus et --in=mydevices.ini --verbose
  67
  68 Then you need to add the generated XML file to the tree by editing the
  69 F<torrus-siteconfig.pl> file, and compile the resulting tree:
  70
  71  torrus compile --tree=main --verbose
  72
  73 Now you can start the collector and Apache server if they aren't yet running.
  74 If they were already running, you don't need to restart them.
  75
  76
  77 =head2 Plugin documentation
  78
  79 The input file for the EasyTarget plugin is a two-level configuration file.
  80 Currently Windows-style INI format is supported. Other formats implemented in
  81 C<Config::Any> Perl module should also work, but they were not tested.
  82
  83 The input file consists of two parts: the global parameters and
  84 per-section parameters. The section name defines the Torrus datasource
  85 subtree or leaf: if the name ends with the slash (/), it denotes a subtree
  86 and defines parameters for child leaves. Otherwise the section defines
  87 a leaf. The section name should always start with slash.
  88
  89 There are two types of parameters: the ones consisting of capitals ([A-Z]) are
  90 the parameters for the EasyTarget engine, and all others are the parameters
  91 passed to the generated Torrus config file.
  92
  93 The prarameter C<easytarget-node> is set to the path as specified in the
  94 section header in the input INI file.
  95
  96 There is no parameter inheritance. You can only define either a parameter
  97 on the global level, or in each of the sections. That means, for example,
  98 that if C<OUTXML> is missing at the global level, it should be present
  99 in each section, regardless of the generated tree hierarchy.
 100 If a parameter exists both at the global level and in a section,
 101 the value in the section overrides the global one.
 102
 103 EasyTarget understands the following parameters:
 104
 105 =over 4
 106
 107 =item * C<OUTXML>
 108
 109 The name of the generated Torrus configuration XML. This parameter can be
 110 set globally or per-section. For example, the value F<myisp1/targets1.xml>
 111 would cause EasyTarget to generate the file
 112 F<@sitexmldir@/myisp1/targets1.xml>.
 113
 114 =item * C<BUNDLE>
 115
 116 This parameter specifies the name of Torrus XML conifg file that would
 117 include C<E<lt>incldeE<gt>> statements for every C<OUTXML> in every section.
 118 This is useful if the EasyTarget file is long enough (e.g. automatically
 119 generated by an external program) and contains multiple output file statements.
 120
 121 =item * C<INCLUDE>
 122
 123 Set this parameter to a comma-separated list of XML file names that
 124 should be included in the generated file. Usually suh files contain some
 125 template definitions.
 126
 127 =item * C<TEMPLATES>
 128
 129 Comma-separated list of templates that will be applied at the given
 130 subtree or leaf in the output file.
 131
 132 =back
 133
 134 The following parameters are set implicitly to their default values:
 135
 136 =over 4
 137
 138 =item * C<data-dir>: '@defrrddir@'
 139
 140 This value is taken from the one given in C<defrrddir=DIR> parameter of
 141 the Torrus configure script at its installation time. This is the directory
 142 where the collector will generate the RRD files.
 143
 144 =item * C<data-file>: '%system-id%.easytarget.rrd'
 145
 146 This is the name of RRD file. System-id parameter is usually equal to
 147 snmp-host.
 148
 149 =item * C<rrd-ds>: the same as the name of the leaf
 150
 151 This is the datasource name used in the RRD file for the corresponding
 152 dataelement. It is usually equal to the last word in the leaf path,
 153 and can be overridden by explicitly defining the parameter.
 154
 155 =item * C<snmp-version>: 2c
 156
 157 =item * C<snmp-port>: 161
 158
 159 =item * C<rrd-create-dstype>: 'COUNTER'
 160
 161 This is the type of the datasource to be collected. In case of non-counter
 162 type of the OID, this parameter should be changed to C<GAUGE>.
 163
 164 =item * C<nodeid>: 'et//%easytarget-node%'
 165
 166 =back
 167
 168 By default, EasyTarget applies the template C<snmp-defaults> from
 169 C<snmp-defs.xml> to each leaf.
 170
 171 The minimum set of parameters that should be defined in EasyTarget
 172 input files are: C<OUTXML>, C<snmp-host>, C<snmp-community>
 173 and C<snmp-object>.
 174
 175 =head1 Author
 176
 177 Copyright (c) 2007 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>