NAME

DESCRIPTION

The configuration files may be used by more than one program, for example rrdbotd(8), or rrdbot-create(8). Some settings are shared between programs, while many are program specific. Settings not recognized are ignored.

An RRD file might only have one 'field' of values, or there may be multiple values which are stored together. Each of the fields have a name. Certain settings in the configuration file are used per field. Where you see <field> in the documentaion below, substitute the appropriate RRD field name.

SYNTAX

# Comment
[header]
setting: a value here
field.setting: part of value
               continuation of value

The configuration file is broken into blocks separated by headers. The header sections each have different sets of options and are described below.

The setting name (including a field name if necessary) is followed by a colon and then the value. Values may be continued onto successive lines, as long as those lines are indented with spaces or tabs.

Comments start with a # character at the leftmost margin.

GENERAL SETTINGS

rrd

The location of the RRD file. If not specified these are chosen automatically. See the FILE LOCATIONS topic below. When specified this should be a full path. Multiple RRD files may be specified.

[ Optional ]

raw

The location to output a raw CSV file. This location is first parsed by strftime with the poll time to find the resulting output location. When specified this should be a full path. Multiple raw files may be specified.

[ Optional ]

POLL SETTINGS

interval

The interval (in seconds) at which to retrieve the SNMP values and store them in the RRD file.

[ Required for rrdbotd(8) ]

<field>.source

Specifies the SNMP source and OID in a URL format. The <field> above should be replaced with the RRD field name. Multiple xxxxx.source options can be specified if the RRD file has multiple fields. The syntax of the SNMP url is as follows:

snmp[version]://community@host[:port]/oid[?query=value]
    

The following are valid SNMP urls:

snmp://public@gateway.example.com/sysUptime.0
snmp2c://mycommunity@uplink.example.com/ifInOctets.2
snmp2c://mycommunity@example.com/ifInOctets?idDescr=eth0
snmp://public@www.example.com:10161/1.3.6.1.2.1.1.3.0
snmp://pub@two.example.com,one.example.com/sysUptime.0
    

See TABLE QUERIES for more info on how to use the query part. See MULTIPLE HOSTS support for info on how to use multiple hosts.

To test that your SNMP urls are correct you can use the rrdbot-get(1) utility.

[ Required for rrdbotd(8) ]

timeout

The timeout (in seconds) to wait for an SNMP response.

CREATE SETTINGS

archive

The archives of values you would like to keep in your RRD. There can be multiple archives specified, separated by commas. The syntax of an archive is as follows:

<count>/<unit> * <how-many> <units>
    

The example below describes three archives of "2 per minute for 1 week", "4 per hour for 3 months", "3 per day for 1 year":

2/minute * 1 weeks, 4/hour * 3 months, 3/day * 1 year
    

[ Required for rrdbot-create 8 ]

cf

The consolidation functions to use to consolidate RRD values when archiving them. This applies to all fields in the RRD. There can be multiple functions specified, separated by commas. The valid functions are:

AVERAGE

Average out the values when archiving them.

LAST

Use the last value in the set to be archived.

MAX

Use the maximum value in the set to be archived.

MIN

Use the minimum value in the set to be archived.

[ Default: AVERAGE ]

<field>.max

The maximum value for the field. Use the character U to specify that there is no maximum (unbounded).

[ Default: U ]

<field>.min

The minimum value for the field. Use the character U to specify that there is no minimum (unbounded).

[ Default: U ]

<field>.type

The type of values that will be stored in this field. For more info see the rrdcreate(1) manual. The types are:

ABSOLUTE

Used for counters that get reset when read.

COUNTER

For values that increment between reads.

DERIVE

Used to measure rates of increase or decrease.

GAUGE

For values that are current, for example the temperature.

[ Default: ABSOLUTE ]

FILE LOCATIONS

# rrdbotd -V

The configuration files for SNMP pollers are laid out in a directory tree, with one file per RRD. Subdirectories can be used to organize the configuration files. The contents of the configuration files are described in rrdbot.conf(5).

By default the RRD files mirror the directory structure and names of the configuration files, with an .rrd extension appended to the filename.

For example if your configuration files are in a structure like the following:

/usr/local/etc/rrdbot/
  gateways/
    gateway-load.conf
    gateway-traffic.conf
  temperature/
    inside-temperature.conf
    outside-temperature.conf
  machine-load.conf

Then the default RRD files would be in a similar directory structure:

/var/db/rrdbot/
  gateways/
    gateway-load.conf.rrd
    gateway-traffic.conf.rrd
  temperature/
    inside-temperature.conf.rrd
    outside-temperature.conf.rrd
  machine-load.conf.rrd

The default location for an RRD file can be overridden by using the rrd option in the configuration file.

Once you have configuration files in place, you can use the rrdbot-create(8) tool to create the needed RRD files in the appropriate places.

MULTIPLE AGENTS

When combined with a query (see TABLE QUERIES) you can use this feature to search for a given value in a table on one of multiple agents.

To use failover, simply use multiple host names with commas (without a space) separating them. For example:

snmp://public@two.example.com,one.example.com/sysUptime.0

TABLE QUERIES

Add the OID and value you want to search for in the table to the end of the SNMP URL. Only one query value is supported.

For example to get the outbound packet count on the 'eth0' interface, you would use:

snmp://public@example.com/ifInUcastPkts?ifDescr=eth0

SEE ALSO

AUTHOR