Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
rrdbot.conf(5)		  FreeBSD 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	multi-
     ple 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 cho-
		 sen 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
     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 val-
		 ues 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
     These settings are	used by	the rrdbot-create(8) tool to automatically
     create 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	com-
		 mas. 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 com-
		 mas. 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 spec-
		 ify that there	is no maximum (unbounded).

		 [ Default: U ]

     _field_.min
		 The minimum value for the field. Use the character U to spec-
		 ify 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
     configuration files. The contents of the configuration files are de-
     scribed 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 fol-
     lowing:

	   /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
     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				  May 9, 2021				rrdbot

NAME | DESCRIPTION | SYNTAX | GENERAL SETTINGS | POLL SETTINGS | CREATE SETTINGS | FILE LOCATIONS | MULTIPLE AGENTS | TABLE QUERIES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rrdbot.conf&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help