summaryrefslogtreecommitdiff
path: root/doc/bsnmp-regex.8
diff options
context:
space:
mode:
authorStef Walter <stef@memberwebs.com>2006-04-05 20:51:48 +0000
committerStef Walter <stef@memberwebs.com>2006-04-05 20:51:48 +0000
commiteac1602858639b0653a8e15ff191ed9b9f64c440 (patch)
tree90349495c80410153c88cd73d4a0beef6b41997c /doc/bsnmp-regex.8
parent0be20dc6ea13149dc2083ac2add78441be8733f3 (diff)
Cleanup and initial open source release
Diffstat (limited to 'doc/bsnmp-regex.8')
-rw-r--r--doc/bsnmp-regex.8145
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