/ 
YATG-5.20002
River stage zero No dependents
/ YATG::Config

NAME

YATG::Config - Configuration management for YATG

VERSION

version 5.140510

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::Printer 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. 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.

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.

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 yatg 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). An alternative is the YATG_INTERVAL environment setting.

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.

newhosts_watch

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 SIGHUP and 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_watch to 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.

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. An alternative is the YATG_DEBUG environment setting.

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