NAME NetSNMP::bridge - SNMP bridge which maps static files into a MIB space. SYNOPSIS 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: * Runnig as an 'agentx' sub agent. 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). * Using the embedded perl agent. 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. PREPARATION 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 for the files. 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 * Populate a sample status file. 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. * Add more files if desired. Optionally you can add more files - however each should have a unique OID prefix which is different down to the shortest lenght. SUBAGENT 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. Setup * Activate AgentX Edit snmpd.conf to ensure that the line agentx master is uncommented. * Ensure the socket is accessible. 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 the sub agent 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 * Test Do an snmpwalk to fetch the above values: snmpwalk localhost 1.3.6.1.4.1.99999 Trouble shooting. Ccheck x/r of the unix agentx socket and higher directories. check log or run with -DALL -f flags. Other configuration options. Consult the snmpd.conf mange page on agentXPingInterval, agentXTimeout and agentXRetries. EMBEDDED 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. Setup * Configure snmp Add the following line to snmpd.conf perl @inputs=('/var/db/snmp'); do "../path/pass.pm"; aand start snmpd. * Test Do an snmpwalk to fetch the above values: snmpwalk localhost 1.3.6.1.4.1.99999 Trouble shooting. Check the log (run with -DALL -f flag). This script will only pick up (new) OID files at startup time. EXAMPLE 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]:

Maillog and apche hits

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]:

Apache processes

LegendI[maillog]: apache processes LegendO[maillog]: apache processes BUGS Please report bugs to the net-snmp developers forum or bug tracker. SEE ALSO The net-snmp manual pages, in particular snmpd.conf and the section on the pass-directive. AUTHOR Dirk-Willem van Gulik COPYRIGHT AND LICENSE 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.