NetSNMP::bridge - SNMP bridge which maps static files into a MIB space.
The idea is that utilities, crontabs or daemons regularly write some statistics into a flat text file. The values in this file are then bridged into the MIB space. E.g. if the file contains:
$ cat /var/db/snmp/1.3.6.1.4.1.9999
1.3.6.1.4.1.99999.1.0 counter 3012
then an SNMP get gives
$ snmpget -v2c -c public foo.site.com 1.3.6.1.4.1.99999.1.0
3012
$
or when a MIB is defined containing the entry:
tcpShutdowns OBJECT-TYPE
SYNTAX Counter
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"Number of TCP shutdowns seen by the foo daemon"
::= { enterprises 99999 1 }
....
the output/data would be like:
$ snmpwalk foo.site.com tcpShutdowns
tcpShutdowns: 3012
$
The fileformat used is the expected wire format of the 'pass' and 'pass-persistant' API of net-snmp; i.e. an OID, a type and a value on one line.
Note that there are two ways to use this bridge:
In this case the bridge will run stand alone, as its own process; register with the subagent (and attempt to re-register should the connection get lost) and then sit idle until there is a request to serve.
You can run as many subagents as required - provided that they do not intrude on each others OID spaces (i.e. serve the same OID).
In this model the bridge is part of the SNMP agent. This implies that you have one process less to worry about. But any faults or issues are not contained.
Which of those two is chosen depends on the situation - though when in doubt - start with the 'agentx' sub agent - as it is the most simplest situation to debug.
The first step is to create some sample files with the statistics or values which are to be exposed or monitored by SNMP. These are simple ascii test files with one value per line.
Create a directory; e.g.
/var/db/snmp
and populate this with a single file called:
/var/db/snmp/1.3.6.1.4.1.99999
Next add the following lines to this file:
1.3.6.1.4.1.99999.1.0 string foo
1.3.6.1.4.1.99999.2.0 gauge 1
1.3.6.1.4.1.99999.3.0 counter 12
See the documentation of 'pass' in the snmpd manpage for details about this format.
In above the 'OID' is contructed from a prefix; in this case '1.3.6.1.4.1.99999', the variable number, arbitrary choosen to be 1, 2 and 3, and a '.0' postfix.
The above prefix is just for testing purposes. Normally an organisation would request a private enterprise prefix with IANA; we've simply picked '999999' - which at the time of writing had not been issued. Check the URL:
http://www.iana.org/assignments/enterprise-numbers
to see if your organisation already has one.
The variable numbers can be freely picked - though by convention they typically are sequentially numbered. It is common to group variables which are logically together in subgroups by prefixing them with another 1, 2... E.g in below the byte r/w counts have been 'virtually' grouped:
# version of the daemon
1.3.6.1.4.1.99999.1.0 string Froobar/1.0
# bytes read/written by the froogle
1.3.6.1.4.1.99999.2.1.0 integer 32
1.3.6.1.4.1.99999.2.2.0 integer 19
# bytes read/written by the boogle
1.3.6.1.4.1.99999.3.1.0 integer 32
1.3.6.1.4.1.99999.3.2.0 integer 19
# memory footprint
1.3.6.1.4.1.99999.4.0 integer 32
Note that the '.0' postfix, while technically not mandatory, is silently assumed by a lot of SNMP management tools. For more details - consult any SNMP primer.
Optionally you can add more files - however each should have a unique OID prefix which is different down to the shortest lenght.
Use as a sub agent (stand alone) - i.e. the snmpd daemon waits for this daemon to connect to it; and this daemon will try to reconnect at regular intervals should it loose the connection.
Edit snmpd.conf to ensure that the line
agentx master
is uncommented.
Check that the user you will run this sub-agent can access the unix socket (default /var/agentx/master).
Or alternatively move/change the permissions within snmpd.conf by editing:
agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]
agentXSocket ...path
Run this perl script with the OID directory or a list of files:
./pass.pm /var/db/snmp
and check that it connexts to the master agent:
NET-SNMP version 5.3.1 AgentX subagent connected
Do an snmpwalk to fetch the above values:
snmpwalk localhost 1.3.6.1.4.1.99999
Ccheck x/r of the unix agentx socket and higher directories. check log or run with -DALL -f flags.
Consult the snmpd.conf mange page on agentXPingInterval, agentXTimeout and agentXRetries.
In this case the embedded perl interpreter of net-snmp is used. This has the advantage that there is one daemon less to worry about - but has the downsites that faults are not as isolated.
Add the following line to snmpd.conf
perl @inputs=('/var/db/snmp'); do "../path/pass.pm";
aand start snmpd.
Do an snmpwalk to fetch the above values:
snmpwalk localhost 1.3.6.1.4.1.99999
Check the log (run with -DALL -f flag).
This script will only pick up (new) OID files at startup time.
As a quick experiment - you could consider installing a small crontab along these lines -- which will let you monitor the number of hits from apache, the last hit of apache and the # of mails - along with the number of apache children running.
#!/bin/sh
# Gather various counts:
#
L=`wc -l /var/log/maillog`
M=`wc -l /var/log/apache2/access_log`
H=`tail -1 /var/log/apache2/access_log`
G=`ps ax | grep httpd | wc -l`
# Output counts into a statistics file for
# the SNMP bridge.
(
echo 1.3.6.1.4.1.8072.9999.1.0 counter $L
echo 1.3.6.1.4.1.8072.9999.2.0 counter $M
echo 1.3.6.1.4.1.8072.9999.3.0 gauge $G
echo 1.3.6.1.4.1.8072.9999.4.0 string $H
) > /var/db/snmp/$OID.new
# note - atomic move rather than copy.
#
mv /var/db/snmp/$OID.new /var/db/snmp/$OID
exit 0
The following 'mrtg' lines would graph above counter and gauge:
Target[maillog]: 1.3.6.1.4.1.8072.9999.1&1.3.6.1.4.1.8072.9999.2.0:public@localhost
Title[maillog]: Maillog and hits
Options[maillog]: growright, nopercent
PageTop[maillog]: <h2>Maillog and apche hits </h2>
LegendI[maillog]: maillog
LegendO[maillog]: apache hits
Target[maillog]: 1.3.6.1.4.1.8072.9999.3&1.3.6.1.4.1.8072.9999.3.0:public@localhost
Title[maillog]: Number of Apache processes
Options[maillog]: growright, nopercent, gauge
PageTop[maillog]: <h2>Apache processes</h2>
LegendI[maillog]: apache processes
LegendO[maillog]: apache processes
Please report bugs to the net-snmp developers forum or bug tracker.
The net-snmp manual pages, in particular snmpd.conf and the section on the pass-directive.
Dirk-Willem van Gulik <dirkx[at]webweaving[dot]org>
Copyright 2004 by Dirk-Willem van Gulik
This library is open source software; you can redistribute it and/or modify it under the same terms as net-snmp itself, the Apache Software License or any version of the BSD license.