diff options
Diffstat (limited to 'doc/rrdbot.conf.5')
| -rw-r--r-- | doc/rrdbot.conf.5 | 264 |
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 |