From 9a78f86f773cbf34e29ec51fc06e3f04072c88d0 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Sun, 2 Mar 2008 01:25:00 +0000 Subject: - Support failover between multiple agents - Support table queries - Major refactoring of internals. --- doc/rrdbot-get.1 | 28 ++++++++++++++++++++++++++++ doc/rrdbot.conf.5 | 37 +++++++++++++++++++++++++++++++++++-- doc/rrdbotd.8 | 9 ++++++++- doc/traffic-example.conf | 6 ++++++ 4 files changed, 77 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/rrdbot-get.1 b/doc/rrdbot-get.1 index 48e4689..e9515d6 100644 --- a/doc/rrdbot-get.1 +++ b/doc/rrdbot-get.1 @@ -76,6 +76,34 @@ Prints the version of .Nm and the locations of the configuration files, RRD files etc. .El +.Sh MULTIPLE AGENTS +.Nm +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. +.Pp +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. +.Pp +To use failover, simply use multiple host names with commas (without a space) +separating them. For example: +.Bd -literal -offset indent +snmp://public@two.example.com,one.example.com/sysUptime.0 +.Ed +.Sh TABLE QUERIES +.Nm +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. +.Pp +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. +.Pp +For example to get the outbound packet count on the 'eth0' interface, you would use: +.Bd -literal -offset indent +snmp://public@example.com/ifInUcastPkts?ifDescr=eth0 +.Ed .Sh SEE ALSO .Xr rrdbotd 8 , .Xr rrdbot.conf 5 , diff --git a/doc/rrdbot.conf.5 b/doc/rrdbot.conf.5 index ad93496..0a31ce4 100644 --- a/doc/rrdbot.conf.5 +++ b/doc/rrdbot.conf.5 @@ -111,16 +111,21 @@ above should be replaced with the RRD field name. Multiple options can be specified if the RRD file has multiple fields. The syntax of the SNMP url is as follows: .Bd -literal -offset indent -snmp[version]://community@host[:port]/oid +snmp[version]://community@host[:port]/oid[?query=value] .Ed .Pp The following are valid SNMP urls: .Bd -literal -offset indent 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 .Ed .Pp +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. +.Pp To test that your SNMP urls are correct you can use the .Xr rrdbot-get 1 utility. @@ -254,7 +259,35 @@ option in the configuration file. .Pp Once you have configuration files in place, you can use the .Xr rrdbot-create 8 -tool to create the needed RRD files in the appropriate places. +tool to create the needed RRD files in the appropriate places. +.Sh MULTIPLE AGENTS +.Xr 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. +.Pp +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. +.Pp +To use failover, simply use multiple host names with commas (without a space) +separating them. For example: +.Bd -literal -offset indent +snmp://public@two.example.com,one.example.com/sysUptime.0 +.Ed +.Sh TABLE QUERIES +.Xr 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. +.Pp +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. +.Pp +For example to get the outbound packet count on the 'eth0' interface, you would use: +.Bd -literal -offset indent +snmp://public@example.com/ifInUcastPkts?ifDescr=eth0 +.Ed .Sh SEE ALSO .Xr rrdbotd 8 , .Xr rrdbot-create 8 , diff --git a/doc/rrdbotd.8 b/doc/rrdbotd.8 index bc4d7fd..8217626 100644 --- a/doc/rrdbotd.8 +++ b/doc/rrdbotd.8 @@ -56,7 +56,14 @@ .Nm is an SNMP polling daemon which writes the polled values to an .Xr rrdtool 1 -RRD database. An can poll many different SNMP sources in an efficient manner. +RRD database. An can poll many different SNMP sources in an efficient manner. +.Pp +Table queries are supported, where the OID index of a certain value is not +known beforehand, or may change regularly. +.Pp +In addition multiple SNMP agents may be specified for a certain value. If +one SNMP agent cannot be contacted or errors for some reason, another one +will be tried. .Pp The configuration (eg: SNMP sources, polling intervals) are located in files in a directory, with one configuration file per RRD. The format of the diff --git a/doc/traffic-example.conf b/doc/traffic-example.conf index aea1b0d..e0d40d2 100644 --- a/doc/traffic-example.conf +++ b/doc/traffic-example.conf @@ -17,6 +17,12 @@ rrd: /var/db/rrds/traffic.rrd in.source: snmp://public@router.example.com/ifInOctets.2 out.source: snmp://public@router.example.com/ifOutOctets.2 +# You might also use table queries to acheive the above. +# If the interface's names is 'eth0', then this would work. +# +# in.source: snmp://public@router.example.com/ifInOctets?ifDescr=eth0 +# out.source: snmp://public@router.example.com/ifOutOctets?ifDescr=eth0 + # Poll every 10 seconds interval: 10 -- cgit v1.2.3