summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am12
-rwxr-xr-xdoc/man2html.pl230
-rw-r--r--doc/rrdbot-create.8147
-rw-r--r--doc/rrdbot-get.184
-rw-r--r--doc/rrdbot.conf.5264
-rw-r--r--doc/rrdbotd.8154
6 files changed, 891 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..2cb19ea
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,12 @@
+
+man_MANS = rrdbotd.8 rrdbot.conf.5 rrdbot-create.8 rrdbot-get.1
+
+# Simple way to make docs
+html:
+ perl man2html.pl rrdbotd.8 > rrdbotd.8.html
+ perl man2html.pl rrdbot.conf.5 > rrdbot.conf.5.html
+ perl man2html.pl rrdbot-create.8 > rrdbot-create.8.html
+ perl man2html.pl rrdbot-get.1 > rrdbot-get.1.html
+
+EXTRA_DIST = $(man_MANS) \
+ man2html.pl
diff --git a/doc/man2html.pl b/doc/man2html.pl
new file mode 100755
index 0000000..21e3ab5
--- /dev/null
+++ b/doc/man2html.pl
@@ -0,0 +1,230 @@
+#!/usr/bin/perl
+
+# TODO: We need to make this more resilient
+# currently expects args without enforcing
+
+$FIL = $NAM = $SEC = @ARGV[0];
+
+$NAM =~ s/^([^.]+)\..+$/$1/;
+$SEC =~ s/^.+\.([^.]+)$/$1/;
+
+$command = "groff";
+@args = split(" ", "-Tascii -mdoc $FIL");
+
+$enable_include_links = 0;
+
+man($NAM, $SEC);
+
+sub man {
+ local($name, $section) = @_;
+ local($_, $title, $head, *MAN);
+ local($html_name, $html_section, $prefix);
+ local(@manargs);
+ local($query) = $name;
+
+ # $section =~ s/^([0-9ln]).*$/$1/;
+ $section =~ tr/A-Z/a-z/;
+
+ $prefix = "Man ";
+ if ($alttitle) {
+ $prefix = "";
+ $title = &encode_title($alttitle);
+ $head = &encode_data($alttitle);
+ } elsif ($section) {
+ $title = &encode_title("${name}($section)");
+ $head = &encode_data("${name}($section)");
+ } else {
+ $title = &encode_title("${name}");
+ $head = &encode_data("${name}");
+ }
+
+ print &html_header("$title");
+ print "<H1>Man Page: ${title}</H1>";
+ print "<PRE>\n";
+
+ $html_name = &encode_data($name);
+ $html_section = &encode_data($section);
+
+ #print Dumper($sectionpath);
+ #print "yy $section yy $manpath\n";
+ if ($name =~ /^\s*$/) {
+ print "Empty input, no man page given.\n";
+ return;
+ }
+
+ if (index($name, '*') != -1) {
+ print "Invalid character input '*': $name\n";
+ return;
+ }
+
+ if ($section !~ /^[0-9ln]\w*$/ && $section ne '') {
+ print "Sorry, section `$section' is not valid\n";
+ return;
+ }
+
+ if (!$section) {
+ if ($sectionpath->{$manpath}) {
+ $section = "-S " . $sectionpath->{$manpath}{'path'};
+ } else {
+ $section = '';
+ }
+ } else {
+ if ($sectionpath->{$manpath}{$section}) {
+ $section = "-S " . $sectionpath->{$manpath}{$section};
+ } else {
+ $section = "-S $section";
+ }
+ }
+
+ # print "X $command{'man'} @manargs -- x $name x\n";
+ &proc(*MAN, $command, @args) ||
+ &mydie ("$0: open of $command{'man'} command failed: $!\n");
+ if (eof(MAN)) {
+ # print "X $command{'man'} @manargs -- x $name x\n";
+ print "Sorry, no data found for `$html_name" .
+ ($html_section ? "($html_section)": '') . "'.\n";
+ return;
+ }
+
+ local($space) = 1;
+ local(@sect);
+ local($i, $j);
+ while(<MAN>) {
+ # remove tailing white space
+ if (/^\s+$/) {
+ next if $space;
+ $space = 1;
+ } else {
+ $space = 0;
+ }
+
+ $_ = &encode_data($_);
+ if($enable_include_links &&
+ m,(<B>)?\#include(</B>)?\s+(<B>)?\&lt\;(.*\.h)\&gt\;(</B>)?,) {
+ $match = $4; ($regexp = $match) =~ s/\./\\\./;
+ s,$regexp,\<A HREF=\"$BASE/usr/include/$match\"\>$match\</A\>,;
+ }
+ /^\s/ && # skip headers
+ s,((<[IB]>)?[\w\_\.\-]+\s*(</[IB]>)?\s*\(([1-9ln][a-zA-Z]*)\)),&mlnk($1),oige;
+
+ # detect E-Mail Addreses in manpages
+ if (/\@/) {
+ s/([a-z0-9_\-\.]+\@[a-z0-9\-\.]+\.[a-z]+)/<A HREF="mailto:$1">$1<\/A>/gi;
+ }
+
+ # detect URLs in manpages
+ if (m%tp://%) {
+ s,((ftp|http)://[^\s<>\)]+),<A HREF="$1">$1</A>,gi;
+ }
+
+ if (/^<B>\S+/ && m%^<B>([^<]+)%) {
+ $i = $1; $j = &encode_url($i);
+ s%^<B>([^<]+)</B>%<B>$i</B>%;
+ push(@sect, $1);
+ }
+ print;
+ }
+ close(MAN);
+
+ print "<H6>Copyright, N. Nielsen&nbsp;&nbsp;&nbsp;[ <a href='./'>back</a> | <a href='../../'>home</a> ]</h6>";
+ print "</BODY>\n";
+ print "</HTML>\n";
+
+ # Sleep 0.35 seconds to avoid DoS attacs
+ select undef, undef, undef, 0.35;
+}
+
+# encode unknown data for use in <TITLE>...</TITILE>
+sub encode_title {
+ # like encode_url but less strict (I couldn't find docs on this)
+ local($_) = @_;
+ s/([\000-\031\%\&\<\>\177-\377])/sprintf('%%%02x',ord($1))/eg;
+ $_;
+}
+
+# encode unknown data for use in a URL <A HREF="...">
+sub encode_url {
+ local($_) = @_;
+ # rfc1738 says that ";"|"/"|"?"|":"|"@"|"&"|"=" may be reserved.
+ # And % is the escape character so we escape it along with
+ # single-quote('), double-quote("), grave accent(`), less than(<),
+ # greater than(>), and non-US-ASCII characters (binary data),
+ # and white space. Whew.
+ s/([\000-\032\;\/\?\:\@\&\=\%\'\"\`\<\>\177-\377 ])/sprintf('%%%02x',ord($1))/eg;
+ s/%20/+/g;
+ $_;
+}
+# encode unknown data for use inside markup attributes <MARKUP ATTR="...">
+sub encode_attribute {
+ # rfc1738 says to use entity references here
+ local($_) = @_;
+ s/([\000-\031\"\'\`\%\&\<\>\177-\377])/sprintf('\&#%03d;',ord($1))/eg;
+ $_;
+}
+# encode unknown text data for using as HTML,
+# treats ^H as overstrike ala nroff.
+sub encode_data {
+ local($_) = @_;
+ local($str);
+
+ # Escape &, < and >
+ s,\010[><&],,g;
+ s/\&/\&amp\;/g;
+ s/\</\&lt\;/g;
+ s/\>/\&gt\;/g;
+
+ s,((_\010.)+),($str = $1) =~ s/.\010//g; "<I>$str</I>";,ge;
+ s,(.\010)+,$1,g;
+
+ if (!s,((.\010.)+\s+(.\010.)+),($str = $1) =~ s/.\010//g; "<B>$str</B>";,ge) {
+ s,((.\010.)+),($str = $1) =~ s/.\010//g; "<B>$str</B>";,ge;
+ }
+
+ s,.\010,,g;
+
+ $_;
+}
+
+sub html_header {
+ return qq{<HTML>
+<HEAD>
+<TITLE>$_[0]</TITLE>
+<link rev="made" href="mailto:wosch\@FreeBSD.ORG">
+<META name="robots" content="nofollow">
+<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
+<link rel="stylesheet" type="text/css" href="/nielsen/style.css">
+</HEAD>
+<BODY BGCOLOR="#FFFFFF" TEXT="#000000">\n\n};
+}
+
+sub mlnk {
+ local($matched) = @_;
+ return qq{<U>$matched</U>};
+}
+
+sub proc {
+ local(*FH, $prog, @args) = @_;
+ local($pid) = open(FH, "-|");
+ return undef unless defined($pid);
+ if ($pid == 0) {
+ exec $prog, @args;
+ &mydie("exec $prog failed\n");
+ }
+ 1;
+}
+
+# CGI script must die with error status 0
+sub mydie {
+ local($message) = @_;
+ print &html_header("Error");
+ print $message;
+
+print qq{
+<p>
+<A HREF="$BASE">Index Page and Help</A>
+</BODY>
+</HTML>
+};
+
+ exit(0);
+}
diff --git a/doc/rrdbot-create.8 b/doc/rrdbot-create.8
new file mode 100644
index 0000000..c518c78
--- /dev/null
+++ b/doc/rrdbot-create.8
@@ -0,0 +1,147 @@
+.\"
+.\" 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-create 8
+.Os rrdbot
+.Sh NAME
+.Nm rddbot-create
+.Nd create the RRD files for
+.Xr rrdbotd 8
+to write values to.
+.Sh SYNOPSIS
+.Nm
+.Op Fl nv
+.Op Fl c Ar confdir
+.Op Fl w Ar workdir
+.Nm
+.Fl V
+.Sh DESCRIPTION
+.Xr rrdbotd 8
+is an SNMP polling daemon. It writes out the polled values to an
+.Xr rrdtool 1
+database. The
+.Nm
+tool can create those RRD files for you.
+.Pp
+.Nm
+uses configuration files, one per RRD, to determine where and how to do its
+work. Details of these files and which settings to put in them are found in the
+.Xr rrdbot.conf 5
+manual under the CREATE SECTION heading.
+.Pp
+By default th RRD files are created in the default work directory (see the FILE
+LOCATIONS section below). Files that already exist are not overwritten or
+modified in any way.
+.Pp
+You can use the
+.Fl n
+option to see the
+.Xr rrdtool 1
+commands that would be executed. This is useful if you want to customize the
+commands before running them.
+.Sh OPTIONS
+The options are as follows.
+.Bl -tag -width Fl
+.It Fl c Ar confdir
+The directory in which configuration files are stored. See below for info
+on the various file locations.
+.It Fl n
+Rather than create the files, print the
+.Xr rrdtool 1
+commands that would be used to create the files.
+.It Fl v
+Print verbose messages.
+.It Fl V
+Prints the version of
+.Nm
+and the locations of the configuration files, RRD files etc.
+.It Fl w Ar workdir
+The default directory where to look for RRD files. See below for info on
+the various file locations.
+.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.
+.Sh SEE ALSO
+.Xr rrdbotd 8 ,
+.Xr rrdbot.conf 5 ,
+.Xr rrdbot-get 1 ,
+.Xr rrdtool 1
+.Sh AUTHOR
+.An Nate Nielsen Aq nielsen@memberwebs.com
diff --git a/doc/rrdbot-get.1 b/doc/rrdbot-get.1
new file mode 100644
index 0000000..1d69141
--- /dev/null
+++ b/doc/rrdbot-get.1
@@ -0,0 +1,84 @@
+.\"
+.\" 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-get 1
+.Os rrdbot
+.Sh NAME
+.Nm rddbot-get
+.Nd retrieves an SNMP value from an SNMP uri
+.Sh SYNOPSIS
+.Nm
+.Op Fl Mnr
+.Op Fl m Ar mibdir
+.Op Fl t Ar timeout
+.Ar snmp://community@host/oid
+.Nm
+.Fl V
+.Sh DESCRIPTION
+.Nm
+retrieves an SNMP value from an SNMP URI. The format is the same as is used by
+.Xr rrdbotd 8 .
+You can use
+.Nm
+for testing SNMP polling while configuring
+.Xr rrdbotd 8 .
+.Sh OPTIONS
+The options are as follows.
+.Bl -tag -width Fl
+.It Fl m Ar mibdir
+The directory in which to look for MIB files. The default directory is
+usually sufficient.
+.It Fl M
+Display MIB parsing warnings.
+.It Fl n
+Display numeric OIDs.
+.It Fl r
+Recursively walk the SNMP values under the given OID.
+.It Fl t Ar timeout
+The amount of time (in seconds) to wait for an SNMP response. Defaults to
+5 seconds.
+.It Fl V
+Prints the version of
+.Nm
+and the locations of the configuration files, RRD files etc.
+.El
+.Sh SEE ALSO
+.Xr rrdbotd 8 ,
+.Xr rrdbot.conf 5 ,
+.Xr rrdbot-create 8
+.Sh AUTHOR
+.An Nate Nielsen Aq nielsen@memberwebs.com
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
diff --git a/doc/rrdbotd.8 b/doc/rrdbotd.8
new file mode 100644
index 0000000..4ff8e5f
--- /dev/null
+++ b/doc/rrdbotd.8
@@ -0,0 +1,154 @@
+.\"
+.\" 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 rrdbotd 8
+.Os rrdbot
+.Sh NAME
+.Nm rddbotd
+.Nd an SNMP poller which writes to an round robin database
+.Sh SYNOPSIS
+.Nm
+.Op Fl M
+.Op Fl c Ar confdir
+.Op Fl w Ar workdir
+.Op Fl m Ar mibdir
+.Op Fl d Ar debuglevel
+.Op Fl p Ar pidfile
+.Op Fl r Ar retries
+.Op Fl t Ar timeout
+.Nm
+.Fl V
+.Sh DESCRIPTION
+.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.
+.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
+configuration files are described in:
+.Xr rrdbot.conf 5
+.Sh OPTIONS
+The options are as follows.
+.Bl -tag -width Fl
+.It Fl c Ar confdir
+The directory in which configuration files are stored. See below for info
+on the various file locations.
+.It Fl d Ar debuglevel
+Don't detach from the console and run as a daemon. In addition the
+.Ar debuglevel
+argument specifies what level of error messages to display. 0 being
+the least, 4 the most.
+.It Fl m Ar mibdir
+The directory in which to look for MIB files. The default directory is
+usually sufficient.
+.It Fl M
+Display MIB parsing warnings.
+.It Fl p Ar pidfile
+Specifies a location for the a process id file to be written to. This file
+contains the process id of
+.Nm
+and can be used to stop the daemon.
+.It Fl r Ar retries
+The number of times to retry sending an SNMP packet. Defaults to 3 retries.
+.It Fl t Ar timeout
+The amount of time (in seconds) to wait for an SNMP response. Defaults to
+5 seconds.
+.It Fl V
+Prints the version of
+.Nm
+and the locations of the configuration files, RRD files etc.
+.It Fl w Ar workdir
+The default directory where to look for RRD files. See below for info on
+the various file locations.
+.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
+You can use the
+.Xr rrdbot-create 8
+tool to create the needed RRD files in the appropriate places.
+.Sh SEE ALSO
+.Xr rrdbot.conf 5 ,
+.Xr rrdbot-create 8 ,
+.Xr rrdbot-get 1 ,
+.Xr rrdtool 1
+.Sh AUTHOR
+.An Nate Nielsen Aq nielsen@memberwebs.com
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-04 21:59:57 +0000