.\" 
.\" 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.conf 5
.Os bsnmp-regex 
.Sh NAME
.Nm bsnmp-regex.conf
.Nd the configuration file for the
.Xr bsnmp-regex 8
module. 
.Sh DESCRIPTION
The
.Xr bsnmp-regex
SNMP module parses logs or other textual output and exposes the matched values 
as SNMP counters. The 
.Nm
config file contains definitions for the counters you want, and what text to 
match to those counters.
.Pp
Blank lines and lines starting with a '#' sign are ignored.
.Sh COUNTERS
.Pp
Two different kinds of counters are possible.
.Ar Stat
counters increment their value each time a match is made. 
.Ar Value 
counters contain the last matched value. 
.Pp
A counter line constists of a name, a colon and a delimited regular expression:
.Bd -literal -offset indent
name: /match.*/
.Ed
.Pp
The name is used as the 
.Ar regexDescr 
SNMP value.
.Pp
A 
.Ar stat 
counter looks like the example above, and simply increments the 
.Ar regexInteger
SNMP value each time a match is made.
.Pp
A value counter has a second part to it's regular expression, similar to 
a 'sed replace':
.Bd -literal -offset indent
name: /([0-9]+) degrees/\\1/
.Ed
.Pp
The backslash-numeral refers to the regular expression group. \\0 refers to 
the entire matched text. The resulting value is available in the 
.Ar regexString
SNMP value. If the result is parseable as an integer, it is also available
in the 
.Ar regexInteger
SNMP value.
.Sh OPTIONS
The file can contain options which change the behavior of the counters
below that point. An option line consists of a name, an equals 
sign, and the value:
.Bd -literal -offset indent
option = value
.Ed
.Pp
An option applies to all match lines below that point in the file. 
.Bl -tag -width Fl
.It Ar expires
This option is the amount of time (in seconds) after which to expire a counter
if no new values have come in. This is mostly useful for 
.Ar stat
counters.
.El
.Sh EXAMPLES
Given a maillog output, this would make a counter for the number of messages 
relayed:
.Bd -literal -offset indent
relayed: /relay.* status=sent/
.Ed 
This would set the counter to the last user that logged into the
system over the past hour:
.Bd -literal -offset indent
expires = 3600
lastuser: /sshd.* Accepted.* for ([^ ]+) from/\\1/
.Ed
.Sh SEE ALSO
.Xr bsnmp-regex 8
.Xr re_format 7
.Sh AUTHOR
.An Stef Walter Aq stef@memberwebs.com