- Support failover between multiple agents

    - Support table queries
    - Major refactoring of internals. 

4 files changed, 77 insertions, 3 deletions

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