Cleanup and initial open source release

1 files changed, 145 insertions, 0 deletions

diff --git a/doc/bsnmp-regex.8 b/doc/bsnmp-regex.8
new file mode 100644
index 0000000..7acf116
--- /dev/null
+++ b/doc/bsnmp-regex.8
@@ -0,0 +1,145 @@
+.\" 
+.\" 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 April, 2006
+.Dt bsnmp-regex 8
+.Os bsnmp-regex 
+.Sh NAME
+.Nm bsnmp-regex
+.Nd an SNMP module which produces counters from logs or other text
+.Sh DESCRIPTION
+.Nm
+is a module for 
+.Xr bsnmpd 1
+which allows you to make SNMP counters from log files or other text. For example
+you could count the number of occurances of a certain string in a text file. You 
+can also match specific numbers or text to build SNMP values.
+.Pp
+.Nm 
+has a configuration file which contains regular expressions for the text you'd 
+like to match. See 
+.Xr bsnmp-regex.conf 5
+for details on this file.
+.Pp
+.Nm
+opens a UNIX domain socket which text is piped into. The text is matched line
+by line against the regular expressions in the configuration file and the 
+appropriate counter or value is updated. The 
+.Xr sockin 1
+utility is useful for piping text into this socket. 
+.Sh MIBS
+The counters will be available as a table under the following MIB:
+.Bd -literal -offset indent
+ .1.3.6.1.4.1.12325.1.203
+.Ed
+.Pp 
+Or if the appropriate MIB.txt files have been installed:
+.Bd -literal -offset indent
+ enterprises.fokus.begemot.regexData
+.Ed
+.Pp
+The following SNMP MIBs are available for use (where X is the counter index):
+.Bl -tag -width Fl
+.It Ar regexData.regexCount.0
+The number of counters available.
+.It Ar regexData.regexEntry.regexIndex.X
+The index of the counter.
+.It Ar regexData.regexEntry.regexDescr.X
+The description of the counter.
+.It Ar regexData.regexEntry.regexLast.X
+How long ago the counter was last updated.
+.It Ar regexData.regexEntry.regexInteger.X
+The current counter value as a integer.
+.It Ar regexData.regexEntry.regexString.X
+The current counter value as a string.
+.El
+.Sh OPTIONS
+To activate the 
+.Nm
+module you must load the module in 
+.Pa /etc/snmpd.config
+and configure the location for the UNIX socket and 
+.Xr bsnmp-regex.conf 5 
+file. See the examples section below. 
+.Bl -tag -width Fl
+.It Ar regexConfig
+The location of the 
+.Xr bsnmp-regex.conf 5
+file. This option must be specified.
+.It Ar regexSocket
+The location of the UNIX socket on which this module will listen for logs
+or text to match.
+.El
+.Sh EXAMPLES
+For a simple 
+.Nm
+configuration add the following to
+.Pa /etc/snmpd.config:
+.Bd -literal -offset indent
+begemotSnmpdModulePath."regex" = "/usr/local/lib/snmp_regex.so"
+%regex
+regexConfig = "/usr/local/etc/bsnmp-regex.conf"
+regexSocket = "/var/run/bsnmp-regex.sock"
+.Ed
+.Pp
+For details on what 
+.Pa /usr/local/etc/bsnmp-regex.conf 
+should contain, see the 
+.Xr bsnmp-regex.conf 5
+man page.
+.Pp
+To pipe logs or text to match into the socket use the
+.Xr sockin 1
+utility, run something like this:
+.Bd -literal -offset indent
+# sockin /var/run/bsnmp-regex.sock tail -f /var/log/maillog
+.Ed
+.Pp
+To have 
+.Xr syslogd 8
+send all logs for matching add a line like this to the
+.Pa /etc/syslog.conf
+file:
+.Bd -literal -offset indent
+*.*         | sockin /var/run/bsnmp-regex.sock
+.Ed
+.Sh SEE ALSO
+.Xr bsnmp-regex.conf 5 ,
+.Xr bsnmpd 1 ,
+.Xr sockin 1 ,
+.Xr syslog.conf 5
+.Sh AUTHOR
+.An Nate Nielsen Aq nielsen@memberwebs.com