.\" 
.\" Copyright (c) 2006, Stefan Walter
.\" 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
.\"  Stef Walter <stef@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.regex
.Ed
.Pp
The following SNMP MIBs are available for use (where X is the counter index):
.Bl -tag -width Fl
.It Ar regex.regexCount.0
The number of counters available.
.It Ar regex.regexEntry.regexIndex.X
The index of the counter.
.It Ar regex.regexEntry.regexDescr.X
The description of the counter.
.It Ar regex.regexEntry.regexLast.X
How long ago the counter was last updated.
.It Ar regex.regexEntry.regexInteger.X
The current value or counter as a integer.
.It Ar regex.regexEntry.regexString.X
The current value as a string.
.It Ar regex.regexEntry.regexCounter.X
The current counter value as a 64 bit integer.
.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 Stef Walter Aq stef@memberwebs.com