home | help 
rrdbot.conf(5)		       File Formats Manual		  rrdbot.conf(5)

NAME
     rrdbot.conf -- configuration files for rrdbotd(8)

DESCRIPTION
     rrdbotd(8) is an SNMP polling daemon. It writes out the polled values to an
     rrdtool(1)  database.  The  configuration	files  describe what to poll and
     where the resulting RRD files are.

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

     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
     The general syntax of an RRD file is as follows:

	   # 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 be-
     low.

     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
     These settings go under the [general] header in a configuration file.

     rrd	 The location of the RRD file. If not specified these are chosen
		 automatically.  See the FILE LOCATIONS topic below. When speci-
		 fied  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
     Settings  to  control when and how the SNMP source is polled by rrdbotd(8).
     These settings go under the [poll] heading.

     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 mul-
		 tiple 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
     These settings are used by the rrdbot-create(8) tool to automatically  cre-
     ate RRD files for you. Put these settings under the [create] header.

     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  tem-
			     perature.

		 [ Default: ABSOLUTE ]

FILE LOCATIONS
     To determine the default location for the configuration files and RRD files
     run this command:

	   # 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	configu-
     ration files. The contents of the configuration files are described in rrd-
     bot.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 follow-
     ing:

	   /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 op-
     tion in the configuration file.

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

MULTIPLE AGENTS
     rrdbotd(8)  supports  failover  between  multiple	agents. If an SNMP query
     fails on one agent or a value is not found when querying an agent, then  it
     will switch to another configured agent.

     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
     rrdbotd(8)  can  query a value that corresponds to a certain row in an SNMP
     table. On many SNMP agents the indexes of rows in tables are not fixed, and
     this allows you to retrieve a certain value no matter what row of the table
     it is on.

     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
     rrdbotd(8), rrdbot-create(8), rrdbot-get(1), rrdtool(1)

AUTHOR
     Stef Walter <stef@memberwebs.com>

rrdbot				  August, 2006			  rrdbot.conf(5)
home | help