Where device configurations must be dynamically determined,
configuration scripts must be provided to map SNMP objects to counter
names for output by snmpacc.
Scripts are configured by the use of the script configuration
option to name the script to be run. If no script option is
specified, no script will be run, and the configuration must be specified
in the configuration file.
Scripts are activated whenever snmpacc does not have information
about a device, or does not believe that the information is current. In
this case, snmpacc will not use the old information but will wait
for the script to complete successfully before continuing to poll the
device.
In addition, the checkevery option can be used to regularly update
the configuration. In this case, old information is used until the
script completes; on successful completion of the script, the old data
is discarded and new data installed.
Scripts may define multiple ``virtual'' objects with different IP
addresses and/or SNMP community names. These will be tied to the
``master'' object specified in the configuration file. This allows
a script to query a real device and report the virtual devices and
objects configured on it.
Script files are run from the directory specified by the
scriptdir option, and must be set up as normal executable scripts,
i.e. with an appropriate ``#! <interpreter>'' line (if not a binary
image) and protection modes of allowing the user snmpacc runs under
to execute the script.
Configuration scripts are passed three parameters. These are:
-
the device name, as specified in the associated device statement of
the configuration file;
-
the IP address or name of the device, as specified in the address
statement of the configuration file (this defaults to the device name if
no address line is specified; and
-
the SNMP community string, from the community statement of the
configuration file (default ``public'').
The script should then query the specified device and determine its
configuration. snmpacc buffers all output from the script until the
script terminates. If the script returns 0, the script's output is then
processed by snmpacc. If the script returns any other value, or
terminates due to a signal, the output is discarded. This permits a
script to abandon its processing at any time, regardless of any output
generated.
Error or debugging messages from the script should be printed on
standard error; such messages will be logged by snmpacc.
Scripts can output two types of records: ``device'' records and
``object'' records. These records must be written to standard output as
text lines terminated by a line feed character and with fields separated
by TAB characters.
There must be a device record, followed by zero or more object
records. This may be followed by another device record and object
records to define multiple virtual devices.
The format for a device record is as follows:
device <devnam> <address> <community>
The device record determines the actual devices that will be polled.
<devnam> is the device name; this must be a unique name for the
device. The <address> and <community> strings determine the IP
address or name of the device to be polled, and the community string to
apply when polling.
Note that the address and community need not match the address and
community of the device specified in the configuration file; when using
a configuration script, these parameters are used soley for passing to
the configuration script to allow it to determine the configuration of
the actual devices to be polled.
A device record should be followed by object records. Object records
are in the format:
object <oid-name> <counter-name>
The <oid-name> field is the name of an SNMP variable to query.
<counter-name> is the name of the counter to to add traffic counted
by the <oid-name> variable.