summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/rrdbot-get.128
-rw-r--r--doc/rrdbot.conf.537
-rw-r--r--doc/rrdbotd.89
-rw-r--r--doc/traffic-example.conf6
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