summaryrefslogtreecommitdiff
path: root/doc/rrdbot.conf.5
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rrdbot.conf.5')
-rw-r--r--doc/rrdbot.conf.5264
1 files changed, 264 insertions, 0 deletions
diff --git a/doc/rrdbot.conf.5 b/doc/rrdbot.conf.5
new file mode 100644
index 0000000..bf4f88f
--- /dev/null
+++ b/doc/rrdbot.conf.5
@@ -0,0 +1,264 @@
+.\"
+.\" Copyright (c) 2006, Nate Nielsen
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" * Redistributions of source code must retain the above
+.\" copyright notice, this list of conditions and the
+.\" following disclaimer.
+.\" * Redistributions in binary form must reproduce the
+.\" above copyright notice, this list of conditions and
+.\" the following disclaimer in the documentation and/or
+.\" other materials provided with the distribution.
+.\" * The names of contributors to this software may not be
+.\" used to endorse or promote products derived from this
+.\" software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+.\" COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+.\" OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+.\" THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+.\" DAMAGE.
+.\"
+.\"
+.\" CONTRIBUTORS
+.\" Nate Nielsen <nielsen@memberwebs.com>
+.\"
+.Dd August, 2006
+.Dt rrdbot.conf 5
+.Os rrdbot
+.Sh NAME
+.Nm rrdbot.conf
+.Nd configuration files for
+.Xr rrdbotd 8
+.Sh DESCRIPTION
+.Xr rrdbotd 8
+is an SNMP polling daemon. It writes out the polled values to an
+.Xr rrdtool 1
+database. The configuration files describe what to poll and where the resulting
+RRD files are.
+.Pp
+The configuration files may be used by more than one program, for example
+.Xr rrdbotd 8 ,
+or
+.Xr rrdbot-create 8 .
+Some settings are shared between programs, while many are program specific.
+Settings not recognized are ignored.
+.Pp
+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
+.Ar <field>
+in the documentaion below, substitute the appropriate RRD field name.
+.Sh SYNTAX
+The general syntax of an RRD file is as follows:
+.Bd -literal -offset indent
+# Comment
+[header]
+setting: a value here
+field.setting: part of value
+ continuation of value
+.Ed
+.Pp
+The configuration file is broken into blocks separated by headers. The header
+sections each have different sets of options and are described below.
+.Pp
+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.
+.Pp
+Comments start with a # character at the leftmost margin.
+.Sh GENERAL SETTINGS
+These settings go under the
+.Ar [general]
+header in a configuration file.
+.Bl -tag -width Fl
+.It Ar rrd
+The location of the RRD file. If not specified these are chosen automatically.
+See the FILE LOCATIONS topic below. When specified this should be a full path.
+.Pp
+[ Optional ]
+.El
+.Sh POLL SETTINGS
+Settings to control when and how the SNMP source is polled by
+.Xr rrdbotd 8 .
+These settings go under the
+.Ar [poll]
+heading.
+.Bl -tag -width Fl
+.It Ar interval
+The interval (in seconds) at which to retrieve the SNMP values and store them in
+the RRD file.
+.Pp
+[ Required for
+.Xr rrdbotd 8
+]
+.It Ar <field>.source
+Specifies the SNMP source and OID in a URL format. The
+.Ar <field>
+above should be replaced with the RRD field name. Multiple
+.Ar xxxxx.source
+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
+.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
+snmp://public@www.example.com:10161/1.3.6.1.2.1.1.3.0
+.Ed
+.Pp
+To test that your SNMP urls are correct you can use the
+.Xr rrdbot-get 1
+utility.
+.Pp
+[ Required for
+.Xr rrdbotd 8
+]
+.It Ar timeout
+The timeout (in seconds) to wait for an SNMP response.
+.El
+.Sh CREATE SETTINGS
+These settings are used by the
+.Xr rrdbot-create 8
+tool to automatically create RRD files for you. Put these settings under the
+.Ar [create]
+header.
+.Bl -tag -width Fl
+.It Ar 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:
+.Bd -literal -offset indent
+<count>/<unit> * <how-many> <units>
+.Ed
+.Pp
+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":
+.Bd -literal -offset indent
+2/minute * 1 weeks, 4/hour * 3 months, 3/day * 1 year
+.Ed
+.Pp
+[ Required for
+rrdbot-create 8
+]
+.It Ar cf
+This is the consolidation function to use to consolidate RRD values when
+archiving them. This applies to all fields in the RRD. The valid settings are:
+.Bl -tag -width Fl
+.It Ar AVERAGE
+Average out the values when archiving them.
+.It Ar LAST
+Use the last value in the set to be archived.
+.It Ar MAX
+Use the maximum value in the set to be archived.
+.It Ar MIN
+Use the minimum value in the set to be archived.
+.El
+.Pp
+[ Default:
+.Ar AVERAGE
+]
+.It Ar <field>.max
+The maximum value for the field. Use the character
+.Ar U
+to specify that there is no maximum (unbounded).
+.Pp
+[ Default:
+.Ar U
+]
+.It Ar <field>.min
+The minimum value for the field. Use the character
+.Ar U
+to specify that there is no minimum (unbounded).
+.Pp
+[ Default:
+.Ar U
+]
+.It Ar <field>.type
+The type of values that will be stored in this field. For more info see the
+.Xr rrdcreate 1
+manual. The types are:
+.Bl -tag -width Fl
+.It Ar ABSOLUTE
+Used for counters that get reset when read.
+.It Ar COUNTER
+For values that increment between reads.
+.It Ar DERIVE
+Used to measure rates of increase or decrease.
+.It Ar GAUGE
+For values that are current, for example the temperature.
+.El
+.Pp
+[ Default:
+.Ar ABSOLUTE
+]
+.El
+.Sh FILE LOCATIONS
+To determine the default location for the configuration files and RRD files
+run this command:
+.Bd -literal -offset indent
+# rrdbotd -V
+.Ed
+.Pp
+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 described
+in
+.Xr rrdbot.conf 5 .
+.Pp
+By default the RRD files mirror the directory structure and names of the
+configuration files, with an
+.Pa .rrd
+extension appended to the filename.
+.Pp
+For example if your configuration files are in a structure like the following:
+.Bd -literal -offset indent
+/usr/local/etc/rrdbot/
+ gateways/
+ gateway-load.conf
+ gateway-traffic.conf
+ temperature/
+ inside-temperature.conf
+ outside-temperature.conf
+ machine-load.conf
+.Ed
+.Pp
+Then the default RRD files would be in a similar directory structure:
+.Bd -literal -offset indent
+/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
+.Ed
+.Pp
+The default location for an RRD file can be overridden by using the
+.Ar rrd
+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.
+.Sh SEE ALSO
+.Xr rrdbotd 8 ,
+.Xr rrdbot-create 8 ,
+.Xr rrdbot-get 1 ,
+.Xr rrdtool 1
+.Sh AUTHOR
+.An Nate Nielsen Aq nielsen@memberwebs.com