The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
YATG-4.112532
River stage zero No dependents
++
/ YATG::Config

NAME

YATG::Config - Configuration management for YATG

VERSION

version 4.112532

REQUIRED CONFIGURATION

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.

oids

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]

Storage

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.

stdout

This means to use the Data::Dumper to print results. It's good for testing.

See YATG::Store::STDOUT.

disk

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.

See YATG::Store::Disk.

memcached

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.

See YATG::Store::Memcached.

rpc

This is merely an extension to the Disk storage module which allows yatg_updater to 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.

See YATG::Store::RPC.

nsca

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.

See YATG::Store::NSCA.

Interface Indexed OIDs

Although 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 IfDescr and 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. 10101).

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:

192.2.1.10 or 192.1.1.0/24

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.

!192.2.1.10 or !192.1.1.0/24

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.

communities

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

At start-up, yatg_updater needs to be given a list of device IPs which it should poll with SNMP. We designed this system to work with NetDisco (a network management system) which populates a back-end database with device IPs. 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 like so (this is an example, of course!):

 yatg:
     dbi_ip_query: 'select ip from device;'

The query must return a single list of IPs. If you don't have a back-end database with such information, then install SQLite and quickly set one up. It's good practice for asset management, if nothing else.

mibdirs

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. Also make sure all references in the MIBs are resolvable to other MIBs. There is a bug in the current release of NetDisco MIBs as it is missing two MIB files.

Here is an example in YAML:

 yatg:
     mibdirs:
         ['/usr/share/netdisco/mibs/cisco',
          '/usr/share/netdisco/mibs/rfc',
          '/usr/share/netdisco/mibs/net-snmp']

OPTIONAL CONFIGURATION

There are some additional, optional keys for the oids section:

interval

yatg_updater polls 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).

timeout

If the poller does not return data from all devices within timeout seconds, then the application will die. The default is 280. You should always have a little head-room between the timeout and interval.

max_pollers

This system uses SNMP::Effective for the SNMP polling, which is a fast, lightweight wrapper to the SNMP perl libraries. SNMP::Effective polls 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.

debug

If this key has a true value, yatg_updater will print out various messages on standard output, instead of using a log file. It's handy for testing, and defaults to false of course.

LOGGING CONFIGURATION

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 log_dispatch_syslog:

name and ident

These are the tokens used to identify the process to syslog, and both default to yatg.

min_level

By default the logging level will be info so override this to change that.

facility

By default the syslog facility will be local1 so 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'

SEE ALSO

http://www.netdisco.org/
http://www.sqlite.org/

AUTHOR

Oliver Gorwits <oliver@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 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.