From 85aadabd85dd077ae396724b264f9c2bfa5357b0 Mon Sep 17 00:00:00 2001
From: Stef Walter <stef@memberwebs.com>
Date: Mon, 7 Aug 2006 16:59:41 +0000
Subject: Added manual pages

---
 Makefile.am         |   2 +-
 doc/Makefile.am     |  12 +++
 doc/man2html.pl     | 230 +++++++++++++++++++++++++++++++++++++++++++++
 doc/rrdbot-create.8 | 147 +++++++++++++++++++++++++++++
 doc/rrdbot-get.1    |  84 +++++++++++++++++
 doc/rrdbot.conf.5   | 264 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/rrdbotd.8       | 154 ++++++++++++++++++++++++++++++
 7 files changed, 892 insertions(+), 1 deletion(-)
 create mode 100644 doc/Makefile.am
 create mode 100755 doc/man2html.pl
 create mode 100644 doc/rrdbot-create.8
 create mode 100644 doc/rrdbot-get.1
 create mode 100644 doc/rrdbot.conf.5
 create mode 100644 doc/rrdbotd.8

diff --git a/Makefile.am b/Makefile.am
index 183974b..c3ce3c4 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,6 +1,6 @@
 
 EXTRA_DIST = common mib acsite.m4
-SUBDIRS = bsnmp daemon tools mibs
+SUBDIRS = bsnmp daemon tools mibs doc
 
 # Clean up any EXTRA_DIST we're distributing
 dist-hook:
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
-- 
cgit v1.2.3