- REQUIRED CONFIGURATION
- OPTIONAL CONFIGURATION
- LOGGING CONFIGURATION
- SEE ALSO
- COPYRIGHT AND LICENSE
YATG::Config - Configuration management for YATG
yatg_updater expects one command line argument, which is its main configuration file. This must be in a format recognizable to Config::Any, and you must use a file name suffix to give that module a hint.
There is a fairly complete example of this configuration file in the
examples/ folder of this distribution - look for the
yatg.yml file. The file must parse out to an anonymous hash of hashes, as in the example.
Let's first consider the
yatg key/value, which is the main configuration area.
This is a hash, with keys being the Leaf Name of an SNMP OID. This tells
yatg_updater the list of OIDs which you would like gathering from each network device. The value for each leaf name key is a list of magic words which tell
yatg_updater whether to get the OID, and what to do with the results. Some of the magic words are mutually exclusive.
# example key and "magic words" list value yatg: oids: ifOperStatus: [disk, ifindex]
These are the storage methods for the results, and an OID without one of these magic words will be ignored. Multiple storage methods can be given for any OID.
This means to use the Data::Printer to print results. It's good for testing.
Disk storage means to create a file for each OID of each port on each device. It is very fast and efficient by design, and most useful for long-term historical data such as port traffic counters.
If you don't need data history, then this module is a better alternative than disk-based storage, because of its speed. A memcached server is required of course.
This is merely an extension to the Disk storage module which allows
yatg_updaterto use disk on another machine. You can think of it as an RPC-based alternative to network mounting a filesystem. On the remote host, the Disk module is then used for storage.
If you wish to submit data to Nagios as a passive service check result, then this method can be configured to contact an NSCA daemon on your Nagios server.
Interface Indexed OIDs
yatg_updater will happily poll single value or plain indexed OIDs, you can give it a hint that there is an interface-indexed OID in use.
In that case,
yatg_updater will make sure that
IfAdminStatus are retrieved from the device, and results will be keyed by human-friendly names (e.g.
FastEthernet2/1) rather than SNMP interface indexes (e.g.
Furthermore, only results for "interesting" interfaces will be stored. This is defined as interfaces which are administratively configured to the "up" state, and whose name does not match an exclusion list (various private sub-interfaces, which are uninteresting). This measure will save you time when storing results to disk as you only save what is interesting. If you store results for a port, then shut it down and some time later start it up again, the results file will be padded out for the period of shut-down time and appended with the new results.
Being indexed by interface is something
yatg_updater cannot work out for itself for an OID, so provide the
ifindex magic word to enable this feature.
IP address filtering
We have not yet covered how
yatg_updater obtains its list of devices to poll, but for now all you need to know is that by default all listed leaf names will be polled on all devices.
You can however provide magic words to override this behaviour and reduce the device space to be polled for a leaf name. Each of these magic words may appear more than once:
Any IP address or IP subnet will be taken as a restriction placed upon the default list of device IPs, for this OID only.
Not providing an explicit IP address or IP subnet means the OID will be polled on all devices in the default list.
Using an exclamation mark at the head of the IP address introduces an exclusion filter upon the cached list of IP addresses.
This prevents the OID from being checked on the given devices, even if the device IP is also given in a magic word, as above.
In case it is not clear, an IP address and an IP subnet are no different - a
/32 subnet mask is assumed in the case of an IP address.
Provide a list of SNMP community strings to the system using this parameter. For each device, at startup,
yatg_updater will work out which community to use and cache that for subsequent SNMP polling. For example:
yatg: communities: [public, anotherone]
The default value for this is
[ public ].
dbi_connect and the list of devices
yatg_updater needs to be given a list of device IPs which it should poll with SNMP.
yatg_updater will make a connection to a database and gather IPs.
By default the SQL query is set for use with NetDisco, so if you use that system you only need alter the DBI connection parameters (password, etc) in the
dbi_connect value in the example configuration file.
If you want to use a different SQL query, add a new key and value to the configuration:
yatg: dbi_ip_query: 'SELECT ip FROM device;'
The query must return a single list of IPs (suitable for DBI's
selectcol_arrayref). If you don't have a back-end database with such information, then install SQLite and quickly set one up (see YATG::Tutorial for help). It's good practice for asset management, if nothing else.
If you use NetDisco, and have the MIB files from that distribution installed in
/usr/share/netdisco/mibs/... then you can probably ignore this as the default will work.
Otherwise, you must provide this application with all the MIBs required to translate leaf names to OIDs and get data types for polled values. This key takes a list of directories on your system which contain MIB files. They will all be loaded when
yatg_updater starts, so only specify what you need otherwise that will take a long time.
Here is an example in YAML:
yatg: mibdirs: ['/usr/share/netdisco/mibs/cisco', '/usr/share/netdisco/mibs/rfc', '/usr/share/netdisco/mibs/net-snmp']
There are some additional, optional keys for the
yatg_updaterpolls all devices at a given interval. Provide a number of settings to this key if you want to override the default of 300 (5 minutes). An alternative is the
If the poller does not return data from all devices within
timeoutseconds, then the application will die. The default is 280. You should always have a little head-room between the
This system uses
SNMP::Effectivefor the SNMP polling, which is a fast, lightweight wrapper to the
SNMP::Effectivepolls asynchronously and you can set the maximum number of polls which are happening at once using this key. The default is 20 which is reasonably for any modern computer.
As YATG is a long-running process, you might occasionally want to update its list of hosts to monitor. Of course you can send a
SIGHUPand have YATG reload entirely, but this can be slow because of the re-checking of SNMP communities, and also requires an external process to send the signal.
If the YATG config has not changed, but you wish to update the list of monitored hosts, then set
newhosts_watchto the name of a file. The modification time of the file is watched and if it updates then YATG retrieves a new set of hosts (and host names and interface filters, if configured), on the next polling run.
If this key has a true value,
yatg_updaterwill print out various messages on standard output, instead of using a log file. It's handy for testing, and defaults to false of course. An alternative is the
This module uses
Log::Dispatch::Syslog for logging, and by default will log timing data to your system's syslog service. The following parameters can be overridden in a section at the same level as
oids, but called
These are the tokens used to identify the process to syslog, and both default to
By default the logging level will be
infoso override this to change that.
By default the syslog facility will be
local1so override this to change that.
Here is an example of what you might do:
log_dispatch_syslog: name: 'my_app' ident: 'my_app' min_level: 'warning' facility: 'local4'
Oliver Gorwits <email@example.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by University of Oxford.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.