snmptt_1.4/0000775000076400007640000000000012236567723011460 5ustar alexalexsnmptt_1.4/snmptthandler0000775000000000000000000001453012236567454014317 0ustar rootroot#!/usr/bin/perl # # SNMPTTHANDLER v1.4 # # Copyright 2002-2013 Alex Burger # alex_b@users.sourceforge.net # 8/26/2002 # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################## # # http://www.sourceforge.net/projects/snmptt # # This script is a snmp trap handler for use with the NET-SNMP / UCD-SNMP # snmptrapd program and SNMPTT. # # The script is called by defining a 'traphandle' in snmptrapd.conf. # For example: # # traphandle default /sbin/snmptthandler # # SNMPTRAPD feeds details about the trap to the launched program's standard # input in the following format (see snmptrapd.conf man page for a complete # descriptipon) # # HOSTNAME: The name of the host in question that sent the trap # IPADDRESS: The IP address of the host that sent the trap # VARBINDS: A list of variable bindings that describe the trap and # the variables enclosed in it. # # SNMPTTHANDLER dumps the received traps into a directory to be processed # by the SNMPTT daemon. # ############################################################################## use strict; # Process command line arguments use Getopt::Long; use Time::HiRes qw(gettimeofday); my $version = ''; my $debug = ''; my $help = ''; my $ini = ''; my $debugfile = ''; GetOptions ('version' => \$version, 'debug:i' => \$debug, 'debugfile=s' => \$debugfile, 'help' => \$help, 'ini=s' => \$ini); if ($version) { &showversion; exit(0); } if ($help) { my $USAGE = qq/Usage: snmptthandler [] Options: --debug=n Set debug level (1 or 2) --debugfile=filename Set debug output file --help Display this message --ini=filename Set configuration file to load --version Display author and version information /; &showversion; print $USAGE; exit(0); } my $DEBUGGING; my $DEBUGGING_FILE; my $debugcmdline; my $debugfilecmdline; if ($debug >= 1) { $DEBUGGING = 1; $debugcmdline = 1 } if ($debugfile ne '') { $DEBUGGING_FILE = $debugfile; # commandline overpowers snmptt script $debugfilecmdline = 1; } ############################################################################## # # Load config file start # # For Linux / Unix, try /etc/snmp/snmptt.ini first, /etc/snmptt.ini second. # # For Windows, try %SystemRoot%\snmptt.ini only. # my $configfile; if ($ini ne '') { $configfile = $ini; } else { if ($^O ne "MSWin32") { $configfile = '/etc/snmp/snmptt.ini'; if( open( CONFIG, '/etc/snmp/snmptt.ini' ) ) { $configfile = '/etc/snmp/snmptt.ini'; close CONFIG; } elsif ( open( CONFIG, '/etc/snmptt.ini' ) ) { $configfile = '/etc/snmptt.ini'; close CONFIG; } } else { $configfile = $ENV{'SystemRoot'}."\\snmptt.ini"; } } my $spool_directory; &loadsnmpttini; ############################################################################## # Pull in passed SNMP info from snmptrapd via STDIN and place in the array @tempvar # Create file in spool directory based on current time my ($s, $usec) = gettimeofday; # Pad the numbers with 0's to make sure they are all the same length. Sometimes the # usec is shorter than 6. my $s_pad = sprintf("%09d",$s); my $usec_pad = sprintf("%06d",$usec); if ($DEBUGGING >= 1) { if ($DEBUGGING_FILE ne '') { open DEBUGFILE, ">>$DEBUGGING_FILE" or warn "Could not open debug output file ($!)"; select DEBUGFILE; # Change default output to debug file } # Print out time print "SNMPTTHANDLER started: ",scalar(localtime),"\n\n"; print "s = $s, usec = $usec\n"; print "s_pad = $s_pad, usec_pad = $usec_pad\n\n"; print "Data received:\n\n"; } my $spoolfile = $spool_directory.'#snmptt-trap-'.$s_pad.$usec_pad; unless (open SPOOL, ">$spoolfile") { if ($DEBUGGING >= 1) { print "Could not write to file file $spoolfile! Trap will be lost!\n"; } die "Could not write to file $spoolfile! Trap will be lost!\n"; } print SPOOL time()."\n"; while (defined(my $line = <>)) { print SPOOL $line; if ($DEBUGGING >= 1) { # Print out item passed from snmptrapd print $line."\n"; } } ############################################################################## sub showversion { printf "\nSNMPTTHANDLER v1.4\n"; printf "(c) 2002-2013 Alex Burger\n\n"; } ############################################################################## sub loadsnmpttini { ############################################################################## # # Load config file start # use Config::IniFiles; my $cfg; # ############################################################################## if( open( CONFIG, $configfile ) ) { close CONFIG; $cfg = new Config::IniFiles( -file => $configfile); } else { if ($DEBUGGING >= 1) { print "Config file ($configfile) could not be loaded\n"; } warn "Config file ($configfile) could not be loaded\n"; exit(1); } if (! $cfg) { if ($DEBUGGING >= 1) { print "Error in config file - please check the syntax in the config file\n"; } exit(1); } # DaemonMode $spool_directory = $cfg->val('DaemonMode', 'spool_directory'); # Debugging if ($debugcmdline == 0) { $DEBUGGING = $cfg->val('Debugging', 'DEBUGGING'); } if ($debugfilecmdline == 0) { $DEBUGGING_FILE = $cfg->val('Debugging', 'DEBUGGING_FILE_HANDLER'); } $cfg->Delete; # # Defaults Start # if (! defined ($spool_directory)) { $spool_directory = ''} ; if (! defined ($DEBUGGING)) { $DEBUGGING = 0} ; if (! defined ($DEBUGGING_FILE)) { $DEBUGGING_FILE = ''} ; # # Defaults End # # print "Config file loaded\n"; # # Load config file end # ############################################################################## } snmptt_1.4/snmptt-eventlog.mc0000664000000000000000000000505307627707261015175 0ustar rootrootMessageIdTypedef=DWORD LanguageNames=(English=0x409:MSG00409) MessageId=0 Severity=Success Facility=Application Language=English %1 . MessageId=1 Severity=Success Facility=Application Language=English %1 . MessageId=2 Severity=Success Facility=Application Language=English %1 . MessageId=3 Severity=Success Facility=Application Language=English %1 . MessageId=4 Severity=Success Facility=Application Language=English %1 . MessageId=5 Severity=Success Facility=Application Language=English %1 . MessageId=6 Severity=Success Facility=Application Language=English %1 . MessageId=7 Severity=Success Facility=Application Language=English %1 . MessageId=8 Severity=Success Facility=Application Language=English %1 . MessageId=9 Severity=Success Facility=Application Language=English %1 . MessageId=10 Severity=Success Facility=Application Language=English %1 . MessageId=11 Severity=Success Facility=Application Language=English %1 . MessageId=12 Severity=Success Facility=Application Language=English %1 . MessageId=13 Severity=Success Facility=Application Language=English %1 . MessageId=14 Severity=Success Facility=Application Language=English %1 . MessageId=15 Severity=Success Facility=Application Language=English %1 . MessageId=16 Severity=Success Facility=Application Language=English %1 . MessageId=17 Severity=Success Facility=Application Language=English %1 . MessageId=18 Severity=Success Facility=Application Language=English %1 . MessageId=19 Severity=Success Facility=Application Language=English %1 . MessageId=20 Severity=Success Facility=Application Language=English %1 . MessageId=21 Severity=Success Facility=Application Language=English %1 . MessageId=22 Severity=Success Facility=Application Language=English %1 . MessageId=23 Severity=Success Facility=Application Language=English %1 . MessageId=24 Severity=Success Facility=Application Language=English %1 . MessageId=25 Severity=Success Facility=Application Language=English %1 . MessageId=26 Severity=Success Facility=Application Language=English %1 . MessageId=27 Severity=Success Facility=Application Language=English %1 . MessageId=28 Severity=Success Facility=Application Language=English %1 . MessageId=29 Severity=Success Facility=Application Language=English %1 . MessageId=30 Severity=Success Facility=Application Language=English %1 . snmptt_1.4/snmptt.ini-nt0000664000000000000000000006230012236567454014151 0ustar rootroot# # SNMPTT v1.4 Configuration File # # Windows NT # [General] # Name of this system for $H variable. If blank, system name will be the computer's # hostname via Sys::Hostname. snmptt_system_name = # Set to either 'standalone' or 'daemon' # standalone: snmptt called from snmptrapd.conf # daemon: snmptrapd.conf calls snmptthandler # Ignored by Windows. See documentation mode = standalone # Set to 1 to allow multiple trap definitions to be executed for the same trap. # Set to 0 to have it stop after the first match. # This option should normally be set to 1. See the section 'SNMPTT.CONF Configuration # file Notes' in the SNMPTT documentation for more information. # Note: Wildcard matches are only matched if there are NO exact matches. This takes # into consideration the NODES list. Therefore, if there is a matching trap, but # the NODES list prevents it from being considered a match, the wildcard entry will # only be used if there are no other exact matches. multiple_event = 1 # SNMPTRAPD passes the IP address of device sending the trap, and the IP address of the # actual SNMP agent. These addresses could differ if the trap was sent on behalf of another # device (relay, proxy etc). # If DNS is enabled, the agent IP address is converted to a host name using a DNS lookup # (which includes the local hosts file, depending on how the OS is configured). This name # will be used for: NODES entry matches, hostname field in logged traps (file / database), # and the $A variable. Host names on the NODES line will be resolved and the IP address # will then be used for comparing. # Set to 0 to disable DNS resolution # Set to 1 to enable DNS resolution dns_enable = 0 # Set to 0 to enable the use of FQDN (Fully Qualified Domain Names). If a host name is # passed to SNMPTT that contains a domain name, it will not be altered in any way by # SNMPTT. This also affects translate_value_hostnames. # Set to 1 to have SNMPTT strip the domain name from the host name passed to it. For # example, server01.domain.com would be changed to server01 # Set to 2 to have SNMPTT strip the domain name from the host name passed to it # based on the list of domains in strip_domain_list strip_domain = 0 # List of domain names that should be stripped when strip_domain is set to 2. # List can contain one or more domains. For example, if the FQDN of a host is # server01.city.domain.com and the list contains domain.com, the 'host' will be # set as server01.city. strip_domain_list = <p {margin:0px;} */ /* #Content>p+p {text-indent:30px;} */ a { color:#09c; font-size:1em; text-decoration:none; font-weight:600; font-family:verdana, arial, helvetica, sans-serif; } a:link {color:#09c;} a:visited {color:#07a;} a:hover {background-color:#eee;} #skip { display:none; } #Header { font-family: verdana,arial,serif; font-size: 2.1em; font-weight: bold; margin:50px 0px 10px 0px; padding:10px 0px 10px 20px; /* For IE5/Win's benefit height = [correct height] + [top padding] + [top and bottom border widths] */ height:33px; /* 14px + 17px + 2px = 33px */ border-style:solid; border-color:black; border-width:1px 0px; /* top and bottom borders: 1px; left and right borders: 0px */ line-height:11px; background-color:#eee; /* Ugly brilliant hack removed - messed up Konqueror. Just set height anyways otherwise ie6 messed up */ height:14px; /* the correct height */ } /* I've heard this called the "be nice to Opera 5" rule. Basically, it feeds correct length values to user agents that exhibit the parsing error exploited above yet get the CSS box model right and understand the CSS2 parent-child selector. ALWAYS include a "be nice to Opera 5" rule every time you use the Tantek Celik hack (above). */ body>#Header {height:14px;} #Content { margin:0px 50px 0px 200px; padding:10px; } #LeftSide { position:absolute; top:100px; left:20px; width:172px; line-height:17px; /* Here is the ugly brilliant hack that protects IE5/Win from its own stupidity. Thanks to Tantek Celik for the hack and to Eric Costello for publicizing it. IE5/Win incorrectly parses the "\"}"" value, prematurely closing the style declaration. The incorrect IE5/Win value is above, while the correct value is below. See http://glish.com/css/hacks.asp for details. */ voice-family: "\"}\""; voice-family:inherit; width:150px; } /* Again, "be nice to Opera 5". */ body>#LeftSide {width:150px;} #Menu { padding:10px; background-color:#eee; border:1px dashed #999; } /* Again, "be nice to Opera 5". */ body>#Menu {width:150px;} #ModificationDate { margin:0px 50px 20px 200px; } .Copyright { font-family: verdana,arial,serif; font-size: 1em;} .Email { font-family: verdana,arial,serif; font-size: 0.85em;} .NewsItem { font-family: verdana,arial,serif; font-size: 1em; } .NewsItemUrgent { font-family: verdana,arial,serif; font-size: 1em; background-color: #ccff99;} .NewsItemDate { font-family: verdana,arial,serif; font-size: 1em; font-weight: bold; } .SectionTitle { font-family: verdana,arial,serif; font-size: 1.2em; font-weight: bold; text-decoration: underline;} .SectionBody { font-family: verdana,arial,serif; font-size: 1em; } .ModificationDate { font-family: verdana,arial,serif; font-size: 0.9em; } snmptt_1.4/docs/faqs.html0000664000000000000000000007575712236567454014300 0ustar rootroot SNMP Trap Translator v1.4

SNMPTT FAQ / Troubleshooting

(www.snmptt.org)
This file was last updated on:  July 18th, 2009

Table of Contents

Installation

General


Q:  What version of Net-SNMP should I run?

A:  If you have no plans on using the Net-SNMP Perl module (see the next question), then any recent version of Net-SNMP should be sufficient with the exception of Net-SNMP 5.1.  Net-SNMP 5.1.1 and higher can be used.  If you plan on using UCD-SNMP 4.2.3 (provided by Compaq for RedHat 7.2), then you must at least use a newer version of snmptrapd.

If you plan on enabling the Net-SNMP Perl module, Net-SNMP v5.1.1 or higher is recommended.  This will allow you to use all the features of snmptt.  Net-SNMP 5.0.8 and 5.0.9  can also be patched with patch 722075 to provide similar functionality.  The patch is available from the Net-SNMP patch page.

The standard way to apply the patch is to follow these steps:
  1. Download a fresh copy of Net-SNMP 5.0.9 or 5.0.8
  2. Uncompress the archive (tar xvf net-snmp-5.0.9.tar.gz)
  3. cd net-snmp-5.0.x
  4. patch -p0 < /path/to/patch.net-snmp-722075
  5. Compile Net-SNMP as per Net-SNMP documentation

If you run freebsd, you can simply copy the patch file into /usr/ports/net/net-snmp/files and rename it to patch-snmp-72205.  When you rebuild Net-SNMP, the patch will be included.


Q: Do I need the UCD-SNMP / Net-SNMP Perl module?

A:  SNMPTT does not REQUIRE the Perl module, but it is recommended.  By enabling the Perl module, you will get the following benefits:
Unless Net-SNMP 5.1.1 or higher or 5.0.8 / 5.0.9 with patch 72205 is used, some Perl features may not work correctly.  The use of Net-SNMP 5.1.1 or higher or 5.0.8 / 5.0.9 with patch 72205 is highly recommended.

Note1:  In addition to the regular Perl modules, Net-SNMP allows Perl to be embedded into the SNMP agent (snmpd) and trap receiver (snmptrapd) by specifying --enable-embedded-perl during compilation. This is only required by SNMPTT if you plan on using the embedded trap handler (snmptthandler-embedded).

Note2:  Do not confuse the CPAN module Net::SNMP (use Net::SNMP;) with the Net-SNMP Perl module (use SNMP;).  They are two completely unrelated programs.  Net::SNMP is a stand-alone SNMP module for Perl, while the Net-SNMP Perl module is a Perl extension of the Net-SNMP software and is included with Net-SNMP. Distributions such as RedHat provide the Perl modules in a separate RPM package called 'net-snmp-perl'.


Q:  I want to enable the Perl support for  under Linux, but I installed Net-SNMP / UCD-SNMP using RPMs.  What is the easiest way to install the module without recompiling everything?

A:  There are two Perl components for Net-SNMP:

1) The Perl modules which allow you to create stand-alone Perl programs that use the 'SNMP' module (use SNMP;)

2) Embedded Perl for snmpd and snmptrapd which allow you to write Perl programs that are loaded and run from inside of snmpd and snmptrapd.

The Perl modules (1) are optional but recommended.  See Do I need the UCD-SNMP / Net-SNMP Perl module? for the benefits of enabling the Perl modules.

Embedded Perl (2) is only needed if you want to use the embedded trap handler (snmptthandler-embedded).See xxxxx for the benefits of using the embedded handler.

For the Perl modules (1), most Linux distributions provide RPMs.  For RedHat, install the net-snmp-perl RPM package using yum.

If you compiled Net-SNMP from source, then the Perl module should be enabled by default.  Typing the following is an easy test to see if the Perl module has been installed:

perl

use SNMP;

If you get an error message starting with 'Can't locate SNMP.pm in @INC....' then the Perl module has not been installed.  Press control-C to exit Perl if there was no error.

For embedded Perl support (2), you may have to compile Net-SNMP yourself using the '--enable-embedded-perl' configuration option.  To test to see if you already have embedded Perl enabled:

     Type snmptrapd -H 2>&1 | grep perl.  It should give perl   PERLCODE if embedded Perl is enabled.  

     If it's not available, you need to compile and install Net-SNMP using the --enable-embedded-perl configure option.  Use the net-snmp-users mail list for assistance.

If you are using UCD-SNMP, you should not have to re-compile the entire package.  Try the following:

  1. Download the source RPM that matches the binary RPM you downloaded.  For example: ucd-snmp-4.2.3-1.src.rpm
  2. Install the RPM
  3. Locate the installed source code.  For Mandrake, it should be in /usr/src/RPM/SOURCES
  4. Go into the sub directory perl/SNMP
  5. Follow the instructions in the README file

Note:  If you have installed Net-SNMP 5.0.9 or 5.0.8 using RPM packages, and want to apply patch 722075, you will need to re-compile the entire package and re-install.  Patch 722075 makes modifications to both the Perl source files, and the main snmp libraries so the above steps will not work.


Q:  I want to use Net-SNMP under Windows.   What should I do?


A:  You have at least three options:

  1. Download the Net-SNMP 5.1.2+ binary from the Net-SNMP home page and install.
  2. Download the Net-SNMP 5.1.2+ source and compile using MSVC++, MinGW or Cygwin as described in the Net-SNMP README.WIN32 file.  This should create a working snmptrapd.  See the question: How to I enable the Perl support for UCD-SNMP / Net-SNMP under Windows? Note: Net-SNMP 5.1.2 or higher is recommended if compiling under Windows as it contains the latest Windows specific compiling improvements.


Q:  How to I enable the Perl support for UCD-SNMP / Net-SNMP under Windows?

A:  There are two Perl components for Net-SNMP:

1) The Perl modules which allow you to create stand-alone Perl programs that use the 'SNMP' module (use SNMP;)

2) Embedded Perl for snmpd and snmptrapd which allow you to write Perl programs that are loaded and run from inside of snmpd and snmptrapd.

The Perl modules (1) are optional but recommended.  See Do I need the UCD-SNMP / Net-SNMP Perl module? for the benefits of enabling the Perl modules.

As of July 2009, embedded Perl (2) is not currently supported under Windows.

Native Windows:

Install ActiveState ActivePerl and then the ActivePerl .ppm module included in the Net-SNMP binary available from the Net-SNMP web site.

If you compiled your own version of Net-SNMP, see the perl/README document for instructions on compiling the Perl modules.

Cygwin:

Download the Net-SNMP 5.1.2+ source and compile using Cygwin as described in the Net-SNMP README.WIN32 file.

Compile the Perl modules as described in the perl\SNMP\README file. 

The program snmptt-net-snmp-test can be used to perform various translations to test the functionality of the installed UCD-SNMP / Net-SNMP Perl module.  The value of best_guess can be specified on the command line to determine how translations should occur.  If you are using 5.0.8+ with patch 722075 or 5.1.1+, use:  snmptt-net-snmp-test --best_guess=2.

 Q:  Which trap handler should I use?  snmptthandler or snmptthandler-embedded?

A:  The standard handler is fine for most installations.  The embedded handler was introduced in snmptt 1.3 and is recommended if there is a high volume of traps being received.

Standard Handler:

The standard handler is a small Perl program that is called each time a trap is received by snmptrapd when using daemon mode.  The limitations of this handler are:

The benefits of using this handler are:

Embedded Handler:

The embedded handler is a small Perl program that is loaded directly into snmptrapd when snmptrapd is started.  The limitations of this handler are:
The benefits of using this handler are:

Q: Are there any sample files to get me started?

A:  Yes, the examples folder contains a sample snmptt.conf file, and a sample trap file for testing.
  1. Install SNMPTT as described in this document
  2. Copy the snmptt.conf.generic file to the location specified in the snmptt.ini file (probably /etc/snmp/ or c:\snmp)
  3. Add snmptt.conf.generic to the snmptt_conf_files section of snmptt.ini.
  4. For standalong mode, test SNMPTT by typing:  snmptt < sample-trap.generic
    For daemon mode, test SNMPTT by copying sample-trap.generic.daemon to the spool folder
  5. Check the logs files etc for a sample linkDown trap


Q:  Why doesn't the snmptt-init.d script work with Debian?

The snmptt-init.d script provided with SNMPTT was written for Mandrake and RedHat.  To make the script work with Debian without requiring any re-writing of the script, copy /etc/init.d/skeleton to /etc/init.d/functions.

Q:  I have enabled net_snmp_perl_enable but the variable names are not being translated into text using $vn, $-n, $+n, $-* or $+*.  How do I troubleshoot it?
Q:  I have enabled translate_integers but the integer values are not being translated into text.   How do I troubleshoot it?

A:  You must have the UCD-SNMP / Net-SNMP Perl module installed and working, and must ensure UCD-SNMP / Net-SNMP is configured correctly with all the required MIBS.

For starters, make sure the SNMP module is working.  Type:

perl
use SNMP;
If you get an error after typing 'use SNMP', then the module is not installed correctly.  Re-install the module and make sure you execute the tests while building.

If the MIB files are present, but translations do not occur, ensure UCD-SNMP / Net-SNMP is correctly configured to process all the required mibs.  This is configured in the snmp.conf file.  Alternatively, you can try setting the mibs_enviroment variable in snmptt.ini to ALL (no quotes) to force all MIBS to be initialized at SNMPTT startup.

If everything appears to be fine, try translating the variable name by hand by using snmptranslate.  Get the variable name OID from the snmptt.debug file from the second Value 0+ section, and type:

snmptranslate -Td oid
This should return the OBJECT-TYPE for the variable if it exists in a MIB file

If you are using UCD-SNMP v4.2.3, then the variables will not translate properly because SNMPTRAPD does not pass them correctly to SNMPTT.  Upgrade to a newer version of snmptrapd.  


Q:  SNMPTT is not working!  How do I troubleshoot it?

A:  Start by enabling enable_unknown_trap_log in the snmptt.ini file.  Look inside this file to see if the traps are being passed correctly to SNMPTT but not being handled correctly.  Next, enable debug mode of 2 and specify a debug text file to log to in the snmptt.ini file.  After a trap is received, take a look at the file to try to determine what is going wrong.  Disable both logs when you are finished.

To make troubleshooting a particular trap easier when working in daemon mode, try the following.  This will prevent you have having to continuously generate the trap on the host.

  1. Shut down SNMPTT
  2. Generate the trap
  3. Copy the resulting # file from the spool directory (/var/spool/snmptt) to the /tmp directory as /tmp/test-trap
  4. Edit the file, removing the first line (which is a large number that contains the date / time)
  5. Run SNMPTT in standalone method using: snmptt < test-trap
  6. Troubleshoot by using the log files etc


Q:  I have configured SNMPTT correctly with an snmptt.ini file, snmptt.conf file(s) etc and it still does not process traps.  Everything appears in the snmpttunknowntrap.log file.  What did I do wrong?

A:  You probably didn't start snmptrapd correctly.  Make sure it is started using:

snmptrapd -On
If it is not started with -On, then it will not pass traps using numeric OIDs and SNMPTT will not process them.

As an alternative, you can edit your snmp.conf file to include the line: printNumericOids 1.  This setting will take effect no matter what is used on the command line.

Note:  If the UCD-SNMP / Net-SNMP Perl module is installed and enabled, then SNMPTT should be able to handle traps passed using symbolic form.  The Perl module (used by SNMPTT) in Net-SNMP 5.0.8 and previous versions should be able to handle single symbolic names (eg: coldTrap).  UCD-SNMP may not properly convert symbolic names to numeric OIDs which could result in traps not being matched.  A patch is available from the Net-SNMP web site for 5.0.8+ to allow it to handle other symbolic names such as module::symbolic name (eg: SNMPv2-MIB::coldTrap) etc.  The patch is available from the contrib folder, or it can be downloaded from the Net-SNMP patch page.  Net-SNMP 5.1.1 and higher contain this patch.


Q:  I have disabled syslog support in SNMPTT, but my syslog (or NT Event Log) is still filling up with trap messages.  How do I disable them?
Q:  I am using syslog (or NT Event Log) to log trap messages, but there are two log entries for each trap received.  How do I prevent it?

A:  What you are seeing are snmptrapd trap messages, not SNMPTT messages.  SNMPTT trap messages start with 'snmptt[pid]:' while snmptrapd messages start with 'snmptrapd[pid]:'.  If you do not start snmptrapd with either the -P or -o (lowercase o) switches, syslog support will be forced on.  Snmptrapd should be started using 'snmptrapd -On' and this results in syslog being forced on.  The reason for this is the original design of snmptrapd assumed that if you are not going to display messages on the screen or log to a file, then you must want syslog output.

A workaround is to have snmptrapd log all messages to /dev/null, or to a text file that can be regularily purged if needed.  To log to a text file, start snmptrapd using:

snmptrapd -On -o /var/log/snmptrapd.log
This will cause ALL snmptrapd messages to be logged to the file which means all snmptrapd 'system' messages such as startup and shutdown will not be logged to syslog.

A patch for Net-SNMP 5.0.7 is available that adds a new switch (-t) to prevent TRAP messages from being logged to syslog, but allowing system messages to continue to be logged.  The patch is available from the Net-SNMP patch section.  This patch is available in Net-SNMP 5.1.1 and higher.  With this patch, snmptrapd should be started using:

snmptrapd -On -t


Q:  I set translate_oids or translate_trap_oid, but the trap is being logged in numerical form.  Why?
Q:  I set translate_oids or translate_trap_oid to 1 or 3 in snmptt.ini, but the trap is not being logged with a long symbolic name.  Why?

A:  The current version of Net-SNMP (5.0.9 at the time of this writing) and everything before it does not support including the module name (eg: IF-MIB::) when translating an OID and most of the 5.0.x versions do not properly tranlsate numeric OIDs to long symbolic names.  A patch is available for 5.0.8+ that will appear in later releases of Net-SNMP (5.1.1+).  The patch is available from the contrib folder, or it can be downloaded from the Net-SNMP patch page.

The program snmptt-net-snmp-test can be used to perform various translations to test the functionality of the installed UCD-SNMP / NE-SNMP Perl module.  The value of best_guess can be specified on the command line to determine how translations should occur.

Q:  I converted a MIB using snmpttconvertmib but the OIDs are appearing as text instead of being numerical.  Why?

For example:
EVENT linkUp .iso.org.dod.internet.snmpV2.snmpModules.snmpMIB.snmpMIBObjects.snmpTraps.linkUp "Status Events" Normal

instead of

EVENT linkUp .1.3.6.1.6.3.1.1.5.4 "Status Events" Normal


A:  Snmpttconvertmib uses the snmptranslate command to convert MIB files.  With Net-SNMP v5.0.2 and newer, setting the -On switch on the snmptranslate command causes the output to be in numerical format, which is what is needed for snmpttconvertmib.

With Net-SNMP v5.0.1 and all versions of UCD-SNMP, setting the -On switch will TOGGLE the setting of using numerical output.  With Net-SNMP v5.0.2 and newer, setting the -On switch will FORCE the output to be numerical.

Snmpttconvermib will use the-On switch for snmptranslate only if it detects anything but UCD-SNMP or Net-SNMP v5.0.1.

If you are using UCD-SNMP, or Net-SNMP v5.0.1, the best option is to modify your snmp.conf file (for UCD-SNMP / Net-SNMP), and add or modify the line:

printNumericOids 1
This will cause all applications to output in numerical format including snmptranslate.  Note: This will affect other UCD-SNMP / Net-SNMP programs you are using, if any.
 
Q:  Does SNMPTT use DNS?

Only if it is enabled.  See the Name Resolution / DNS section.


Q:  Is there a front-end alarm browser available for SNMPTT?

A:  Take a look at SNMPTT-GUI.  SNMPTT-GUI aims to provide a web based frontend for SNMPTT.  The GUI is made up of server side perl cgi scripts with client side javascripts which interfaces to a SQL database using DBI::ODBC.

SNMPTT-GUI questions should be directed to the project admins on the SNMPTT-GUI Sourceforge page.
 

Q:  When I convert a MIB file using snmpttconvertmib I get 'Bad operator (_) errors.

A:  You need to enable support for underlines / underscores in MIB files.  See the snmp.conf man page.  Support can be enabled by adding this line to your main snmp.conf file: 

mibAllowUnderline 1


Q:  Double quotation marks (") are being logged with a \ in front of them.  How can this be disabled?

A:  Set remove_backslash_from_quotes = 1 in the snmptt.ini to have the \ removed from double quotes (").


Q:  Each trap received is being logged multiple times. Why?

A:  There are a few possible reasons for this.


 
 
 
 
 
 

snmptt_1.4/docs/snmptt.html0000664000000000000000000057300712236567454014662 0ustar rootroot SNMP Trap Translator

SNMP Trap Translator v1.4

(SNMPTT)
This file was last updated on: November 6th, 2013

License

SNMPTT

What is it?
Downloading
Requirements
What's New
Upgrading
Installation
   Overview
   Unix
Standard handler
Embedded handler
   Windows
   Securing SNMPTT
Configuration Options - snmptt.ini
Logging
   Standard
   Unknown Traps
   Syslog
   EventLog
   Database
     MySQL
     PostgreSQL
     ODBC
     Windows ODBC
Executing an external program
Modes of Operation
Command line arguments
SNMPTT.CONF Configuration file format
   EVENT
   FORMAT
      Variable-substitutions
   EXEC
   PREEXEC
   NODES
   MATCH
   REGEX
   SDESC
   EDESC
SNMPTT.CONF Configuration file Notes
Name resolution / DNS
Sample1 SNMPTT.CONF file
Sample2 SNMPTT.CONF file
Notes
Limitations
Feedback & Bugs
Integration with other software
   Nagios / Netsaint
   Simple Event Correlator (SEC)
   Windows Event Log forwarding
   Hobbit

License

Copyright 2002-2013 Alex Burger
alex_b@users.sourceforge.net
4/3/2002

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 

What is it?

SNMPTT (SNMP Trap Translator) is an SNMP trap handler written in Perl for use with the Net-SNMP / UCD-SNMP snmptrapd program (www.net-snmp.org). SNMPTT supports Linux, Unix and Windows.

Many network devices including but not limited to network switches, routers, remote access servers, UPSs, printers and operating systems such as Unix and Windows NT have the ability to send notifications to an SNMP manager running on a network management station. The notifications can be either SNMP Traps, or SNMP Inform messages.

The notification can contain a wide array of information such as port failures, link failures, access violations, power outages, paper jams, hard drive failures etc. The MIB (Management Information Base) available from the vendor determines the notifications supported by each device.

The MIB file contains TRAP-TYPE (SMIv1) or NOTIFICATION-TYPE (SMIv2) definitions, which define the variables that are passed to the management station when a particular event occurs.

The Net-SNMP program snmptrapd is an application that receives and logs SNMP trap and inform messages via TCP/IP. Following is a sample syslog entry for a Compaq cpqDa3LogDrvStatusChange trap that notifies that the drive array is rebuilding:

Feb 12 13:37:10 server11 snmptrapd[25409]: 192.168.110.192: Enterprise Specific Trap (3008) Uptime: 306 days, 23:13:24.29, .1.3.6.1.2.1.1.5.0 = SERVER08, .1.3.6.1.4.1.232.11.2.11.1.0 = 0, .1.3.6.1.4.1.232.3.2.3.1.1.4.8.1 = rebuilding(7)

or

Feb 12 13:37:10 server11 snmptrapd[25409]: 192.168.110.192: Enterprise Specific Trap (3008) Uptime: 306 days, 23:13:24.29, sysName.0 = SERVER08, cpqHoTrapFlags.0 = 0, cpqDaLogDrvStatus.8.1 = rebuilding(7)

The output from snmptrapd can be changed via the -O option to display numeric or symbolic OIDs and other display options, but it generally follows the format of variable name = value, variable name = value etc.

A more descriptive / friendly trap message can be created using SNMPTT's variable substitution. Following is the same trap, logged with SNMPTT:

Feb 12 13:37:13 server11 TRAPD: .1.3.6.1.4.1.232.0.3008 Normal "XLOGONLY" server08 - Logical Drive Status Change: Status is now rebuilding

The definition for the cpqDa3LogDrvStatusChange trap in the SNMPTT configuration file would be defined as follows:

FORMAT Logical Drive Status Change: Status is now $3.

The $3 represents the third variable as defined in the MIB file, which for this particular trap, is the cpqDaLogDrvStatus variable.

Another example of an SNMPTT configuration entry is:

FORMAT Compaq Drive Array Spare Drive on controller $4, bus $5, bay $6 status is $3.

Which could result in the following output:

"Compaq Drive Array Spare Drive on controller 3, bus 0, bay 3 status is Failed."

Snmptt can log to any of the following destinations: text log, syslog, NT Event log or a SQL database. External programs can also be run to pass the translated trap to an email client, paging software, Nagios etc.

In addition to variable substitution, SNMPTT allows complex configurations allowing:


Downloading

SNMPTT can be downloaded from http://www.sourceforge.net/projects/snmptt

Requirements

All development and testing was done with Linux, Windows 2000 or higher and various versions of Net-SNMP from UCD SNMP v4.2.1 to the current Net-SNMP 5.4.x release. The Windows version has been tested with both native mode and under Cygwin.

SNMP V1, V2 and V3 traps have been tested.

Net-SNMP 5.1.1 or higher is recommended.

UCD-SNMP v4.2.3 appears to have a bug that prevents it from working correctly with SNMPTT.  UCD-SNMP v4.2.1, v4.2.4 and v4.2.5 appear to work fine.  If you need to use UCD-SNMP v4.2.3 (for example you are using the Compaq supplied UCD-SNMP package) then you should at the very least use the snmptrapd program from v4.2.5.  Net-SNMP does not have this problem.

Note:

SNMPTT only requires the Net-SNMP Perl module if you want to have variable names translated into symbolic form, want to be able to have snmptrapd pass traps using symbolic form, or you enable the options translate_integers, translate_trap_oid or translate_oids. Although not required, using the Perl module is recommended.  It is also required if you want to use the snmptthandler-embedded trap handler with snmptrapd.

What's New

v1.4 - November 6th, 2013

v1.3 - November 15th, 2009

v1.2 - June 16th, 2007

v1.1 - January 17th, 2006

1.0 - August 30, 2004

0.9 - November 3rd, 2003

0.8 - September 16th, 2003

0.7 - April 17th, 2003

0.6 - March 25th, 2003

0.5 - February 12th, 2003

0.4 - November 18th, 2002

0.3 - September 11th, 2002

0.2 - July 10th, 2002

0.1 - April 18th, 2002

Upgrading

v1.3 to v1.4

To upgrade from v1.3 to v1.4, you should:

  1. Replace snmptt and snmptthandler-embedded with the new versions.  Make sure the files are executable (chmod +x filename).
  2. Backup your snmptt.ini file, replace it with the new version, and make any necessary configuration changes to it.  The only change is the addition of the net_snmp_perl_cache_enable option.
  3. Check your snmptt.conf files for any traps defined with LOGONLY.  These entries will no longer have EXEC lines executed.  In previous versions EXEC was exectued when it should not have been.
  4. The new snmptt.ini option net_snmp_perl_cache_enable defaults to on, so disable if required.

v1.2 to v1.3

To upgrade from v1.2 to v1.3, you should:

  1. Replace snmptt and snmpttconvertmib with the new versions.  Make sure the files are executable (chmod +x filename).
  2. Copy snmptt-init.d to /etc/init.d/snmptt.  Make sure the file is executable (chmod +x filename).
  3. Optional:  Install and configure the snmptthandler-embedded trap handler.  See Embedded handler for details.
  4. Backup your snmptt.ini file, replace it with the new version, and make any necessary configuration changes to it.  The default log paths have changed so modify as needed.
  5. Setup log rotation by copying snmptt.logrotate to /etc/logrotate.d/snmptt and modifying as needed for the correct paths, rotate frequency etc.
  6. Enable any new features in snmptt.ini as required.

v1.1 to v1.2

To upgrade from v1.1 to v1.2, you should:

  1. Replace snmptt and snmpttconvertmib with the new versions contained in the v1.2 package.  Make sure the files are executable (chmod +x filename).
  2. Backup your snmptt.ini file, replace it with the new version, and make any necessary configuration changes to it.
  3. Enable any new features in snmptt.ini as required.
  4. For Linux and Unix (or anything non-Windows), if you are using the daemon_uid option in snmptt.ini, and are monitoring the availability of snmptt by checking for the snmptt process, be aware that there will now be two snmptt processes running instead of one.
  5. For Linux and Unix (or anything non-Windows), the snmptt.ini exec_escape option is enabled by default which will escape wildcard characters (* and ?) for EXEC, PREEXEC and the unknown_trap_exec commands. Disable if required.

v1.0 to v1.1

To upgrade from v1.0 to v1.1, you should:

  1. Replace snmptt and snmpttconvertmib with the new versions contained in the v1.1 package.  Make sure the files are executable (chmod +x filename).
  2. Backup your snmptt.ini file, replace it with the new version, and make any necessary configuration changes to it.
  3. Enable any new features in snmptt.ini as required.

v0.9 to v1.0

To upgrade from v0.9 to v1.0, you should:

  1. Replace snmptt, snmpttconvert, snmpttconvertmib, and snmptthandler with the new versions contained in the v1.0 package.  Make sure the files are executable (chmod +x filename).
  2. Backup your snmptt.ini file, replace it with the new version, and make any necessary configuration changes to it
  3. If you are using a MySQL, PostgreSQL or ODBC (via DBD::ODBC) and do not want the database to be pinged before each INSERT, set mysql_ping_on_insert, postgresql_ping_on_insert or dbd_odbc_ping_on_insert to 0 in snmptt.ini. If you do not want the database to be pinged periodically, set mysql_ping_interval, postgresql_ping_interval or dbd_odbc_ping_interval to 0 in snmptt.ini.
  4. Enable any new features in snmptt.ini as required
  5. Test and report any issues to alex_b@users.sourceforge.net, or open a bug report at Sourceforge.

v0.8 to v0.9

To upgrade from v0.8 to v0.9, you should:

  1. Replace snmptt with the new version contained in the v0.9 package.  Make sure the file is executable (chmod +x filename)
  2. Backup your snmptt.ini file, replace it with the new version, and make any necessary configuration changes to it
  3. If you have any external applications that monitor the syslog for SNMPTT or TRAPD messages, modify them to look for snmptt[pid] and snmptt-sys[pid] instead
  4. Enable any new features in snmptt.ini as required
  5. Test and report any issues to alex_b@users.sourceforge.net, or open a bug report at Sourceforge.

v0.7 to v0.8

To upgrade from v0.7 to v0.8, you should:

  1. Replace snmptt and snmpttconvertmib with the new versions contained in the v0.8 package.  Make sure the files are executable (chmod +x filename)
  2. Replace your /etc/rc.d/init.d/snmptt file (cp snmptt-init.d /etc/rc.d/init.d/snmptt).  Make sure the file is executable (chmod +x filename)
  3. Backup your snmptt.ini file, replace it with the new version, and make any necessary configuration changes to it
  4. In your snmptt.ini file, configure translate_log_trap_oid with translate_trap_oid value from old snmptt.ini
  5. In your snmptt.ini file, configure translate_value_oids with translate_oids value from old snmptt.ini
  6. In your snmptt.ini file, set dynamic_nodes to 1 if you want the NODES files to be loaded each time an event is processed which is how previous versions of snmptt worked
  7. In your snmptt.conf files, replace any $A with $aA unless you want agent host names to be used instead of IP addresses
  8. In your snmptt.conf files, replace any $E with $e unless you want Enterprise trap OID in symbolic format
  9. In your snmptt.conf files, replace any $O with $o unless you want Trap OID in symbolic format
  10. In your snmptt.conf files, append a g to the end of all REGEX lines to enable global search and replace
  11. Review other translate settings in snmptt.ini
  12. Enable any new features in snmptt.ini as required
  13. If you are using database logging, add a new column called trapoid
  14. If you are using database logging and you enable conversions of OIDs to long names, make sure the table columns are wide enough to hold them
  15. Test and report any issues to alex_b@users.sourceforge.net, or open a bug report at Sourceforge.

v0.6 to v0.7

To upgrade from v0.6 to v0.7, you should:

  1. Replace SNMPTT and SNMPTTCONVERTMIB with the new versions contained in the v0.7 package
  2. Backup your snmptt.ini file, replace it with the new version, and make any necessary configuration changes to it
  3. Enable any new features in snmptt.ini as required
  4. Test and report any issues to alex_b@users.sourceforge.net, or open a bug report at Sourceforge.

v0.5 to v0.6

To upgrade from v0.5 to v0.6, you should:

  1. Replace SNMPTTHANDLER, SNMPTT and SNMPTTCONVERTMIB with the new versions contained in the v0.6 package
  2. Backup your snmptt.ini file, replace it with the new version, and make any necessary configuration changes to it
  3. Enable any new features in snmptt.ini as required
  4. Test and report any issues to alex_b@users.sourceforge.net, or open a bug report at Sourceforge.

v0.4 to v0.5

To upgrade from v0.1, v0.2 to v0.3 to v0.4, you should:

  1. Set use_trap_time to 0 to have SNMPTT operate the same as v0.4, or leave as 1 (recommended default) and test
  2. Replace both SNMPTTHANDLER and SNMPTT with the new versions contained in the v0.5 package
  3. Backup your snmptt.ini file, replace it with the new version, and make any necessary configuration changes to it

v0.1, v0.2 or v0.3 to v0.4

To upgrade from v0.1, v0.2 to v0.3 to v0.4, you should:

  1. In your snmptt.conf file, replace all $x with $x $X (see What's New section)
  2. In your snmptt.conf file, replace all $S with $N (see What's New section)
  3. Configure the snmptt.ini as described in this file - configuration options are no longer stored in the snmptt and snmptthandler scripts
  4. If your snmptt.conf file contained a list of other snmptt.conf files instead of trap definitions, move that list to the snmptt.ini file

Installation - Overview

The following outlines the general steps required to install and configure SNMPTT:

  1. Install Net-SNMP and SNMPTT as described below
  2. Create an snmptt.conf file by hand, or using snmpttconvertmib
  3. Modify snmptt.ini to include the snmptt.conf file and set any desired options
  4. Start snmptt
  5. Configure your network devices to send traps to the Net-SNMP / SNMPTT machine
  6. Initiate a trap on your network device and check the SNMPTT log files for the result
  7. Secure the SNMPTT installation

Installation - Unix

Standard handler

The standard handler is a small Perl program that is called each time a trap is received by snmptrapd when using daemon mode.  The limitations of this handler are:
The benefits of using this handler are:

1.  Read this entire file to understand how snmptt works

2.  Copy snmptt to /usr/sbin/ and ensure it is executable (chmod +x snmptt)

3.  Copy snmptthandler to /usr/sbin/ and ensure it is executable (chmod +x snmptthandler)

4.  Copy snmptt.ini to /etc/snmp/ or /etc/ and edit the options inside the file.

5.  Either copy examples/snmptt.conf.generic to /etc/snmp/snmptt.conf (renaming the file during the copy) or use the touch command to create the file (touch /etc/snmp/snmptt.conf).

6.  Create the log folder /var/log/snmptt/.

7a.   For standlone mode:  Modify (or create) the Net-SNMP snmptrapd.conf file by adding the following line:

traphandle default /usr/sbin/snmptt

Note:   It is possible to configure snmptrapd to execute snmptt based on the specific trap received, but using the default option is preferred

7b.   For daemon mode:

Modify (or create) the Net-SNMP snmptrapd.conf file by adding the following line:

traphandle default /usr/sbin/snmptthandler

Create the spool folder /var/spool/snmptt/:

mkdir /var/spool/snmptt/
A startup script is included which can be used to start and stop snmptt on Mandrake, RedHat and other systems.  Copy the script to the init.d directory (renaming the file during the copy):

cp snmptt-init.d /etc/rc.d/init.d/snmptt

Add the service using chkconfig:

chkconfig --add snmptt

Configure the service to start at runlevel 2345:

chkconfig --level 2345 snmptt on

Snmptt will be started at the next reboot, or can be started immediately with:

service snmptt start

or

/etc/rc.d/init.d/snmptt start

To manually start snmptt, use:

snmptt --daemon

8.       A log rotation script is included which can be used to rotate the log files on Mandrake, RedHat and other systems.  Copy the file to the logrotate.d directory (renaming the file during the copy):

cp snmptt.logrotate /etc/logrotate.d/snmptt

Edit the /etc/logrotate.d/snmptt and update the paths and rotate frequency as needed.

9.       Start snmptrapd using the command line:  snmptrapd -On.

You should be able to edit the /etc/rc.d/init.d/snmptrapd script if you have one and change
the OPTIONS to "-On".

Note:  The -On is recommended.  This will make snmptrapd pass OIDs in numeric form and prevent SNMPTT from having to translate the symbolic name to numerical form.  If the UCD-SNMP / Net-SNMP Perl module is not installed, then you MUST use the -On switch.  Depending on the version of UCD-SNMP / Net-SNMP, some symbolic names may not translate correctly.  See the FAQ for more info.

As an alternative, you can edit your snmp.conf file to include the line: printNumericOids 1.  This setting will take effect no matter what is used on the command line.

10.     See the Securing SNMPTT section.

Note:  The default snmptt.ini enables logging to snmptt.log and also syslog for both trap messages and snmptt system messages.  Change the following settings if required:  log_enable, syslog_enable and syslog_system_enable.


Embedded handler


The embedded handler is a small Perl program that is loaded directly into snmptrapd when snmptrapd is started.  The limitations of this handler are:
The benefits of using this handler are:

1.  Read this entire file to understand how snmptt works

2.  Make sure snmptrapd has embedded Perl support enabled.  When compiling from source, use the '--enable-embedded-perl' configuration option.  

     Type snmptrapd -H 2>&1 | grep perl.  It should give perl   PERLCODE if embedded Perl is enabled.  

     If it's not available, you need to compile Net-SNMP using the --enable-embedded-perl configure option.

3.  Copy snmptt to /usr/sbin/ and ensure it is executable (chmod +x snmptt)

4.  Copy snmptthandler-embedded to /usr/sbin/.  It does not need to be executable as it is called directly by snmptrapd.

5.  Copy snmptt.ini to /etc/snmp/ or /etc/ and edit the options inside the file.

6.  Either copy examples/snmptt.conf.generic to /etc/snmp/snmptt.conf (renaming the file during the copy) or use the touch command to create the file (touch /etc/snmp/snmptt.conf).

7.  Create the log folder /var/log/snmptt/.

8.  Configure snmptrapd and install the service:

Modify (or create) the Net-SNMP snmptrapd.conf file by adding the following line:

perl do "/usr/sbin/snmptthandler-embedded";
Create the spool folder /var/spool/snmptt/.
A startup script is included which can be used to start and stop snmptt on Mandrake, RedHat and other systems.  Copy the script to the init.d directory (renaming the file during the copy):

cp snmptt-init.d /etc/rc.d/init.d/snmptt

Add the service using chkconfig:

chkconfig --add snmptt

Configure the service to start at runlevel 2345:

chkconfig --level 2345 snmptt on

Snmptt will be started at the next reboot, or can be started immediately with:

service snmptt start

or

/etc/rc.d/init.d/snmptt start

To manually start snmptt, use:

snmptt --daemon

9.       A log rotation script is included which can be used to rotate the log files on Mandrake, RedHat and other systems.  Copy the file to the logrotate.d directory (renaming the file during the copy):

cp snmptt.logrotate /etc/logrotate.d/snmptt

Edit the /etc/logrotate.d/snmptt and update the paths and rotate frequency as needed.

10.     Start snmptrapd using the command line:  snmptrapd -On.

You should be able to edit the /etc/rc.d/init.d/snmptrapd script if you have one and change
the OPTIONS to "-On".
Note:  The -On is recommended.  This will make snmptrapd pass OIDs in numeric form and prevent SNMPTT from having to translate the symbolic name to numerical form.  If the UCD-SNMP / Net-SNMP Perl module is not installed, then you MUST use the -On switch.  Depending on the version of UCD-SNMP / Net-SNMP, some symbolic names may not translate correctly.  See the FAQ for more info.

As an alternative, you can edit your snmp.conf file to include the line: printNumericOids 1.  This setting will take effect no matter what is used on the command line.

11.     See the Securing SNMPTT section.

Note:  The default snmptt.ini enables logging to snmptt.log and also syslog for both trap messages and snmptt system messages.  Change the following settings if required:  log_enable, syslog_enable and syslog_system_enable.


Installation - Windows

The Net-SNMP trap receiver does not currently support embedded Perl, so only the standard trap handler can be used with Windows.

1.  Read this entire file to understand how snmptt works

2.  Create the directory c:\snmp and copy snmptt and snmptthandler to it. 

3.  Copy snmptt.ini-nt to %SystemRoot%\snmptt.ini (c:\winnt\snmptt.ini) and edit the options inside the file.

4.  Either copy examples/snmptt.conf.generic to c:\snmp\snmptt.conf (renaming the file during the copy) or create the file using notepad.

4.  Create the log folder c:\snmp\log\.

5a.   For standlone mode:  Modify (or create) the Net-SNMP snmptrapd.conf file by adding the following line:

traphandle default perl c:\snmp\snmptt
Note:   It is possible to configure snmptrapd to execute snmptt based on the specific trap received, but using the default option is preferred
5b.   For daemon mode:  Modify (or create) the Net-SNMP snmptrapd.conf file by adding the following line:
traphandle default perl c:\snmp\snmptthandler
Create the spool folder c:\snmptt\spool\.

Launch snmptt using:

snmptt --daemon

6.  Start SNMPTRAPD using the command line:  SNMPTRAPD -On.
     Note:  The -On is recommended.  This will make snmptrapd pass OIDs in numeric form
     and prevent SNMPTT from having to translate the symbolic name to numerical form.  If
     the UCD-SNMP / Net-SNMP Perl module is not installed, then you MUST use the
     -On switch.  Depending on the version of UCD-SNMP / Net-SNMP, some symbolic names
     may not translate correctly.  See the FAQ for more info.

     As an alternative, you can edit your snmp.conf file to include the line: printNumericOids 1.  This setting will take effect no matter what is used on the command line.

6.  See the Securing SNMPTT section.

Windows NT EventLog:

If you have enabled Windows Event Log support, then you must install an Event Message File to prevent "Event Message Not Found" messages from appearing in the Event Log.  Microsoft Knowledge Base article KB166902 contains information on this error.

The Event Message File is a binary DLL file.  Included with SNMPTT is a pre-compiled binary.  To compile the DLL yourself, see 'Compiling' below.

To install the DLL:

  1. Backup your system
  2. Make sure Event Viewer is not open
  3. Copy bin\snmptt-eventlog.dll to %windir%\system32
  4. Launch the Registry Editor
  5. Go to 'HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Eventlog\Application'
  6. Create a new subkey (under Application) called SNMPTT
  7. Inside of the SNMPTT key, create a new String Value called EventMessageFile.  Give it a value of %windir%\system32\snmptt-eventlog.dll.
  8. Inside of the SNMPTT key, create a new DWORD Value called TypesSupported.  Give it a value of 7.
To un-install the DLL:
  1. Backup your system
  2. Make sure Event Viewer is not open
  3. Launch the Registry Editor
  4. Go to 'HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Eventlog\Application'
  5. Delete the key SNMPTT
  6. Delete the file %windir%\system32
Compiling snmptt-eventlog.dll (MS Visual C++ required)
  1. If your environment is not already set up for command line compilation, locate vcvars32.bat, start a command prompt, and execute it (vcvars32.bat).
  2. cd into the directory where snmptt-eventlog.mc is located (included with SNMPTT) and execute the following commands:
  3. mc snmptt-eventlog.mc
  4. rc /r snmptt-eventlog.rc
  5. link /nodefaultlib /INCREMENTAL:NO /release /nologo -base:0x60000000 -machine:i386 -dll -noentry -out:snmptt-eventlog.dll snmptt-eventlog.res
  6. Install the DLL as described above


Windows NT Service:

To configure SNMPTT as a service under Windows NT, follow these steps.  More information can be obtained from the Windows NT Resource Kit.

1.    Install the Windows NT resource kit

2.    Copy the srvany.exe program to c:\winnt\system32 from c:\Program Files\Resource Kit *

3.    Install the SNMPTT service using:

        instsrv SNMPTT c:\winnt\system32\srvany.exe

4.    Configure the service:

        Launch REGEDIT

        Go to HKLM\SYSTEM\CurrentControlSet\SNMPTT

        Create a key called: Parameters

        Inside of Parameters, create a Sting Value (REG_SZ) called Application with the value of: c:\perl\bin\perl.exe

        Inside of Parameters, create a Sting Value (REG_SZ) called AppParameters with the value of: c:\snmp\snmptt --daemon

5.    Start the service from the control panel, or from a command prompt, type:  net start snmptt

To remove the service, type:  instsrv SNMPTT remove

Securing SNMPTT

As with most software, SNMPTT should be run without root or administrator privileges.  Running with a non privileged account can help restrict what actions can occur when using features such as EXEC and REGEX.

For Linux and Unix, if you start SNMPTT as root, a user called 'snmptt' should be created and the snmptt.ini option daemon_uid should be set to the numerical user id (eg: 500) or textual user id (snmptt). Only define daemon_uid if starting snmptt using root.

If you start SNMPTT as a non-root user, then daemon_uid is not required (and will probably not work).

When using daemon_uid in daemon mode, there will be two SNMPTT processes. The first will run as root and will be responsible for creating the .pid file, and for cleaning up the .pid file on exit. The second process will run as the user defined by daemon_uid. If the system syslog (syslog_system_enable) is enabled, a message will be logged stating the user id has been changed. All processing from that point on will be as the new user id. This can be verified by checking the user id in the syslog for traps and system messages. For example, if the user id was changed to 500, the syslog would contain entries with snmptt[500].  When running as root, entries will contain snmptt[0].

For Windows, a local or domain user account called 'snmptt' should be created.  If running as an NT service, the service should be configured to use the snmptt user account.  Otherwise the system should be logged in locally with the snmptt account before launching SNMPTT in daemon mode.

The script snmptthandler which is called from Net-SNMP's snmptrapd will be executed in the same security context as snmptrapd. 

The snmptt user should be configured with the following permissions: If snmptrapd is run as a non root / administrator, it should be configured with the following permissions:
Note:  It is recommended that only the user running snmptrapd and the snmptt user be given permission to the spool folder.  This will prevent other users from placing files into the spool folder such as non-trap related files, or the !reload file which causes SNMPTT to reload.

Configuration Options - snmptt.ini

As mentioned throughout this document, configuration options are set by editing the snmptt.ini file.

For Linux / Unix, the following directories are searched to locate snmptt.ini:

/etc/snmp/
/etc/
/usr/local/etc/snmp/
/usr/local/etc/

For Windows, the file should be in %SystemRoot%\.  For example, c:\winnt or c:\windows.

The location of the ini file can be set on the command line using the -ini= parameter.  See Command Line Arguments.

A sample snmptt.ini is provided in this package.  For Windows NT, be sure to copy the snmptt.ini-nt file to %SystemRoot%\snmptt.ini.  Be sure to remove the -nt from the end of the filename.

This readme file does not document all configuration options available in the snmptt.ini as the snmptt.ini file contains detailed descriptions for each option.

Logging - Standard

Translated traps can be sent to standard output and to a log file.  The output format is:

date trap-oid severity category hostname translated-trap
To configure standard output or regular logging, edit the snmptt.ini file and modify the following variables:
stdout_enable
log_enable
log_file

Logging - Unknown traps

Logging of unrecognized traps is also possible.  This would be used mainly for troubleshooting purposes.

To configure unknown trap logging, edit the snmptt.ini file and modify the following variables:

enable_unknown_trap_log
unknown_trap_log_file
Unknown traps can also be logged to a SQL table as described in the Database section.

Logging - Syslog

Translated traps can also be sent to syslog.  The format of the entries will be similar to above without the date (as syslogd logs the date):

trap-oid severity category hostname translated-trap
Syslog entries normally start with: date hostname snmptt[pid]:

To configure syslog, edit the snmptt ini file and modify the following variables:
syslog_enable
syslog_facility
syslog_level
SNMPTT system errors can be sent to syslog by editing the snmptt.ini file and modifying the following variables:
syslog_system_enable
syslog_system_facility
syslog_system_level
Syslog system entries normally start with: date hostname snmptt-sys[pid]:

 The following errors are logged:
SNMPTT (version) started (*)
Unable to enter spool dir x (*)
Unable to open spool dir x (*)
Unable to read spool dir x (*)
Could not open trap file x (*)
Unable to delete trap file x from spool dir (*)
Unable to delete !reload file spool dir (*)
 Unable to delete !statistics file spool dir (*)
Reloading configuration file(s) (*)
SNMPTT (version) shutdown (*)
Loading snmpttconfigfile (*)
Could not open configuration file: snmpttconfigfile(*)
Finished loading x lines from snmpttconfigfile (*)
MySQL error: Unable to connect to database
SQL error: Unable to connect to DSN
Can not open log file logfile
MySQL error: Unable to perform PREPARE
MySQL error: Unable to perform INSERT INTO (EXECUTE)
DBI DBD::ODBC error: Unable to perform INSERT INTO
Win32::ODBC error: Unable to perform INSERT INTO
PostgreSQL error: Unable to connect to database
PostgreSQL error: Unable to perform PREPARE
PostgreSQL error: Unable to perform INSERT INTO (EXECUTE)

* (daemon mode only)

Logging - EventLog

Translated traps can also be sent to the NT EventLog.  All traps are logged under EventID 2 under the source SNMPTT.  The format of the entries will be similar to above without the date (as the Event Log logs the date):

trap-oid severity category hostname translated-trap
To configure eventlog support, edit the snmptt ini file and modify the following variables:
eventlog_enable
eventlog_type
SNMPTT system errors can be sent to the Event Log by editing the snmptt.ini file and modifying the following variables:
eventlog_system_enable
The following errors are logged.  Note that each error contains a unique EventID:
EventID 0: SNMPTT (version) started (*)
EventID 3: Unable to enter spool dir x (*)
EventID 4: Unable to open spool dir x (*)
EventID 5: Unable to read spool dir x (*)
EventID 6: Could not open trap file x (*)
EventID 7: Unable to delete trap file x from spool dir (*)
EventID 20: Unable to delete !reload file spool dir (*)
 EventID 21: Unable to delete !statistics file spool dir (*)
EventID 8: Reloading configuration file(s) (*)
EventID 1: SNMPTT (version) shutdown (*)
EventID 9: Loading snmpttconfigfile (*)
EventID 10: Could not open configuration file: snmpttconfigfile(*)
EventID 11: Finished loading x lines from snmpttconfigfile(*)
EventID 12: MySQL error: Unable to connect to database
EventID 13: SQL error: Unable to connect to DSN dsn
EventID 14: Can not open log file logfile
EventID 23: MySQL error: Unable to perform PREPARE
EventID 15: MySQL error: Unable to perform INSERT INTO (EXECUTE)
EventID 16: DBI DBD::ODBC error: Unable to perform INSERT INTO
EventID 17: Win32::ODBC error: Unable to perform INSERT INTO
EventID 18: PostgreSQL error: Unable to connect to database
EventID 22: PostgreSQL error: Unable to perform PREPARE
EventID 19: PostgreSQL error: Unable to perform INSERT INTO (EXECUTE)

* (daemon mode only)

Note:
To prevent "Event Message Not Found" messages in the Event Viewer, an Event Message File must be used.  For information on installing the message file, see the Installation section for Windows.

Logging - Database

Translated and unrecognized traps can also be sent to a database.  MySQL (tested under Linux), PostgreSQL (tested under Linux) and ODBC (tested under Windows NT) can be used.

To configure unknown trap logging, edit the snmptt.ini file and modify the following variables:

enable_unknown_trap_log
db_unknown_trap_format

DBD::MySQL

To configure SNMPTT for MySQL, modify the following variables in the snmptt.ini file.

mysql_dbi_enable
mysql_dbi_host
 mysql_dbi_port
mysql_dbi_database
mysql_dbi_table
 mysql_dbi_table_unknown
mysql_dbi_username
mysql_dbi_password

Note:  Sample values are defined in the default ini file.  Defining mysql_dbi_table_unknown is optional.

The following MySQL script can create the database and table. Permissions etc should also be defined. Run 'mysql' as root and enter:

CREATE DATABASE snmptt;
USE snmptt;

DROP TABLE snmptt;
CREATE TABLE snmptt (
id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
eventname VARCHAR(50),
eventid VARCHAR(50),
trapoid VARCHAR(100),
enterprise VARCHAR(100),
community VARCHAR(20),
hostname VARCHAR(100),
agentip  VARCHAR(16),
category VARCHAR(20),
severity VARCHAR(20),
uptime  VARCHAR(20),
traptime VARCHAR(30),
formatline VARCHAR(255));

Note: To store the traptime as a real date/time (DATETIME data type), change 'traptime VARCHAR(30),' to 'traptime DATETIME,' and set date_time_format_sql in snmptt.ini to %Y-%m-%d %H:%M:%S.

Note: If you do not want the auto-incrementing id column, remove the 'id INT...' line.

If logging of unknown traps to a SQL table is required, create the snmptt_unknown table using:

USE snmptt;

DROP TABLE snmptt_unknown;
CREATE TABLE snmptt_unknown (
trapoid VARCHAR(100),
enterprise VARCHAR(100),
community VARCHAR(20),
hostname VARCHAR(100),
agentip  VARCHAR(16),
uptime  VARCHAR(20),
traptime VARCHAR(30),
formatline VARCHAR(255));

Note: To store the traptime as a real date/time (DATETIME data type), change 'traptime VARCHAR(30),' to 'traptime DATETIME,' and set date_time_format_sql in snmptt.ini to %Y-%m-%d %H:%M:%S.

If logging of statistics to a SQL table is required, create the snmptt_statistics table using:

USE snmptt;

DROP TABLE snmptt_statistics;
CREATE TABLE snmptt_statistics (
stat_time VARCHAR(30),
total_received BIGINT,
total_translated BIGINT,
total_ignored BIGINT,
total_unknown BIGINT);

Note: To store the stat_time as a real date/time (DATETIME data type), change 'stat_time VARCHAR(30),' to 'stat_time DATETIME,' and set stat_time_format_sql in snmptt.ini to %Y-%m-%d %H:%M:%S.

Note: The variable lengths I have chosen above should be sufficient, but they may need to be increased depending on your environment.

To add a user account called 'snmptt' with a password of 'mytrap' for use by SNMPTT, use the following SQL statement:

GRANT ALL PRIVILEGES ON *.* TO 'snmptt'@'localhost' IDENTIFIED BY 'mytrap';

DBD::PgPP (PostgreSQL)

To configure SNMPTT for PostgreSQL, modify the following variables in the snmptt.ini file.

postgresql_dbi_enable
postgresql_dbi_module
postgresql_dbi_hostport_enable
postgresql_dbi_host
 postgresql_dbi_port
postgresql_dbi_database
postgresql_dbi_table
 postgresql_dbi_table_unknown
postgresql_dbi_username
postgresql_dbi_password

Note: Sample values are defined in the default ini file. Defining postgresql_dbi_table_unknown is optional.

The following shell / PostgreSQL commands will drop the existing database if it exists and then delete the existing snmptt user. It will then create a new snmptt database, a new snmptt user (prompting for a password) and then create the table. Run these commands as root.

su - postgres
dropdb snmptt
dropuser snmptt

createuser -P snmptt
createdb -O snmptt snmptt
psql snmptt

DROP TABLE snmptt;
CREATE TABLE snmptt (
eventname VARCHAR(50),
eventid VARCHAR(50),
trapoid VARCHAR(100),
enterprise VARCHAR(100),
community VARCHAR(20),
hostname VARCHAR(100),
agentip  VARCHAR(16),
category VARCHAR(20),
severity VARCHAR(20),
uptime  VARCHAR(20),
traptime VARCHAR(30),
formatline VARCHAR(255));

GRANT ALL ON snmptt TO snmptt;
\q

Note: To store the traptime as a real date/time (timestamp data type), change 'traptime VARCHAR(30),' to 'traptime timestamp,' and set date_time_format_sql in snmptt.ini to %Y-%m-%d %H:%M:%S.

If logging of unknown traps to a SQL table is required, create the snmptt_unknown table using:
su - postgres
psql snmptt

DROP TABLE snmptt_unknown;
CREATE TABLE snmptt_unknown (
trapoid VARCHAR(100),
enterprise VARCHAR(100),
community VARCHAR(20),
hostname VARCHAR(100),
agentip  VARCHAR(16),
uptime  VARCHAR(20),
traptime VARCHAR(30),
formatline VARCHAR(255));

GRANT ALL ON snmptt_unknown TO snmptt;
\q

Note: To store the traptime as a real date/time (timestamp data type), change 'traptime VARCHAR(30),' to 'traptime timestamp,' and set date_time_format_sql in snmptt.ini to %Y-%m-%d %H:%M:%S.

If logging of statistics to a SQL table is required, create the snmptt_statistics table using:
su - postgres
psql snmptt

DROP TABLE snmptt_statistics;
CREATE TABLE snmptt_statistics (
stat_time VARCHAR(30),
total_received BIGINT,
total_translated BIGINT,
total_ignored BIGINT,
total_unknown BIGINT);

GRANT ALL ON snmptt_statistics TO snmptt;
\q

Note: To store the stat_time as a real date/time (timestamp data type), change 'stat_time VARCHAR(30),' to 'stat_time timestamp,' and set stat_time_format_sql in snmptt.ini to %Y-%m-%d %H:%M:%S.

The variable lengths I have chosen above should be sufficient, but they may need to be increased depending on your environment.

DBD::ODBC

SNMPTT can access ODBC data sources using either the DBD::ODBC module on Linux and Windows, or the WIN32::ODBC module on Windows.

To configure SNMPTT for ODBC access using the module DBD::ODBC, modify the following variables in the snmptt script.

dbd_odbc_enable = 1;
dbd_odbc_dsn = 'snmptt';
dbd_odbc_table = 'snmptt';
 dbd_odbc_table_unknown = 'snmptt';
dbd_odbc_username = 'snmptt';
dbd_odbc_password = 'password';
Note: 
SNMPTT does not create the DSN connection. You must define the DSN outside of SNMPTT. See 'Data Sources (ODBC)' in Windows help for information on creating a DSN connection.

Defining dbd_odbc_table_unknown is optional.

Sample values are defined in the default ini file.

The following MS SQL Server / Access script can create the table inside an existing database.  Permissions etc should also be defined.

CREATE TABLE snmptt (
eventname character(50) NULL,
eventid  character(50) NULL,
trapoid  character(100) NULL,
enterprise character(100) NULL,
community character(20) NULL,
hostname character(100) NULL,
agentip  character(16) NULL,
category character(20) NULL,
severity character(20) NULL,
uptime  character(20) NULL,
traptime character(30) NULL,
formatline character(255) NULL)

Note: To store the traptime as a real date/time, change 'traptime character(30),' to the date/time data type supported by the database and and set date_time_format_sql in snmptt.ini to a compatible format. For example: %Y-%m-%d %H:%M:%S.

If logging of unknown traps to a SQL table is required, create the snmptt_unknown table using:
CREATE TABLE snmptt_unknown (
trapoid  character(100) NULL,
enterprise character(100) NULL,
community character(20) NULL,
hostname character(100) NULL,
agentip  character(16) NULL,
uptime  character(20) NULL,
traptime character(30) NULL,
formatline character(255) NULL)

Note: To store the traptime as a real date/time, change 'traptime character(30),' to the date/time data type supported by the database and and set date_time_format_sql in snmptt.ini to a compatible format. For example: %Y-%m-%d %H:%M:%S.

If logging of statistics to a SQL table is required, create the snmptt_statistics table using:
CREATE TABLE snmptt_statistics (
stat_time character(30) NULL,
total_received BIGINT NULL,
total_translated BIGINT NULL,
total_ignored BIGINT NULL,
total_unknown BIGINT NULL)

Note: To store the stat_time as a real date/time, change 'stat_time character(30),' to the date/time data type supported by the database and and set stat_time_format_sql in snmptt.ini to a compatible format. For example: %Y-%m-%d %H:%M:%S.

All variables are inserted into the database using 'INSERT INTO' as text including the date and time.  The variable lengths I have chosen above should be sufficient, but they may need to be increased depending on your environment.
 

Win32::ODBC

SNMPTT can access ODBC data sources using either the DBD::ODBC module on Linux and Windows, or the WIN32::ODBC module on Windows.

To configure SNMPTT for MS SQL via ODBC on Windows, modify the following variables in the snmptt script.

sql_win32_odbc_enable = 1;
sql_win32_odbc_dsn = 'snmptt';
sql_win32_odbc_table = 'snmptt';
sql_win32_odbc_username = 'snmptt';
sql_win32_odbc_password = 'password';
Note: 
SNMPTT does not create the DSN connection. You must define the DSN outside of SNMPTT. See 'Data Sources (ODBC)' in Windows help for information on creating a DSN connection.

Defining sql_win32_odbc_table_unknown is optional.

Sample values are defined in the default ini file.

The following MS SQL Server script can create the table inside an existing database.  Permissions etc should also be defined.

CREATE TABLE snmptt (
eventname character(50) NULL,
eventid  character(50) NULL,
trapoid  character(50) NULL,
enterprise character(50) NULL,
community character(20) NULL,
hostname character(100) NULL,
agentip  character(16) NULL,
category character(20) NULL,
severity character(20) NULL,
uptime  character(20) NULL,
traptime character(30) NULL,
formatline character(255) NULL)

Note: To store the traptime as a real date/time, change 'traptime character(30),' to the date/time data type supported by the database and and set date_time_format_sql in snmptt.ini to a compatible format. For example: %Y-%m-%d %H:%M:%S.

If logging of unknown traps to a SQL table is required, create the snmptt_unknown table using:
CREATE TABLE snmptt_unknown (
trapoid  character(50) NULL,
enterprise character(50) NULL,
community character(20) NULL,
hostname character(100) NULL,
agentip  character(16) NULL,
uptime  character(20) NULL,
traptime character(30) NULL,
formatline character(255) NULL)

Note: To store the traptime as a real date/time, change 'traptime character(30),' to the date/time data type supported by the database and and set date_time_format_sql in snmptt.ini to a compatible format. For example: %Y-%m-%d %H:%M:%S.

If logging of statistics to a SQL table is required, create the snmptt_statistics table using:
CREATE TABLE snmptt_statistics (
stat_time character(30) NULL,
total_received BIGINT NULL,
total_translated BIGINT NULL,
total_ignored BIGINT NULL,
total_unknown BIGINT NULL)

Note: To store the stat_time as a real date/time, change 'stat_time character(30),' to the date/time data type supported by the database and and set stat_time_format_sql in snmptt.ini to a compatible format. For example: %Y-%m-%d %H:%M:%S.

All variables are inserted into the database using 'INSERT INTO' as text including the date and time.  The variable lengths I have chosen above should be sufficient, but they may need to be increased depending on your environment.
 

Executing an external program

An external program can be launched when a trap is received.  The command line is defined in the configuration file.  For example, to send a page using QPAGE (http://www.qpage.org), the following command line could be used:

qpage -f TRAP notifygroup1 "$r $x $X Compaq Drive Array Spare Drive on controller $4, bus $5, bay $6 status is $3."
$r is translated to the hostname, and $x is the current date, and $X is the current time (described in detail below)

To enable or disable the execution of EXEC definitions, edit the snmptt.ini file and modify the following variable:

exec_enable
It is also possible to launch an external program when an unknown trap is received. This can be enabled by defining unknown_trap_exec in snmptt.ini. Passed to the command will be all standard and enterprise variables, similar to unknown_trap_log_file but without the newlines.

Modes of Operation

SNMPTT can be run in two modes:  standalone mode and daemon mode.

Standalone mode

To use SNMPTT in standalone mode, the snmptrapd.conf file would contain a traphandle statement such as:

traphandle default /usr/sbin/snmptt
When a trap is received by SNMPTRAPD, the trap is passed to the /usr/sbin/snmptt script.  SNMPTT performs the following tasks: With a 450 Mhz PIII and a 9000 line snmptt.conf containing 566 unique traps (EVENTs), it takes under a second to process the trap including logging and executing the qpage program.  The larger the snmptt.conf file is, the longer it will take to process.  If there are a large number of traps being received, daemon mode should be used.  If it takes 1 second to process one trap, then obviously you shouldn't try to process more than one trap per second.

Running SNMPTT without the --daemon command line option will result standalone mode unless the mode variable in the snmptt.ini file is set to daemon.  For standalone mode, the mode variable in the snmptt.ini file should be set standalone.

Note: Enabling the UCD-SNMP / Net-SNMP Perl module will greatly increase the startup time of SNMPTT.  Daemon mode is recommended.

Daemon mode

When SNMPTT is run in daemon mode, the snmptrapd.conf file would contain a traphandle statement such as:

traphandle default /usr/sbin/snmptthandler
When a trap is received by SNMPTRAPD, the trap is passed to the /usr/sbin/snmptthandler script.  SNMPTTHANDLER performs the following tasks: SNMPTT running in daemon mode performs the following tasks: Using SNMPTTHANDLER and SNMPTT in daemon mode, a large number of traps per minute should be handled easily.

Running SNMPTT with the --daemon command line option or setting the mode variable in the snmptt.ini file to daemon will cause SNMPTT to run in daemon mode.

By setting the snmptt.ini variable use_trap_time to 1 (default), the date and time used for logging will be the date and time passed inside the trap spool file.  If use_trap_time is set to 0, the date and time that the trap was processed by SNMPTT is used.  Setting use_trap_time to 0 can result in inaccurate time stamps in log files due to the length of time SNMPTT sleeps between spool directory polling.

Note:  When running on a non Windows platform, SNMPTT will fork to the background and create a pid file in /var/run/snmptt.pid if daemon_fork is set to 1.  If the user is not able to create the /var/run/snmptt.pid file, it will attempt to create one in the current working directory.

Sending the HUP signal to SNMPTT when running as a daemon will cause it to reload the configuration file including the .ini file, snmptt.conf files listed in the .ini file and any NODES files if dynamic_nodes is disabled.  A reload can also be forced by adding a file to the spool directory called !reload.  The filename is not case sensitive.  If this file is detected, it will flag a reload to occur and will delete the file.  This would be the only way to cause a reload when using Windows as Windows does not support signals.

Statistical logging of total traps received, total traps translated and total unknown traps can be enabled by setting the statistics_interval snmptt.ini variable to a value greater than 0.  At each interval (defined in seconds), the statistics will be logged to syslog or the event log.

Sending the USR1 signal will also cause the statistical information for total traps received, total traps translated and total unknown traps to be logged.  This could be used for example if you want to log statistics at a set time each day using a task scheduler instead of using the interval time defined in the snmptt.ini variable statistics_interval.  A statistics dump can also be forced by adding a file to the spool directory called !statistics which is processed similar to the !reload file.

Command line arguments

The following command line arguments are supported:

Usage:
    snmptt [<options>]
Options:
    --daemon                    Start in daemon mode
    --debug=n                   Set debug level (1 or 2)
    --debugfile=filename    Set debug output file
    --dump                        Dump (display) defined traps
    --help                          Display this message
    --ini=filename               Specify path to snmptt.ini file
    --version                      Display author and version information
    --time                          Use to see how long it takes to load and
                                        process trap file (eg: time snmptt --time)
 

SNMPTT.CONF Configuration file format

The configuration file (usually /etc/snmp/snmptt.conf or c:\snmp\snmptt.conf) contains a list of all the defined traps.

If your snmptt.conf file is getting rather large and you would like to divide it up into many smaller files, then do the following:

-create additional snmptt.conf files
-add the file names to the snmptt_conf_files section in the snmptt.ini file.

For example:

snmptt_conf_files = <<END
/etc/snmp/snmptt.conf.generic
/etc/snmp/snmptt.conf.compaq
/etc/snmp/snmptt.conf.cisco
/etc/snmp/snmptt.conf.hp
/etc/snmp/snmptt.conf.3com
END
The syntax of the snmptt.conf file  is:
EVENT event_name event_OID "category" severity

FORMAT format_string

[EXEC command_string]

[NODES sources_list]

[MATCH [MODE=[or | and]] | [$n:[!][(    ) | n | n-n | > n | < n | x.x.x.x | x.x.x.x-x.x.x.x | x.x.x.x/x]]

[REGEX (    )(    )[i][g][e]]

[SDESC]
[EDESC]

Note: Lines starting with a # will be ignored.

Note:  The EVENT and FORMAT line are REQUIRED.  Commands in [] are optional.  Do NOT include the []s in the configuration file!

EVENT:

EVENT event_name event_OID "category" severity

event_name:

Unique text label (alias) containing no spaces.  This would match the name on the TRAP-TYPE or NOTIFICATION-TYPE line in the MIB file when converted using snmpttconvertmib.
event_OID:
Object identifier string in dotted format or symbolic notation containing no spaces.

For example, a Compaq (enterprise .1.3.6.1.4.1.232) cpqHoGenericTrap trap (trap 11001) would be written as:

.1.3.6.1.4.1.232.0.11001

Symbolic names can also be used if the UCD-SNMP / Net-SNMP Perl module is installed and enabled by setting net_snmp_perl_enable in the snmptt.ini file.  For example:

linkDown

IF-MIB::linkDown

Note:

Net-SNMP 5.0.9 and earlier does not support including the module name (eg: IF-MIB::) when translating an OID.  A patch is available for 5.0.8+ that is included in Net-SNMP 5.1.1 and higher. The patch is available from the Net-SNMP patch page.  If the version of Net-SNMP you are using does not support this feature and the event OID is specified with the module name, the event definition will be ignored.  Also note that UCD-SNMP may not properly convert symbolic names to numeric OIDs which could result in traps not being matched.
SNMP V1 traps are in the format of enterprise ID (.1.3.6.1.4.1.232) followed by a 0, and then followed by the trap number (11001).

There can be multiple entries for the same trap OID in the configuration file.  If multiple_event is enabled in the snmptt.ini, then it will process all matching traps.  If multiple_event is disabled, only the first matching entry will be used.

Wildcards in dotted format notation can  also be used.  For example:

.1.3.6.1.4.1.232.1.2.*

Note:

Specific trap matches are performed before wildcards so if you have an entry for .1.3.6.1.4.1.232.1.2.5 AND .1.3.6.1.4.1.232.1.2.*, it will process the .5 trap when received even if the wildcard is defined first.

Wildcard matches are only matched if there are NO exact matches.  This takes into consideration the NODES list.  Therefore, if there is a matching trap, but the NODES list prevents it from being considered a match, the wildcard entry will only be used if there are no other exact matches.

category:
Character string enclosed in double "s.  Used when logging output (see above).

If the category is "IGNORE", no action will take place even if the snmptt.conf contains FORMAT and / or EXEC statements.

If the category is "LOGONLY", the trap will be logged as usual, but the EXEC statement will be ignored.

Note:   If you plan on using an external program such as Nagios for logging, paging etc, you probably do not want any traps defined with LOGONLY as the EXEC line would never be used to submit the passive service check.

severity:
Character string of the severity of the event.  Used in the output when logging.  Example: Minor, Major, Normal, Critical, Warning.  The snmptt.ini contains options to match the syslog level or NT Event Log type to the severity level.

FORMAT:

FORMAT format_string

There can be only one FORMAT line per EVENT.

The format string is used to generate the text that will be logged to any of the supported logging methods.

Variable substitution is performed on this string using the following variables:

$A - Trap agent host name (see Note 1)
$aA - Trap agent IP address
$Be - securityEngineID (snmpEngineID) (see Note 7)
$Bu - securityName (snmpCommunitySecurityName) (see Note 7)
$BE - contextEngineID (snmpCommunityContextEngineID) (see Note 7)
$Bn - contextName (snmpCommunityContextName) (see Note 7)
$c - Category
$C - Trap community string
$D - Description text from SNMPTT.CONF or MIB file (see Note 6)
$E - Enterprise trap OID in symbolic format
$e  - Enterprise trap OID in number format
$Fa  - alarm (bell) (BEL)
$Ff  - form feed (FF)
$Fn  - newline (LF, NL)
$Fr  - return (CR)
$Ft  - tab (HT, TAB)
$Fz  - Translated FORMAT line (EXEC only)
$G  - Generic trap number (0 if enterprise trap)
$H  - Host name of the system running SNMPTT
$S  - Specific trap number (0 if generic trap)
$N  - Event name defined in .conf file of matched entry
$i  - Event OID defined in .conf file of matched entry (could be a wildcard OID)
$O - Trap OID in symbolic format (see Note 4)
$o - Trap OID in numerical format (see Note 4)
$R, $r  - Trap hostname (see Note 1)
$aR, $ar - IP address
$s  - Severity
$T  - Uptime:  Time since network entity was initialized
$X  - Time trap was spooled (daemon mode) or current time (standalone mode)
$x  - Date trap was spooled (daemon mode) or current date (standalone mode)
$# - Number of (how many) variable-bindings in the trap
$$  - Print a $
$@ - Number of seconds since the epoch of when the trap was spooled (daemon mode) or the current time (standalone mode)
$n  - Expand variable-binding n (1-n) (see Note 2,5)
$+n  - Expand variable-binding n (1-n) in the format of variable name:value (see Note 2,3,5)
$-n  - Expand variable-binding n (1-n) in the format of variable name (variable type):value (see Note 2,3,5)
$vn  - Expand variable name of the variable-binding n (1-n)(see Note 3)
$*  - Expand all variable-bindings (see Note 5)
$+*  - Expand all variable-bindings in the format of variable name:value (see Note 2,3,5)
$-*  - Expand all variable-bindings in the format of variable name (variable type):value (see Note 2,3,5)
Example:
FORMAT NIC switchover to slot $3, port $4 from slot $5, port $6

Note:

For the text log file, the output will be formatted as:
date time trap-OID severity category hostname - format
For all other log files except MySQL, DBD::ODBC and Win32::ODBC, the output will be formatted as:
trap-OID severity category hostname - format
For MySQL, DBD::ODBC and Win32::ODBC, the formatline column will contain only the format text.
Note (1):
See the section 'Name Resolution / DNS' for important DNS information.
Note (2):
If  translate_integers is enabled in the snmptt.ini file, SNMPTT will attempt to convert integer values received in traps into text by performing a lookup in the MIB file.

You must have the UCD-SNMP / Net-SNMP Perl module installed for this to work and you must enable support for it by enabling net_snmp_perl_enable in the snmptt.ini file.

For this feature to work, you must ensure UCD-SNMP / Net-SNMP is configured correctly with all the required MIBS.  If the option is enabled, but the value can not be found, the integer value will be used.  If the MIB files are present, but translations do not occur, ensure UCD-SNMP / Net-SNMP is correctly configured to process all the required mibs.  This is configured in the UCD-SNMP / Net-SNMP snmp.conf file.  Alternatively, you can try setting the mibs_enviroment variable in snmptt.ini to ALL (no quotes) to force all MIBS to be initialized at SNMPTT startup.

If translate_integers is enabled while using stand-alone mode, it may take longer to process each trap due to the initialization of the MIB files.

Note (3):
$vn, $+n and $-n variable names and variable type are translated into the text name by performing a lookup in the MIB file.  You must have the UCD-SNMP / Net-SNMP Perl module installed for this to work and you must enable support for it by enabling net_snmp_perl_enable in the snmptt.ini file.  If net_snmp_perl_enable is not enabled, the $vn variable will be replaced with the text 'variablen' where n is the variable number (1+).

For the name translation to work, you must ensure UCD-SNMP / Net-SNMP is configured correctly with all the required MIBS.  If the option is enabled and the correct name is not returned, ensure UCD-SNMP / Net-SNMP is correctly configured to process all the required mibs.  This is configured in the UCD-SNMP / Net-SNMP snmp.conf file.  Alternatively, you can try setting the mibs_enviroment variable in snmptt.ini to ALL (no quotes) to force all MIBS to be initialized at SNMPTT startup.

Note (4):

If  translate_trap_oid is enabled in the snmptt.ini file, SNMPTT will attempt to convert the numeric OID of the received trap into symbolic form such as IF-MIB::linkDown.  You must have the UCD-SNMP / Net-SNMP Perl module installed for this to work and you must enable support for it by enabling net_snmp_perl_enable in the snmptt.ini file.  If net_snmp_perl_enable is not enabled, it will default to using the numeric OID. 

Net-SNMP 5.0.9 and earlier does not support including the module name (eg: IF-MIB::) when translating an OID and most of the 5.0.x versions do not properly tranlsate numeric OIDs to long symbolic names.  A patch is available for 5.0.8+ that is included in Net-SNMP 5.1.1 and higher. The patch is available from the Net-SNMP patch page.

Note (5):

If  translate_oids is enabled in the snmptt.ini file, SNMPTT will attempt to convert any numeric OIDs found inside the variables passed inside the trap to symbolic form.  You must have the UCD-SNMP / Net-SNMP Perl module installed for this to work and you must enable support for it by enabling net_snmp_perl_enable in the snmptt.ini file.  If net_snmp_perl_enable is not enabled, it will default to using the numeric OID. 

Net-SNMP 5.0.9 and earlier does not support including the module name (eg: IF-MIB::) when translating an OID and most of the 5.0.x versions do not properly tranlsate numeric OIDs to long symbolic names.  A patch is available for 5.0.8+ that is inlcuded in Net-SNMP 5.1.1 and higher. The patch is available from the Net-SNMP patch page.

Note (6):

The snmptt.ini description_mode option must be set to either 1 or 2. If set to 1, the description is pulled from the SNMPTT.CONF files. If set to 2, the description is pulled from the MIB file. If using the MIB file, you must have the UCD-SNMP / Net-SNMP Perl module installed and enabled.
Note (7):
These variables are only available when using the embedded trap handler for snmptrapd (snmptthandler-embedded).

EXEC:

[EXEC command_string]

There can be multiple EXEC lines per EVENT.

Optional string containing a command to execute when trap is received and arguments to pass to the program.  The EXEC lines are executed in the order that they appear.

EXEC uses the same variable substitution as the FORMAT line.

Example:

EXEC /usr/bin/qpage -f TRAP alex "$r: $x $X - NIC switchover to slot $3, port $4 from slot $5, port $6"
or
EXEC c:\snmp\pager netops "$r: $x $X - NIC switchover to slot $3, port $4 from slot $5, port $6"
Note: Unlike the FORMAT line, nothing is prepended to the message.  If you would like to include the hostname and date in the page above, you must use the variables such as $r, $x and $X.

Note: If the trap severity is set to LOGONLY in the snmptt.conf file, EXEC will not be executed.

PREEXEC:

[PREEXEC command_string]

There can be multiple PREEXEC lines per EVENT.

Optional string containing a command to execute after a trap is received but before the FORMAT and EXEC statements are processed. The output of the external program is stored in the $pn variable where n is a number starting from 1. Multiple PREEXEC lines are permitted. The first PREEXEC stores the result of the command in $p1, the second in $p2 etc. Any ending newlines are removed. The snmptt.ini parameter pre_exec_enable can be used to enable / disable PREEXEC statements.

PREEXEC uses the same variable substitution as the FORMAT line.

Example:

EVENT linkDown .1.3.6.1.6.3.1.1.5.3 "Status Events" Normal
FORMAT Link down on interface $1($p1). Admin state: $2. Operational state: $3
PREEXEC /usr/local/bin/snmpget -v 1 -Ovq -c public $aA ifDescr.$1

Sample output:

Link down on interface 69("100BaseTX Port 1/6 Name SERVER1"). Admin state up. Operational state: down

In the above example the result is in quotes because that is what comes back from snmpget (it is not added by SNMPTT).

Note: PREEXEC will execute even if the trap severity is set to LOGONLY in the snmptt.conf file.

NODES:

[NODES sources_list]

Used to limit which devices can be mapped to this EVENT definition. 

There can be multiple NODES lines per EVENT.

Optional string containing any combination of host names, IP addresses, CIDR network address, network IP address ranges, or a filename.  If this keyword omitted then ALL sources will be accepted.  Each entry is checked for a match.  As soon as one match occurs, searching stops.

For example, if you only wanted devices on the subnet 192.168.1.0/24 to trigger this EVENT, you could use a NODES entry of:

NODES 192.168.1.0/24

If a filename is specified, it must be specified with a full path. 

There are two modes of operation: POS (positive - the default) and NEG (negative). If set to POS, then NODES is a 'match' if any of the NODES entries match. If set to NEG, then NODES is a 'match' only if none of the NODES entries match. To change the mode of operation, use one of the following statements:

NODES MODE=POS
NODES MODE=NEG

A common use for this feature is when you have devices that implement a trap in a non-standard way (added additional variables for example) such as the linkDown and linkUp traps. By defining two EVENT statements and using NODES statements with NODES MODE, you can have one EVENT statement handle the standard devices, and the other handle the other devices with the extended linkDown / linkUp traps.

Example 1:
This example will match any hosts called fred, barney, betty or wilma:

NODES fred barney betty wilma
Example 2:
This example will match any hosts not called fred, barney, betty or wilma:

NODES fred barney betty wilma
NODES MODE=NEG
Example 3:
This example will load the file /etc/snmptt-nodes (see below), and match any hosts called fred, barney, betty, network ip addresses  192.168.1.1, 192.168.1.2, 192.168.1.3, 192.168.2.1, network range 192.168.50.0/22 or network range 192.168.60.0-192.168.61.255:

NODES /etc/snmptt-nodes
Example 4:
This example will load both files /etc/snmptt-nodes and /etc/snmptt-nodes2 (see above example):

NODES /etc/snmptt-nodes /etc/snmptt-nodes2
Example 5:
NODES 192.168.4.0/22 192.168.60.0-192.168.61.255 /etc/snmptt-nodes2
Example 6:
NODES fred /etc/snmptt-nodes pebbles /etc/snmptt-nodes2 barney
where snmptt-nodes contains:
fred
barney betty
# comment lines
192.168.1.1 192.168.1.2 192.168.1.3
192.168.2.1
192.168.50.0/22
192.168.60.0-192.168.61.255
wilma
Notes:
The names are NOT case sensitive and comment lines are permitted by starting the line with a #.

CIDR network addresses must be specified using 4 octets followed by a / followed by the number of bits.  For example: 172.16.0.0/24.  Using 172.16/24 will NOT work.

Do not use any spaces between network ranges as they will be interpreted as two different values.  For example, 192.168.1.1   -    192.168.1.20 will not work.  Use 192.168.1.1-192.168.1.20 instead.

By default, NODES files are loaded when the snmptt.conf files are loaded (during startup of SNMPTT).  The snmptt.ini option dynamic_nodes can be set to 1 to have the nodes files loaded each time an EVENT is processed.

See the section 'Name Resolution / DNS' for important DNS information.

MATCH:


[MATCH [MODE=[or | and]] | [$n:[!][(    )[i] | n | n-n | > n | < n | x.x.x.x | x.x.x.x-x.x.x.x | x.x.x.x/x]]

Optional match expression that must be evaluated to true for the trap to be considered a match to this EVENT definition.

If a MATCH statement exists, and no matches evaluate to true, then the default will be to NOT match this EVENT definition.

The following Perl regular expression modifiers are supported:

i - ignore case when trying to match

The following command formats are available:

MATCH MODE=[or | and]
MATCH $x: [!] (reg) [i]
MATCH $x: [!] n
MATCH $x: [!] n-n
MATCH $x: [!] < n
MATCH $x: [!] > n
MATCH $x: [!] & n
MATCH $x: [!] x.x.x.x
MATCH $x: [!] x.x.x.x-x.x.x.x
MATCH $x: [!] x.x.x.x/x

where:
or or and set the default evaluation mode for ALL matches
$x is any variable (example: $3, $A etc)
reg is a regular expression
! is used to negate the result (not)
& is used to perform a bitwise AND
n is a number
x.x.x.x is an IP address
x.x.x.x-x.x.x.x is an IP network address range
x.x.x.x/x is an IP CIDR network addresss
Notes:

To limit which devices can be mapped to this EVENT definition based on the IP address / hostname of the device / agent that sent the trap, the NODES keyword is recommended.

If the match mode is 'or', once a match occurs no other matches are performed and the end result is true.

If the match mode is 'and', once a match fails, no other matches are performed and the end result is false.

To use parentheses ( or ) in the search expression, they must be backslashed (\).

If no MATCH MODE= line exists, it defaults to 'or'.

There can be only one match mode per EVENT.  If multiple MATCH MODE= lines exists, the last one in the list is used.
Examples:

$2 must be between 1000 and 2000:

MATCH $2: 1000-2000

Any one must match (or): $3 must be 52, or $4 must be an IP address between 192.168.1.10 and 192.168.1.20, or the severity must be 'Major':

MATCH $3: 52
MATCH $4: 192.168.1.10-192.168.1.20
MATCH $s: (Major)

All must match (and): $3 must be greater than 20, and $5 must not contain the words alarm or critical, $6 must contain the string '(1) remaining' and $7 must contain the string 'power' which is not case sensitive:

MATCH $3: >20
MATCH $5: !(alarm|critical)
MATCH $6: (\(1\) remaining)
 MATCH $7: (power)i
MATCH MODE=and

The integer $1 must have bit 4 set:

MATCH $1: &8

REGEX:


[REGEX(    )(    )[i][g][e]]

Optional regular expression to perform a search and replace on the translated FORMAT / EXEC line.  Multiple REGEX (    )(    ) lines are permitted.

First (    ) contains the search expression.
Second (    ) contains the replacement text

The following Perl regular expression modifiers are supported:

i - ignore case when trying to match left side
g - replace all occurances instead of only the first
e - execute the right side (eval) as code

To use substitution with captures (memory parenthesis) or the e modifier, you must first enable support in the snmptt.ini file by setting allow_unsafe_regex to 1.  Note:  This is considered unsafe because the contents of the right expression is executed (eval) by Perl which could contain unsafe code.  If this option is enabled, BE SURE THAT THE SNMPTT CONFIGURATION FILES ARE SECURE! 

Each REGEX line is processed in order from top to bottom and are accumulative.  The second REGEX operates on the results of the first REGEX etc.

Example:

FORMAT line before:  UPS has       detected a      building alarm.       Cause: UPS1 Alarm #14: Building alarm 3.

REGEX (Building alarm 3)(Computer room high temperature)
 REGEX (Building alarm 4)(Moisture detection alarm)
REGEX (roOm)(ROOM)ig
REGEX (UPS)(The big UPS)
REGEX (\s+)( )g

FORMAT line after:  The big UPS has detected a building alarm. Cause: UPS1 Alarm #14: Computer ROOM high temperature

To use parentheses ( or ) in the search expression, they must be backslashed (\) otherwise it is interpreted as a capture (see below).  The replacement text does not need to be backslashed.

Example:

FORMAT line before:  Alarm (1) and (2) has been triggered

REGEX (\(1\))(One)
REGEX (\(2\))((Two))

FORMAT line after:  Alarm One and (Two) has been triggered
If allow_unsafe_regex is enabled, then captures can be used in the replacement text.

Example:

FORMAT line before:  The system has logged exception error 55 for the service testservice

REGEX (The system has logged exception error (\d+) for the service (\w+))(Service $2 generated error $1)

FORMAT line after:  Service testservice generated error 55

If allow_unsafe_regex is enabled and an e modifier is specified, then the right side is executed (evaluated).  This allows you to use Perl functions to perform various tasks such as convert from hex to decimal, format text using sprintf etc.  All text must be inside of quotes, and statements can be concatenated together using the dot (.).

Example 1:

FORMAT line before:  Authentication Failure Trap from IP address: C0 A8 1 FE

REGEX (Address: (\w+)\s+(\w+)\s+(\w+)\s+(\w+))("address: ".hex($1).".".hex($2).".".hex($3).".".hex($4))ei

FORMAT line after:  Authentication Failure Trap from IP address: 192.168.1.254

Example 2:

FORMAT line before:  Authentication Failure Trap from IP address: C0 A8 1 FE

REGEX (Address: (\w+)\s+(\w+)\s+(\w+)\s+(\w+))("address:".sprintf("%03d.%03d.%03d.%03d",hex($1),hex($2),hex($3),hex($4)))ie


FORMAT line after:  Authentication Failure Trap from IP address: 192.168.001.254

Example 3

This example is for a BGP bgpBackwardTranstion trap.  The OID for the bgpBackwardTranstion trap has the IP address of the device that transitioned appended to the end of the OID.  To create a meaningful trap message, the IP address needs to be separated from the variable OID.  Because the IP address is part of the OID variable name instead of the OID value, a REGEX expression is needed.  The following uses the $+1 variable on the FORMAT line so REGEX can parse out the IP address. 

FORMAT line before:  Peer:$+2

 FORMAT line after substitution, but before REGEX:  Peer:bgpPeerState.192.168.1.1:idle

REGEX (Peer:.*\.(\d+\.\d+\.\d+\.\d+):(.*))("Peer: $1 has transitioned to $2")e

FORMAT line after:  Peer: 192.168.1.1 has transitioned to idle


Example 4

This example is a sample of using Perl subroutines inside of a REGEX statement.

FORMAT line before:  Extremely severe error has occured

REGEX (Extremely severe error has occured)(("Better get a lotto ticket!!  Here is a lotto number to try:".sprintf ("%s", lottonumber());sub lottonumber { for(my $i=0;$i<6;$i++) { $temp = $temp . " " . (int(rand 49) +1); } return $temp; } )ie

FORMAT line after:  Better get a lotto ticket!!  Here is a lotto number to try: 36 27 38 32 29 6


Note:  The REGEX expression is executed on the final translated FORMAT / EXEC line, after all variable substitutions have been completed.


SDESC

[SDESC]

Optional start of a description.  All text between this line and the line EDESC will be ignored by snmptt. This section can be used to enter comments about the trap for your own use.  If you use a SDESC, you MUST follow with a EDESC.

EDESC

[EDESC]

Used to end the description section.

Example:

SDESC
Trap used when power supply fails in
a server.
EDESC

SNMPTT.CONF Configuration file Notes

When there are multiple definitions of the same trap in the configuration file, the following rules apply:

A match occurs when:

If multiple_event is set to 1 in snmptt.ini: If multiple_event is set to 0 in snmptt.ini:

Name resolution / DNS

Snmptrapd passes the IP address of the device sending the trap (host), the host name of the device sending the trap (host) (if configured to resolve host names) and the IP address of the actual SNMP agent (agent).

If the configuration setting dns_enable is set to 0 (dns disabled), then the host name of the AGENT will not be available for the $A variable, NODES matches, and the hostname column in SQL databases.  The only exception to this is if the (host) IP address matches the (agent) IP address and snmptrapd is configured to resolve host names.  In that case, the host name of the (host) will be used for the (agent) host name as they are obviously the same host.

If the configuration setting dns_enable is set to 1 (dns enabled), then the host name of both the host and the AGENT will be resolved via DNS.  NODES entries will also be resolved to IP addresses before performing matches.

The host name may resolve to the Fully Qualified Domain Name (FQDN).  For example: barney.bedrock.com.  Adding an entry for the host in your /etc/hosts file or %systemroot%\system32\drivers\etc\hosts may result in the short name being used instead (barney).  You can also enable the strip_domain / strip_domain_list options to have SNMPTT strip the domain of any FQDN host.  See the snmptt.ini file for details.

To allow IP addresses to be resolved to host names, PTR records must exist in DNS or the local hosts file must contain all hosts.

It is recommended that either DNS be installed on the machine running SNMPTT / snmptrapd or a local hosts file be configured will all devices.  DNS should be configured as a secondary (authoritive) for the domains that it will receive traps from.  This will reduce network resolution traffic, speed up resolution, and remove the dependency of the network for DNS.  If a local DNS or hosts file is not used, then the entire network management station could become useless during a DNS / remote network outage and could cause false alarms for network management software.


Sample1 SNMPTT.CONF file

Note: The examples folder also contains a sample snmptt.conf file.

Following is a sample of two defined traps in snmptt.conf:

#
EVENT COMPAQ_11003 .1.3.6.1.4.1.232.0.11003 "LOGONLY" Normal
FORMAT Compaq Generic Trap: $*
EXEC qpage -f TRAP notifygroup1 "Compaq Generic Trap: $*"
NODES /etc/snmp/cpqnodes
SDESC
Generic test trap
EDESC
#
#
EVENT cpqDa3AccelBatteryFailed .1.3.6.1.4.1.232.0.3014 "Error Events" Critical
FORMAT Battery status is $3.
EXEC qpage -f TRAP notifygroup1 "$s $r $x $X: Battery status is $3"
NODES ntserver1 ntserver2 ntserver3
#
#

Sample2 SNMPTT.CONF file

Following is a sample of a list of files to load in snmptt.ini:

snmptt_conf_files = <<END
/etc/snmp/snmp-compaq.conf
/etc/snmp/snmp-compaq-hsv.conf
END
Following is a sample of one defined traps in /etc/snmp/snmptt-compaq.conf:
#
EVENT COMPAQ_11003 .1.3.6.1.4.1.232.0.11003 "LOGONLY" Normal
FORMAT Compaq Generic Trap: $*
EXEC qpage -f TRAP notifygroup1 "Compaq Generic Trap: $*"
NODES /etc/snmp/cpqnodes
SDESC
Generic test trap
EDESC
#
Following is a sample of one defined traps in /etc/snmp/snmptt-compaq-hsv.conf:
#
EVENT mngmtAgentTrap-16025 .1.3.6.1.4.1.232.0.136016025 "Status Events" Normal
FORMAT Host $1 : SCellName-TimeDate $2 : EventCode $3 : Description $4
EXEC qpage -f TRAP notifygroup1 "Host $1 : SCellName-TimeDate $2 : EventCode $3 : Description $4"
SDESC
"Ema EMU Internal State Machine Error [status:10]"
EDESC
#

Notes

An existing HP Openview trapd.conf can be used in most cases but the file must be a VERSION 3 file.  SNMPTT does not support all the variables implemented in HPOV, but most are available.  The following variables may or may not match exactly to HPOV: $O, $o, $r, $ar, $R, $aR.

Some vendors (such as Compaq and Cisco ) provide a file that can be imported in to HP Openview using an HP Openview utility.  Snmpttconvert can be used to convert the file to snmptt.conf format.

Some vendors provide a MIB file that contains TRAP or NOTIFICATION definitions.  Snmpttconvertmib can be used to convert the file to snmptt.conf format.
 

Limitations

Standalone mode only:

With a 450 Mhz PIII and a 9000 line snmptt.conf containing 566 unique traps (EVENTs), it takes under a second to process the trap including logging and executing the qpage program.  The larger the snmptt.conf file is, the longer it will take to process.  If there are a large number of traps being received, daemon mode should be used.  If it takes 1 second to process one trap, then obviously you shouldn't try to process more than one trap per second.

Note: Enabling the UCD-SNMP / Net-SNMP Perl module will greatly increase the startup time of SNMPTT.  Daemon mode is recommended.

Standalone or daemon mode:

The SNMPTRAPD program blocks when executing traphandle commands.  This means that if the program called never quits, SNMPTRAPD will wait forever.  If a trap is received while the traphandler is running, it is buffered and will be processed when the traphandler finishes.  I do not know how large this buffer is.

The program called by SNMPTT (EXEC) blocks SNMPTT.  If you call a program that does not return, SNMPTT will be left waiting.  In standalone mode, this would cause snmptrapd to wait forever also.
 

Feedback & Bugs

Please send me any comments - good or bad - to alex_b@users.sourceforge.net.  If you have any problems including converting trap files, please send me an email and include the file you are trying to convert and I will try to take a look at it.

Please also send any bug reports, patches or improvements so I can fix / add them and add it to the next release.  You can also use Sourceforge for bugs and feature requests.
 

Integration with other software

Nagios / Netsaint

Overview

Nagios / Netsaint is a system monitoring application. It monitors hosts and services and alerts you when things go wrong.  The name changed from Netsaint to Nagios in July of 2002.

This section will outline the basic steps to integrate SNMPTT with Nagios.  It will not attempt to explain how Nagios works.  There is very good documentation available on the Nagios web page.  You should be able to install and configuration Nagios before attempting to integrate it with SNMPTT.  You should also have a functioning SNMPTT system that can at least log translated traps to a log file.


Nagios Passive Service Checks

Passive service checks allow Nagios to process service check results that are submitted by external applications.  Using SNMPTT's EXEC statement, the received trap can be passed to Nagios using the submit_check_result script included with Nagios.  Once received by Nagios, the trap can be logged, a page sent, email sent etc. 

One service is defined for each Nagios host that is to receive traps from SNMPTT.  The benefits of using only one service entry is that it is makes it easier to set up Nagios. Trying to define every possible trap for every host you have is not recommended.  For example, after converting the MIBS from Compaq, there are over 340 traps defined.  Trying to define this for every Compaq server would not be a good idea as 40 servers * 340 traps = 13,600 service definitions.

The downside of using only one service entry is that you will only see the last trap that was recieved on the Nagios console.  Each received trap will be logged, emailed, paged etc but the console will only show the last one as being in the warning or critical state.  The service will remain in this state until you manually force a service check unless you have freshness checking enabled (Nagios 2.0 and higher).  See Clearing received traps in Nagios below.


Nagios Volatile Services

When defining the service for receiving the SNMPTT translated trap, the service must be defined as volatile.  When a service is changed from an OK state to a non-OK state, contacts are notified etc.  Normally, a service is Nagios is NOT defined volatile which means if another service check is performed and the state is STILL non-OK then NO contacts are notified.  Because there is only one service entry for the SNMP traps, we need to make sure we are contacted every time a trap comes in.


Creating the Nagios service entry

Following is a sample service entry for Nagios.  The Description column should not be included in the definition.

define service{ Description

host_name server01 Name of host

service_description TRAP Name of service.  What you use here must match the same value for the submit_check_result script

is_volatile 1 Enables volatile services

check_command check-host-alive Used to reset the status to OK when 'Schedule an immediate check of this service' is selected.

max_check_attempts 1
 Leave as 1.

normal_check_interval 1
 Leave as 1.

retry_check_interval 1
 Leave as 1.

active_checks_enabled 0 Prevent active checks from occuring as we are only using passive checks.

passive_checks_enabled 1 Enables passive checks

check_period 24x7 Required for freshness checking.

notification_interval 31536000 Notification interval.  Set to a very high number to prevent you from getting pages of previously received traps (1 year - restart Nagios at least once a year! - do not set to 0!).

notification_period 24x7 When you can be notified.  Can be changed

notification_options w,u,c Notify on warning, unknown and critical.  Recovery is not enabled so we do not get notified when a trap is cleared.

notifications_enabled 1
 Enable notifications

contact_groups cg_core Name of contact group to notify
    }

Note:  Previous versions of this documentation defined a check_period of none, and did not set active_checks_enabled to 0.  As of SNMPTT 1.2, setting active_checks_enabled to 0 instead of setting check_periodto none is recommened as freshness checks require it.  The recovery notification option has also been removed so we do not get notified when a trap is cleared.

Following is a sample service entry for Netsaint.  Netsaint does not support active_checks_enabled, so a check period of none is used.

service[server01]=TRAP;1;none;1;1;1;cg_core;31536000;24x7;0;1;1;;check-host-alive

See the Netsaint documentation and the Nagios table above for an explanation of the various fields.


Creating the SNMPTT EXEC statement


The Nagios distribution should contain the script submit_check_result in the contrib/eventhandlers directory.  Create a directory called eventhandlers under libexec (/usr/local/netsaint/libexec) and copy the submit_check_result script to that directory.  Make sure the script is executable (chmod +x submit_check_result).

The submit_check_result script expects the following arguments:

host_name
svc_description
return_code
plugin_output

The possible return codes are: 0=OK, 1=WARNING, 2=CRITICAL, -1=UNKNOWN.  See the top of the submit_check_result script for a detailed description of each argument.

Create an EXEC statement such as the following for each EVENT entry in your snmptt.conf file:

EXEC /usr/local/nagios/libexec/eventhandlers/submit_check_result $r TRAP 1 "xxxxxx"

where "xxxxxx" is the text for the trap using the same format as the FORMAT statement.  For example:

EXEC /usr/local/nagios/libexec/eventhandlers/submit_check_result $r TRAP 1 "Drive $1 in bay $2 has failed"

The variable substitution $r is used to pass the host name, TRAP matches the service definition defined above, 1 represents a WARNING, and "xxxxxx" is the translated message from SNMPTT.

You must make sure that the host definition in Nagios matches the hostname that will be passed from SNMPTT using the $r variable.  See the section 'Name Resolution / DNS' for important DNS information.


Clearing received traps in Nagios

Using the above configuration, once a trap is received for a host, it will remain in the WARNING state.  To clear the trap from the Nagios console, open the TRAP service and click 'Schedule an immediate check of this service'.  This will cause the defined service check to be run (check-host-alive in the example above) which will then change the status code to OK and clear the warning after a minute or so, assuming of course the system responds OK to the check-host-alive check.  An alternative to using check-host-alive is to create a new command called reset-trap with:

#!/bin/sh
/bin/echo "OK: No recent traps received"
exit 0

Be sure to create a command definition in your *commands.cfg file.  See the 'Object configuration file options' section of the Nagios documentation.

Nagios 2.0 introduced service and host result freshness checks.  Service freshness checks can be used to automatically reset the trap notification to an OK state by defining check_freshness and freshness_threshold in the service definition.  Using freshness checks is recommended over normal active checks (defined by normal_check_interval) because the next check time of a normal active check does not change when a service changes state.  Because of this, if you wanted to clear the trap after 24 hours, the last trap would be cleared some time between when it happened at 24 hours, depending on when the last active check was done.  With freshness checking, the check command will be run freshness_threshold seconds after the last passive result was received.

For freshness checking to work, normal_check_interval must be set to 1, valid check_period should be set to 24x7 and the following service definitions should be added.  The third column should not be included in the definition.
check_freshness 1 Enable freshness checking
freshness_threshold 86400 Reset trap alert every 24 hours.


SNMP heartbeat monitoring

If you have an application that sends periodic SNMP heartbeats, it is possible to use freshness checking to alert if a heartbeat has not been received.

To configure a heartbeat trap, start by creating a new service definition by following 'Creating the Nagios service entry' above, but use a new service_description such as MyApp_heartbeat.  Next, add / change the following service definitions.  The third column should not be included in the definition.

check_freshness 1 Enable freshness checking
freshness_threshold 1200 Check freshness every 20 minutes.
check_command myapp_heartbeat_alarm_set Command to execute when a heartbeat is not received within freshness_threshold seconds.
notification_options w,u,c,r Notify on warning, unknown critical and recovery.


Note:  For freshness checking to work, normal_check_interval must be set to 1, and valid check_period should be set to 24x7.

In this example, it is assumed that the heartbeat trap is received every 15 minutes, so a freshness_threshold of 20 minutes was selected in case the heartbeat was delayed.

Create the new myapp_heartbeat_alarm_set command for Nagios:

#!/bin/sh
/bin/echo "CRITICAL: Heartbeat signal from MyApp was not received!"
exit 2

Be sure to create a command definition in your *commands.cfg file.  See the 'Object configuration file options' section of the Nagios documentation.

Next, add an EXEC statement to the snmptt.conf file for the trap definition:

EXEC /usr/local/nagios/libexec/eventhandlers/submit_check_result $r MyApp_heartbeat 1 "Heartbeat signal from MyApp received."

As long as the traps are received, the MyApp_heartbeat service will have an OK status.  If the heartbeat is not received, the freshness command will be executed which will set the status to CRITICAL.


SEC - Simple Event Correlator

Overview

Simple Event Correlator (SEC) is a free and platform independent event correlation tool.

This section will outline the basic steps to integrate SNMPTT with SEC.  It will not attempt to explain how SEC works.  There is very good documentation available on the SECs web page and a good introduction to SEC can be found here.  You should be able to install and configuration SEC before attempting to integrate it with SNMPTT.  You should also have a functioning SNMPTT system that can at least log translated traps to a log file.

This section outlines one method of integrating SEC with SNMPTT.  Another method is documented in the March edition of Sys Admin Magazine in an article written by Francois Meehan.

Here are a couple of examples of why you would want to integrate SNMPTT with SEC: 
  1. You have a 'noisy' device that constantly sends the same trap over and over again.  It would be possible to simply disable the trap in SNMPTT, but you want the trap to be logged, just not excessively.  The SEC 'SingleWithSupress' could be used to reduce the number of traps logged.
  2. Router interfaces often go up and down and you are receiving a trap for each event.  You do not want to be alerted every time the interface 'bounces', but you do want to be alerted if it happens many times over a set period of time.  You want to be alerted when the interface is down for more than 10 seconds, and then when the interface comes back up.

The following outlines how the flow of traps between SNMPTT and SEC could take place:

  1. SNMPTT receives a trap.
  2. SNMPTT logs the trap to a separate log file such as /var/log/snmptt/snmptt.sec.log using '/bin/echo ...' for the EXEC statement.  No FORMAT line is defined so the trap is not logged to the regular snmptt.log log file (or SQL table if a SQL server is used).
  3. SEC monitors the log file for new entries.
  4. SEC correlates the messages from the log file.
  5. When a new alert needs to be generated by SEC based on its rules, SEC will call an external script which will feed the information back into SNMPTT as a trap using a user defined unique trap OID.  The unique trap OID is defined in a custom snmptt.conf file (such as /etc/snmp/snmptt.conf.sec).
  6. SNMPTT will process the new trap as it would any other trap by logging to snmptt.log, a SQL table etc.

Configuration Overview

The following outlines how example 2 from above could be handled using SEC.  This is a slightly modified version of the example from the SEC Examples page.

The example provides the following:

  • Prevents interface flapping from flooding the log files
  • Provides an 'unstable' and 'stable' alert based on how often the interface bounces.

The following steps need to be completed:

  1. Modify the Cisco snmptt.conf file to output linkDown and linkUp messages to a separate log file.
  2. Create a new snmptt.conf file to handle incoming alerts from SEC
  3. Create a SEC configuration file to correlate the linkDown / linkUp messages and pass new alerts to a script
  4. Create a script that will feed the messages from SEC back in to SNMPTT
  5. Test

1. Modify the Cisco SNMPTT.CONF file

The existing SNMPTT.CONF file needs to be modified to output the linkDown and linkUp messages to a separate log file for processing by SEC.

Following is an example snmptt.conf.cisco file modified to log a linkdown or linkup message to /var/log/snmptt/snmptt.sec.log.  As you can see there are no FORMAT lines so the trap will not be logged to the regular SNMPTT log system.

EVENT Cisco_Link_Down .1.3.6.1.6.3.1.1.5.3.1.3.6.1.4.1.9 "Cisco Events" Minor
EXEC /bin/echo "node=$A msg_text=cisco linkdown trap on interface $1" >> /var/log/snmptt/snmptt.sec.log
SDESC
This event occurs when the Cisco agent
detects an interface has gone down.

A linkDown trap signifies that the sending
protocol entity recognizes a failure in one of
the communication links represented in the
agent's configuration.
EDESC
#
#
#
EVENT Cisco_Link_Up .1.3.6.1.6.3.1.1.5.4.1.3.6.1.4.1.9 "Cisco Events" Normal
EXEC /bin/echo "node=$A msg_text=cisco linkup trap on interface $1" >> /var/log/snmptt/snmptt.sec.log
SDESC
This event occurs when the Cisco agent
detects an interface has come back up.

A linkUp trap signifies that the sending
protocol entity recognizes that one of the
communication links represented in the agent's
configuration has come up.
EDESC
#
#
#

2. Create a new SNMPTT.CONF file for incoming SEC alerts

A new SNMPTT.CONF file needs to be created which will handle the incoming traps from SEC.

Following is an example snmptt.conf.sec file to accept incoming traps from SEC.  Use an enterprise OID that will not interferre with any other OIDs already configured on your system.  For example, .1.3.6.1.4.1.9999.

EVENT Cisco_Link_DownUp .1.3.6.1.4.1.9999.1 "Cisco Events" Normal
FORMAT $1
#
#
#
EVENT Cisco_Link_DownUp .1.3.6.1.4.1.9999.2 "Cisco Events" Major
FORMAT $1
#
#
#

3. Create a SEC configuration file

Following is a SEC configuration file that handles the even correlation for the Cisco traps.  This file is the same as the file available on the SEC Examples page except comments and file paths have been modified.

################################################################
#          Sample SEC ruleset for SNMPTT
################################################################

# process Cisco linkDown/linkUp trap events received from
# SNMPTT via log file

type=PairWithWindow
ptype=RegExp
pattern=node=(\S+).*msg_text=cisco linkdown trap on interface (\S+)
desc=CISCO $1 INTERFACE $2 DOWN
action=event %s;
continue2=TakeNext
ptype2=RegExp
pattern2=node=$1.*msg_text=cisco linkup trap on interface $2
desc2=CISCO %1 INTERFACE %2 BOUNCE
action2=event %s;
window=20

type=SingleWithSuppress
continue=TakeNext
ptype=RegExp
pattern=CISCO (\S+) INTERFACE (\S+) DOWN
desc=cisco $1 interface $2 down
action=reset +1 %s
window=60

type=Pair
ptype=RegExp
pattern=CISCO (\S+) INTERFACE (\S+) DOWN
desc=cisco $1 interface $2 down
action=shellcmd /home/snmptt/cisco_msg $1 $2 major down
ptype2=RegExp
pattern2=node=$1.*msg_text=cisco linkup trap on interface $2
desc2=cisco %1 interface %2 up
action2=shellcmd /home/snmptt/cisco_msg %1 %2 normal up
window=86400

type=SingleWith2Thresholds
ptype=RegExp
pattern=CISCO (\S+) INTERFACE (\S+) BOUNCE
desc=cisco $1 interface $2 is unstable
action=shellcmd /home/snmptt/cisco_msg $1 $2 major unstable
window=3600
thresh=10
desc2=cisco $1 interface $2 is stable again
action2=shellcmd /home/snmptt/cisco_msg $1 $2 normal stable
window2=10800
thresh2=0

Here is a quick breakdown of what each rule does:

First rule:
  • If a linkDown is received (node=x msg_text=cisco linkdowni trap on interface x from SNMPTT), and then a linkUp is received within 20 seconds, it is considered a BOUNCE.  A new 'event' is created with the internal SEC event 'CISCO %1 INTERFACE %2 BOUNCE' is created which is passed to the other rules. 
  • If a linkDown is received and a linkUp is not received within 20 seconds, a new 'down' internal SEC event is created (CISCO $1 INTERFACE $2 DOWN) which is passed to the other rules.
Second rule:
  • Allows only one 'CISCO x INTERFACE x DOWN' message to be processed over 60 seconds.
Third rule:
  • When a SEC internally generated 'CISCO $1 INTERFACE $2 DOWN' message is found, it passes the host name, interface number and 'major down' to the cisco_msg script.
  • When a SEC internally generated 'CISCO $1 INTERFACE $2 UP' message is found, it passes the host name, interface number and 'normal up' to the cisco_msg script.
Fourth rule:
  • If ten 'CISCO %1 INTERFACE %2 BOUNCE' messages are detected over the span of 1 hour, it passes the host name, interface number and 'major unstable' to the cisco_msg script.
  • <>If after the last unstable alert there are no 'CISCO %1 INTERFACE %2 BOUNCE' messages for 3 hours, it passes the host name, interface number and 'normal stable' to the cisco_msg script.

4. Create a script to pass a trap back to SNMPTT

Following is a Perl script that passes the information passed from SEC back to SNMPTT by calling SNMPTTHANDLER directly.  This file is basically a modified Perl version of the shell script available on the SEC Examples page.

#!/usr/bin/perl
#
# the cisco_msg script:
#
use Socket;

$node = shift(@ARGV);
$interface = shift(@ARGV);
$severity = shift(@ARGV);
$text  = shift(@ARGV);

$temp_ipaddr = gethostbyname($node);
if (defined($temp_ipaddr)) {
  $ipaddr = Socket::inet_ntoa(scalar($temp_ipaddr));
}
else {
  $ipaddr = "0.0.0.0";
}

# use snmpget utility from Net-SNMP package
$ifname=`/usr/bin/snmpget -c public -OQv $NODE .1.3.6.1.2.1.2.2.1.2.$IF`
$description=`/usr/bin/snmpget -c public -OQv $NODE .1.3.6.1.4.1.9.2.2.1.1.28.$IF`

$message="Interface $ifname ($description) $text";
$message=~s/\"/\'/g;

open (TRAP, "|/usr/sbin/snmptthandler");

select TRAP;

print "$node\n";
print "$ipaddr\n";
print ".1.3.6.1.2.1.1.3.0 00:00:00:00.00\n";
if ($severity=~/normal/i) {
  print ".1.3.6.1.6.3.1.1.4.1.0 .1.3.6.1.4.1.9999.1\n";
}
else {
  print ".1.3.6.1.6.3.1.1.4.1.0 .1.3.6.1.4.1.9999.2\n";
}
print ".1.3.6.1.4.1.9999.1.1 $message\n";
print ".1.3.6.1.6.3.18.1.3.0 $ipaddr\n";
print ".1.3.6.1.6.3.18.1.4.0 public\n";
print ".1.3.6.1.6.3.1.1.4.3.0 .1.3.6.1.4.1.9999\n";

close TRAP;

Windows Event Log forwarding

Overview

The Windows utility Event to Trap Translator (evntwin.exe andevntcmd.exe) can be used to configure Windows to forward user selectable Event Log entries to an SNMP manager when using the Microsoft SNMP service. SNMPTT can be configured to process these traps like any other trap. If the Event to Trap Translator is not already installed on your machine, it should be available from the Microsoft Resource Kit, SMS or after installation of the Microsoft SNMP service (Windows 2000 AS and Windows XP or higher).

This section will outline the basic steps to configure Windows to forward event log entries to Net-SNMP / SNMPTT when using the Microsoft SNMP server (not the Net-SNMP snmpd.exe agent).  It will not attempt to explain how evntwin.exe and evntcmd.exe function.  Documentation on using evntwin.exe and evntcmd.exe is available on the Microsoft web site and should be reviewed. You should have a functioning SNMPTT system that can at least log translated traps to a log file before attempting this.

SNMP Service

The Windows SNMP Service is the Microsoft SNMP agent. The agent is responsible for handling SNMP requests from management stations such as queries for CPU utilization, disk space etc. The agent is also responsible for sending traps to management stations when an event occurs.

Note: The Microsoft SNMP Trap Service is used to RECEIVE SNMP traps which is similar to the Net-SNMP snmptrapd.exe daemon. The Microsoft SNMP Trap Service is NOT used to send traps and is not required.

Configuring the trap destination

The Windows SNMP agent needs to be configured to forward traps to your Net-SNMP / SNMPTT management station. This is done using the following steps:

  • Click Start - Settings - Control Panel
  • Open Administrative Tools
  • Open Services
  • Open Local Policies
  • Open SNMP Service
  • Click the Traps tab
  • Enter a community name and click Add to List
  • Click Add and enter the IP address of the management station
  • Click Apply
  • Click OK
  • Right-click on SNMP Service and select Restart

After the service is restarted, a coldStart trap will be sent to the management station. If SNMPTT has been configured to translate coldStart messages, you should see a log entry similar to the following:

Thu Sep 9 21:33:06 2004 .1.3.6.1.6.3.1.1.5.1 Normal "Status Events" server1 - Device reinitialized (coldStart)

Note:If the SNMP Service is not listed in the Services Control Panel, then it needs to be installed using Add/Remove Programs. Under Add/Remove Windows Components, select Management and Monitoring Tools and then Simple Network Management Protocol.

Configuring the Event to Trap Translator

The following steps explain how to configure the Event to Trap Translator to forward system logon failures to SNMPTT:

  • Launch evntwin.exe
  • For Configuration Type select Custom
  • Click the Edit button
  • Inside Event Sources, expand Security and then click Security
  • Locate Event ID 529 (Logon Failure:%n%tReason:%t%tUnknown username or bad password%n.)
  • Click Add
  • Click OK
  • Click Apply

The SNMP agent should now forward all logon failures to the SNMP management station. A restart of the SNMP service should not be necessary.

Configuring SNMPTT to accept the Microsoft traps

An SNMPTT.CONF file needs to be created to handle the Microsoft traps. As documented in Microsoft knowledge base article 318464, all Microsoft traps start with .1.3.6.1.4.1.311.1.13.1. For simplicity, a single SNMPTT.CONF EVENT entry will be used with a wildcard to accept all Microsoft traps. Following is an example snmptt.conf.microsoft file which needs to be included in the list of .conf files in the TrapFiles section in snmptt.ini:

EVENT EventLog .1.3.6.1.4.1.311.1.13.1.* "Regular" Normal

FORMAT EventLog entry: $1

The first enterprise variable ($1) contains the complete text that is displayed in the Event Log Description box. Variables are described in more detail in the Advanced Section.

After creating the snmptt.conf.microsoft file and adding it to the snmptt.ini, restart snmptt.

Testing

To test that the trap is received by SNMPTT, a logon failure in Windows should be created.

Your default installation of Windows may not create Event Log entries for unsuccessful logins. To configure Windows to log all failed logins, follow these steps:

  • Click Start - Settings - Control - Panel
  • Open Administrative Tools
  • Open Local Security Policy
  • Open Local Policies
  • Open Audit Policy
  • Enable auditing of failures for Audit account logon events
  • Enable auditing of failures for Audit logon events

The settings should take effect immediately, and a reboot should not be required.

To generate an event log entry, you can either log off and try to log on to the system with an invalid username and password, or use the runas.exe command from a command prompt. For example:

  • runas /user:fakeuser cmd

When prompted for a password, press Enter.

SNMPTT should log something similar to the following:

Thu Sep 9 21:05:40 2004 .1.3.6.1.4.1.311.1.13.1.8.83.101.99.117.114.105.116.121.0.529 Normal "Regular" server1 - Event Log entry: Logon Failure:.....Reason:..Unknown user name or bad password.....User Name:.fakeuser.....Domain:.......Logon Type:.joint-iso-ccitt.....Logon Process:.seclogon.....Authentication Package:.Negotiate.....Workstation Name:.SERVER1.

The text in the log entry should match the text in the Description field of the Event Log entry but without the formatting.

Advanced Configuration

Specific EVENTs

Instead of using a wildcard EVENT entry to match all Microsoft traps, it is possible to create EVENT entries for each trap. As SNMPTT will only match using wildcard entries if there is no exact EVENT match, it may be desirable to create EVENT entries for a select number of important events, and keep the wildcard to catch any others.

To determine the trap OID that will be used for the EVENT, display the entry in evntwin.exe and combine the Enterprise OID, a 0 and the Trap Specific ID. For example, for the security event ID 529 used above:

Enterprise OID: 1.3.6.1.4.1.311.1.13.1.8.83.101.99.117.114.105.116.121

Trap Specific ID: 529

Based on the information above, the following EVENT line would be used::

EVENT EventLog 1.3.6.1.4.1.311.1.13.1.8.83.101.99.117.114.105.116.121.0.529 "Regular" Normal

Enterprise variables

Each trap sent from the Event to Trap Translator contains the text displayed in the Description, User and Computer fields for the Event Log. Also passed are the individual variables which are used by the Windows SNMP Service to create the Description field in the Event Log.

The following lists the enterprise variables that can be used in SNMPTT for each trap:

  • $1:Event Log Description
  • $2:Event Log User
  • $3:Event Log Computer
  • $4:?
  • $5:?
  • $6:Event to Trap Translator variable %1
  • $7:Event to Trap Translator variable %2
  • $8:Event to Trap Translator variable %3
  • $9:Event to Trap Translator variable %4
  • $n:Event to Trap Translator variable %n-5

As the individual variables are passed in the trap, it is possible to recreate the FORMAT line instead of using the passed Description ($1) field. For example, $1 in the previous example contains:

Logon Failure:.....Reason:..Unknown user name or bad password.....User Name:.fakeuser.....Domain:.......Logon Type:.joint-iso-ccitt.....Logon Process:.seclogon.....Authentication Package:.Negotiate.....Workstation Name:.SERVER1.

By reviewing the Description field as defined in the evntwin.exe utility, a new cleaned up FORMAT line can be used that does not contain all the dots.

Following is the text from the Description field in evntwin.exe which will be used as a reference. Notice the use of %n variables which are equivalent to the SNMPTT $n variables +5 (%1 = SNMPTT's $6). Note: In the example below, %n is a newline and %t is a tab while %n is a variable number.

Logon Failure:%n %tReason:%t%tUnknown user name or bad password%n %tUser Name:%t%1%n %tDomain:%t%t%2%n %tLogon Type:%t%3%n %tLogon Process:%t%4%n %tAuthentication Package:%t%5%n %tWorkstation Name:%t%6

The EVENT entry could be cleaned up using:

EVENT EventLog 1.3.6.1.4.1.311.1.13.1.8.83.101.99.117.114.105.116.121.0.529 "Regular" Normal
FORMAT Logon Failure: Reason: Unknown user name or bad password. User Name: $6, Domain: $7, Logon Type: $8, Logon Process: $9, Auth package: $10, Workstation name: $11

Hobbit

Information on handling SNMP traps with Hobbit can be found at http://cerebro.victoriacollege.edu/hobbit-trap.html.
snmptt_1.4/docs/snmpttconvertmib.html0000664000000000000000000003127212236567454016744 0ustar rootroot SNMP Trap Translator

SNMP Trap Translator Convert MIB v1.4

(SNMPTTCONVERTMIB)
This file was last updated on:  November 5th, 2005

License

Copyright 2002-2013 Alex Burger
alex_b@users.sourceforge.net
4/3/2002

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA  

SNMPTTCONVERTMIB

SNMPTTCONVERTMIB is a Perl script which will read a MIB file and convert the TRAP-TYPE (v1) or NOTIFICATION-TYPE (v2) definitions into a configuration file readable by SNMPTT.

For example, if the file CPQHOST.mib (v1) contained:

CPQHOST-MIB DEFINITIONS ::= BEGIN

    IMPORTS
        enterprises             FROM RFC1155-SMI
.
.
. (lines removed)
.
.
    cpqHo2NicSwitchoverOccurred2 TRAP-TYPE
        ENTERPRISE compaq
        VARIABLES { sysName, cpqHoTrapFlags, cpqHoIfPhysMapSlot,
                    cpqHoIfPhysMapPort, cpqHoIfPhysMapSlot,
                    cpqHoIfPhysMapPort }
        DESCRIPTION
            "This trap will be sent any time the configured redundant NIC
            becomes the active NIC."

             --#TYPE "Status Trap"
             --#SUMMARY "NIC switchover to slot %s, port %s from slot %s, port %s."
             --#ARGUMENTS {2, 3, 4, 5}
             --#SEVERITY MAJOR
             --#TIMEINDEX 99
        ::= 11010
 

Executing snmpttconvertmib CPQHOST.mib snmptt.conf would APPEND to the end of the snmptt.conf file (specified on the command line):
#
#
#
EVENT cpqHo2NicSwitchoverOccurred2 .1.3.6.1.4.1.232.0.11010 "Status Events" Normal
FORMAT Status Trap: NIC switchover to slot $3, port $4 from slot $5, port $6.
#EXEC qpage -f TRAP notifygroup1 "Status Trap: NIC switchover to slot $3, port $4 from slot $5, port $6."
SDESC
This trap will be sent any time the configured redundant NIC
becomes the active NIC.
EDESC


Notes:

To specifiy an EXEC statement, use the --exec= command line option.  

To prevent the --#TYPE text from being prepended to the --#SUMMARY line, change $prepend_type to 0 in the SNMPTTCONVERTMIB script.

See the help screen for more options (snmpttconvertmib --h).

Requirements

Snmpttconvertmib converts a MIB file using the snmptranslate utility. 

If the Net-SNMP Perl module is enabled using --net_snmp_perl on the command line, it can provide more detailed variable descriptions in the DESC sestion if available such as:

For example:

2: globalStatus
   Syntax="INTEGER"
      2: ok
      4: failure
   Descr="Current status of the entire library system"


Converting a MIB file

See the snmpttconvertmib help screen for all possible command line options (snmpttconvertmib --h) before converting a MIB file.  Depending on what type of information is available in the MIB file, you may want to change how the FORMAT / EXEC lines are generated.

Before trying to convert  MIB file, you should ensure that the MIB file can be parsed by Net-SNMP

  1. Copy the MIB file to the UCD-SNMP / Net-SNMP mibs folder
  2. Type: export MIBS=ALL to ensure all the mibs will be read in by snmptranslate
  3. Make sure the MIB file can be interpreted by snmptranslate correctly.  Simply typing snmptranslate should tell you if it was able to read the mib file correctly.  If it can't, an error will be produced at the top of the help screen.
  4. Try to translate a TRAP-TYPE or NOTIFICATION-TYPE entry contained inside the MIB file.  For example, if the MIB file contains the Notification definition of 'rptrHealth NOTIFICATION-TYPE', then type:  snmptranslate rptrHealth -IR -Td.  If you get 'Unknown object identifier: xxx' then the MIB file was not found or parsed correctly.

Running snmpttconvertmib:
 

  1. Make sure the MIB file has been successfully installed (see above)
  2. Edit the options between OPTIONS START and OPTIONS END in snmpttconvertmib if needed
  3. If you are using UCD-SNMP, or Net-SNMP v5.0.1, then add the folllowing to your snmp.conf file: printNumericOids 1 (note:  this will affect all snmp commands).  This ensures the OIDs are returned in numerical format.  Other versions of Net-SNMP do not require this change, as snmpttconvertmib will use a command line switch to force it on when calling snmptranslate.
  4. Convert the mib file with: snmpttconvertmib --in=path-to-mib --out=output-file-name.  Note:  the output-file-name is appended to, so remember to delete it first if needed.
Example:
snmpttconvertmib --in=/usr/share/snmp/mibs/CPQHOST.mib --out=/etc/snmp/snmptt.conf.compaqhost
If the Net-SNMP Perl module is installed and you want more descriptive variable descriptions, add --net_snmp_perl to the command line:
snmpttconvertmib --in=/usr/share/snmp/mibs/CPQHOST.mib --out=/etc/snmp/snmptt.cong.compaq --net_snmp_perl

To convert all the CPQ* files in the current folder, you can use:

Unix / Linux:
for i in CPQ*
> do
> /usr/local/sbin/snmpttconvertmib --in=$i --out=snmptt.conf.compaq
> done

Windows:
for %i in (CPQ*) do perl snmpttconvertmib --in=%i --out=snmptt.conf.compaq

How it works

 
Some MIB files contain --#SUMMARY and --#ARGUMENTS lines which are used by Novell's Network Management system.  These MIB files convert very well to SNMPTT as they contain detailed information that can be used on the FORMAT and EXEC lines.  Compaq's MIBs usually have these lines.

Other MIBS contain only a DESCRIPTION section where the first line contains the FORMAT string.  In some MIBS, this line also contains variables similar to the --#SUMMARY lines.

The mib file is searched for the name of the MIB file.  This should be at the top of the file and contain 'name DEFINITIONS ::=BEGIN'.  This name will be used when looking up the TRAP / NOTIFICATION to ensure the correct MIB file is accessed.

The mib file is also searched for lines containing TRAP-TYPE or NOTIFICATION-TYPE.  If it finds one that appears to be a valid trap definition, it reads in the following lines until a ::= is found while looking for the DESCRIPTION section.  It then looks for the --#SUMMARY and --#ARGUMENTS line if enabled.

SNMPTRANSLATE is used with the following syntax to find the OID of the trap:

snmptranslate -IR -Ts mib-name::trapname -m mib-filename

Note: If  Net-SNMP 5.0.2 or newer is detected, the command line also includes the -On switch.  See the FAQ.

* If --#SUMMARY and --#ARGUMENTS are found, the %letter variables are replaced with $number variables based on the values lists in the --#ARGUMENTS section incremented by 1 (ARGUMENTS starts with 0, SNMPTT starts with 1).  This will be used to define the FORMAT and EXEC lines.

* If there is no --#SUMMARY and --#ARGUMENTS lines, but the first line of the DESCRIPTION contains %letter variables, then that line will be used to define the FORMAT and EXEC lines.  The %letter variables are replaced with $number variables starting at 1 and going up.

* If there is no --#SUMMARY and --#ARGUMENTS lines, and the first line of the DESCRIPTION does not contain %letter variables, then that line will be sed to define the FORMAT and EXEC lines followed by a $* which will dump all received variables.

* If the entry contains variables, the variables are listed in the DESC section.   If --net_snmp_perl is specified, the syntax, description and enums for each variable is used.

* Note:  This can be changed by specifying a --format=n command line option.  See the snmpttconvertmib help screen for all possible command line options (snmpttconvertmib --h).


snmptt_1.4/docs/snmpttconvert.html0000664000000000000000000000562412236567454016256 0ustar rootroot SNMP Trap Translator

SNMP Trap Translator Convert v1.4

(SNMPTTCONVERT)
This file was last updated on:  August 30th, 2004

License

Copyright 2002-2013 Alex Burger
alex_b@users.sourceforge.net
4/3/2002

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 

SNMPTTCONVERT

Some vendors provide a file that can be imported into HP Openview using a HP Openview utiltity.  SNMPTTCONVERT is a simple Perl script which will convert one of these files into the format used by SNMPTT.  The file can contain multiple traps.

For example, if the file ciscotrap.txt contained:

rpsFailed {.1.3.6.1.4.1.437.1.1.3} 6 5 - "Status Events" 1
Trap received from enterprise $E with $# arguments: sysName=$1
SDESC
"A redundant power source is connected to the switch but a failure exists in
the power system."
EDESC
Executing snmpttconvert ciscotrap.txt would output:
#
#
#
EVENT rpsFailed .1.3.6.1.4.1.437.1.1.3.0.5 "Status Events" Normal
FORMAT Trap received from enterprise $E with $# arguments: sysName=$1
#EXEC qpage -f TRAP notifygroup1 "Trap received from enterprise $E with $# arguments: sysName=$1"
SDESC
"A redundant power source is connected to the switch but a failure exists in
the power system."
EDESC


Note:  The #EXEC line is added by default.  This can be changed by editing the SNMPTTCONVERT script.
 

snmptt_1.4/docs/index.html0000664000000000000000000000254507751027414014427 0ustar rootroot SNMPTT
SNMPTT Documentation

SNMPTTCONVERT Documentation

SNMPTTCONVERTMIB Documentation

SNMPTT Frequently Asked Questions
snmptt_1.4/sample-trap-daemon0000664000000000000000000000061310110174450015067 0ustar rootroot1092665195 server01.domain.com 192.168.1.1 .1.3.6.1.2.1.1.3.0 111:21:48:19.07 .1.3.6.1.6.3.1.1.4.1.0 .1.3.6.1.4.1.232.0.11003 .1.3.6.1.2.1.1.5.0 SERVER01 .1.3.6.1.4.1.232.11.2.11.1.0 0 .1.3.6.1.4.1.232.11.2.8.1.0 "Compaq Management Agents Test Trap sent - Friday, August 16, 2002 2:05:15 PM" .1.3.6.1.6.3.18.1.3.0 192.168.1.1 .1.3.6.1.6.3.18.1.4.0 public .1.3.6.1.6.3.1.1.4.3.0 .1.3.6.1.4.1.232 snmptt_1.4/sample-unknown-trap0000664000000000000000000000050110110174451015320 0ustar rootrootserver01.domain.com 192.168.1.1 .1.3.6.1.2.1.1.3.0 111:21:48:19.07 .1.3.6.1.6.3.1.1.4.1.0 .1.3.6.1.0.0.0.0.0 .1.3.6.1.2.1.1.5.0 SERVER01 .1.3.6.1.4.1.232.11.2.11.1.0 0 .1.3.6.1.4.1.232.11.2.8.1.0 "Sample Unknown Trap" .1.3.6.1.6.3.18.1.3.0 192.168.1.1 .1.3.6.1.6.3.18.1.4.0 public .1.3.6.1.6.3.1.1.4.3.0 .1.3.6.1.4.1.232 snmptt_1.4/snmptthandler-embedded0000664000000000000000000002201312236567454016036 0ustar rootroot#!/usr/bin/perl # # SNMPTTHANDLER-EMBEDDED v1.4 # # Copyright 2009-2013 Alex Burger # alex_b@users.sourceforge.net # 5/17/2009 # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################## # # http://www.sourceforge.net/projects/snmptt # # This script is an embedded snmptrapd trap handler for use with the NET-SNMP # / UCD-SNMP and SNMPTT. ** It can only be run directly from snmptrapd. ** # # The script is called by defining a perl handler snmptrapd.conf. # For example: # # perl do "/sbin/snmptthandler-embedded"; # # SNMPTTHANDLER-EMBEDDED dumps the received traps into a directory to be # processed by the SNMPTT daemon. # ############################################################################## use strict; use Getopt::Long; use Time::HiRes qw(gettimeofday); use Config::IniFiles; my $debug = ''; # Override debug level setting in snmptt.ini # Set to '' to use the snmptt.ini setting or set to 1 to enable. my $ini = ''; # Override snmptt.ini file location. # Set to '' to use the default locations of /etc/snmp/snmptt.ini # and /etc/snmptt.ini for Unix and %SYSTEMROOT%\snmptt.ini for # Windows. ############################################################################## # Don't modify anything below this line # my $DEBUGGING; my $DEBUGGING_FILE; my $configfile; my $spool_directory; if ($debug >= 1) { $DEBUGGING = 1; } &loadsnmpttini; # Load snmptt.ini ############################################################################## # Register the trap receiver NetSNMP::TrapReceiver::register("all", \&snmptt_trap_receiver) || warn "failed to register our perl trap handler\n"; print STDERR "Loaded the SNMPTT embedded snmptrapd handler\n"; ############################################################################## # Trap receiver. sub snmptt_trap_receiver { my $pdu_info = $_[0]; my $varbinds = $_[1]; my $hostname = $$pdu_info{"receivedfrom"} || "unknown"; if ($hostname ne "unknown") { $hostname =~ /\[(.*?)\].*/; # UDP: [127.0.0.1]:41070->[127.0.0.1] $hostname = $1 || "unknown"; } my $ip_address = $hostname; my $community = $$pdu_info{"community"} || "unknown"; # contextEngineID in hash = snmpCommunityContextEngineID = .1.3.6.1.6.3.18.1.1.1.4 my $contextEngineID = $$pdu_info{"contextEngineID"} || "unknown"; $contextEngineID = unpack('h*', $contextEngineID); # contextName in hash = snmpCommunityContextName = .1.3.6.1.6.3.18.1.1.1.5 my $contextName = $$pdu_info{"contextName"} || "unknown"; # snmplib/snmp_api.c: # static oid snmpEngineIDoid[] = { 1,3,6,1,6,3,10,2,1,1,0}; # securityEngineID in hash = snmpEngineID = .1.3.6.1.6.3.10.2.1.1.0 my $securityEngineID = $$pdu_info{"securityEngineID"} || "unknown"; $securityEngineID = unpack('h*', $securityEngineID); # securityName in hash = snmpCommunitySecurityName = .1.3.6.1.6.3.18.1.1.1.3 my $securityName = $$pdu_info{"securityName"} || "unknown"; # SNMPTT expects the 3rd item to be the uptime and the 4th to be the trapname my $uptime; my $trapname; my $other_varbinds; # Cycle through all the varbinds foreach my $x (@$varbinds) { printf " %-30s type=%-2d value=%s\n", $x->[0], $x->[2], $x->[1]; my $oid = "$x->[0]"; my $value = "$x->[1]"; $value =~ s/^STRING: //g; $value =~ s/^INTEGER: //g; $value =~ s/^OID: //g; $value =~ s/^IpAddress: //g; $value =~ s/^Timeticks: //g; if ($oid eq ".1.3.6.1.2.1.1.3.0") { # my $temp = $value; # $temp =~ /Timeticks: \(.*?\) (.*)/; # $uptime = $oid . " " . $1; $uptime = $oid . " " . $value; } elsif ($oid eq ".1.3.6.1.6.3.1.1.4.1.0") { # my $temp = $value; # $temp =~ /OID: (.*)/; # $trapname = $oid . " " . $1; $trapname = $oid . " " . $value; } else { $other_varbinds .= $oid . " " . $value . "\n"; } } ############################################################################## # Create file in spool directory based on current time my ($s, $usec) = gettimeofday; # Pad the numbers with 0's to make sure they are all the same length. Sometimes the # usec is shorter than 6. my $s_pad = sprintf("%09d",$s); my $usec_pad = sprintf("%06d",$usec); if ($DEBUGGING >= 1) { if ($DEBUGGING_FILE ne '') { open DEBUGFILE, ">>$DEBUGGING_FILE" or warn "Could not open debug output file ($!)"; select DEBUGFILE; # Change default output to debug file } # Print out time print "-------------------------------------------------------------\n"; print "SNMPTTHANDLER-EMBEDDED started: ",scalar(localtime),"\n\n"; print "s = $s, usec = $usec\n"; print "s_pad = $s_pad, usec_pad = $usec_pad\n\n"; print "Data received:\n\n"; } my $spoolfile = $spool_directory.'#snmptt-trap-'.$s_pad.$usec_pad; unless (open SPOOL, ">$spoolfile") { if ($DEBUGGING >= 1) { print "Could not write to file file $spoolfile! Trap will be lost!\n"; } die "Could not write to file $spoolfile! Trap will be lost!\n"; } print SPOOL time()."\n"; print SPOOL $hostname . "\n"; print SPOOL $ip_address . "\n"; print SPOOL $uptime . "\n"; print SPOOL $trapname . "\n"; print SPOOL ".1.3.6.1.6.3.18.1.4.0 $community\n"; print SPOOL $other_varbinds; if ($securityEngineID ne "") { print SPOOL ".1.3.6.1.6.3.10.2.1.1.0 \"0x$securityEngineID\"\n"; } if ($securityName ne "") { print SPOOL ".1.3.6.1.6.3.18.1.1.1.3 \"$securityName\"\n"; } if ($contextEngineID ne "") { print SPOOL ".1.3.6.1.6.3.18.1.1.1.4 \"0x$contextEngineID\"\n"; } if ($contextName ne "") { print SPOOL ".1.3.6.1.6.3.18.1.1.1.5 \"$contextName\"\n"; } close SPOOL; if ($DEBUGGING >= 1) { print SPOOL time()."\n"; print $hostname . "\n"; print $ip_address . "\n"; print $uptime . "\n"; print $trapname . "\n"; print ".1.3.6.1.6.3.18.1.4.0 $community\n"; print $other_varbinds; if ($securityEngineID ne "") { print ".1.3.6.1.6.3.10.2.1.1.0 \"0x$securityEngineID\"\n"; } if ($securityName ne "") { print ".1.3.6.1.6.3.18.1.1.1.3 \"$securityName\"\n"; } if ($contextEngineID ne "") { print ".1.3.6.1.6.3.18.1.1.1.4 \"0x$contextEngineID\"\n"; } if ($contextName ne "") { print ".1.3.6.1.6.3.18.1.1.1.5 \"$contextName\"\n"; } # Flush the buffers for debugging. $| = 1; $| = 0; } return NETSNMPTRAPD_HANDLER_OK; } sub loadsnmpttini { ############################################################################## # Load snmptt.ini # # For Linux / Unix, try /etc/snmp/snmptt.ini first, /etc/snmptt.ini second. # # For Windows, try %SystemRoot%\snmptt.ini only. # my $cfg; if ($ini ne '') { $configfile = $ini; } else { if ($^O ne "MSWin32") { if (-f '/etc/snmp/snmptt.ini' && -r '/etc/snmp/snmptt.ini') { $configfile = '/etc/snmp/snmptt.ini'; } elsif (-f '/etc/snmptt.ini' && -r '/etc/snmptt.ini') { $configfile = '/etc/snmptt.ini'; } else { if ($DEBUGGING >= 1) { print "Could not load snmptt.ini from the default file locations (/etc/snmp/ or /etc/).\n"; } warn "Could not load snmptt.ini from the default file locations (/etc/snmp/ or /etc/).\n"; exit(1); } } else { $configfile = $ENV{'SystemRoot'}."\\snmptt.ini"; } } if( open( CONFIG, $configfile ) ) { close CONFIG; $cfg = new Config::IniFiles( -file => $configfile); } else { if ($DEBUGGING >= 1) { print "Config file ($configfile) could not be loaded\n"; } warn "Config file ($configfile) could not be loaded\n"; exit(1); } if (! $cfg) { if ($DEBUGGING >= 1) { print "Error in config file - please check the syntax in the config file\n"; } exit(1); } # DaemonMode $spool_directory = $cfg->val('DaemonMode', 'spool_directory'); # Debugging if ($debug eq '') { $DEBUGGING = $cfg->val('Debugging', 'DEBUGGING'); } $DEBUGGING_FILE = $cfg->val('Debugging', 'DEBUGGING_FILE_HANDLER'); $cfg->Delete; # Defaults Start if (! defined ($spool_directory)) { $spool_directory = ''} ; if (! defined ($DEBUGGING)) { $DEBUGGING = 0} ; if (! defined ($DEBUGGING_FILE)) { $DEBUGGING_FILE = ''} ; # Defaults End } snmptt_1.4/snmpttconvertmib0000775000000000000000000007405512236567454015062 0ustar rootroot#!/usr/bin/perl # # SNMPTTCONVERTMIB v1.4 # # Copyright 2002-2013 Alex Burger # alex_b@users.sourceforge.net # # 8/14/2002 # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################## # # http://www.sourceforge.net/projects/snmptt # ############################################################################### use strict; # # OPTIONS START # # Set this to '' to have no default EXEC line added, or modify as needed. # Can also set on the command line with --exec='string' my $defaultexec = ''; # Choose what type of quotes (if any) you want around the SUMMARY text pulled from the MIB. #$defaultexecquote = ''; # no quotes #$defaultexecquote = "\'"; # single (') quotes my $defaultexecquote = "\""; # double (") quotes # Set this to 1 to have the --TYPE string prepended to the --SUMMARY string. # Set to 0 to disable my $prepend_type = 1; # # OPTIONS END # ############################################################################# # my $snmpttconvertmib_version = "v1.4"; sub showversion { print "\nSNMPTTCONVERTMIB $snmpttconvertmib_version\n"; print "(c) 2002-2013 Alex Burger\n"; print "http://snmptt.sourceforge.net\n\n"; } ############################################################################## # Process command line arguments $| = 1; use Getopt::Long; use File::Basename; use File::Spec; my $DEBUGGING = 0; my $version = 0; my $debug = 0; my $help = 0; my $net_snmp_perl = 0; my $in = ''; my $out = ''; my $nodes = ''; my $no_description = 0; my $no_variables = 0; my $no_format_summary = 0; my $no_format_desc = 0; my $format = 0; my $format_desc = 0; my $no_desc_wildcard = 0; my $no_severity = 0; my $severity = 'Normal'; my $exec = ''; GetOptions ('version' => \$version, 'debug:i' => \$debug, 'help' => \$help, 'in=s' => \$in, 'out=s' => \$out, 'net_snmp_perl' => \$net_snmp_perl, 'nodes=s' => \$nodes, 'no_description' => \$no_description, 'no_variables' => \$no_variables, 'no_format_summary' => \$no_format_summary, 'no_format_desc' => \$no_format_desc, 'no_severity' => \$no_severity, 'severity=s' => \$severity, 'format=n' => \$format, 'format_desc=n' => \$format_desc, 'no_desc_wildcard' => \$no_desc_wildcard, 'exec=s' => \$exec); if ($version == 1) { &showversion; exit(0); } if ($help == 1) { &show_help(); exit(0); } # Replace any spaces with -'s in severity $severity =~ s/ /-/g; if ($debug == 1) { $DEBUGGING = 1; } if ($debug == 2) { $DEBUGGING = 2; } if (($in eq "") || ($out eq "")) { print "\nMissing arguments!\n"; &show_help(); exit 1; } # Get complete path of input file (MIB) in a portable way (needed for -m switch for snmptranslate) my $dirname = dirname $in; my $basename = basename $in; my $input = File::Spec->catfile($dirname, $basename); # Get complete path of output file (.conf) in a portable way $dirname = dirname $out; $basename = basename $out; my $output = File::Spec->catfile($dirname, $basename); if ($exec ne '') { $defaultexec = $exec; print "exec: $exec\n"; } #print "nodes: $nodes\n"; if ($net_snmp_perl == 1) { print "\n\n***** UCD-SNMP / NET-SNMP Perl module enabled *****\n\n"; } print "\n\n***** Processing MIB file *****\n\n"; my $snmptranslate_use_On; check_snmptranslate_version(); print "severity: $severity\n"; print "\nFile to load is: $input\n"; print "File to APPEND TO: $output\n"; # Set MIBS environment variable to the filename of the MIB file (not the mib name - if a file contains # multiple MIB definitions in one file, the mib name will not work - at least with 5.0.8 and older) $ENV{MIBS} = $input; print "\nMIBS environment var: $ENV{MIBS}\n"; if ($DEBUGGING >= 1) { print "\nLoading$input\n"; } unless (open INPUTFILE, "<$input") { die "Cannot open input file: $!"; } my @mibfile; while () { chomp; # remove at end of line s/\015//; # Remove any DOS carriage returns push(@mibfile, $_); # add to each line to @trapconf array } if ($DEBUGGING >= 1) { print "Finished loading $input\n\n"; } my $currentline=0; unless (open OUTPUTFILE, ">>$output") { die "Cannot open output file: $!"; } # A mib file can contain multiple BEGIN definitions. This finds the first one # to make sure we have at least one definition. # Determine name of MIB file my $mib_name = ''; while ($currentline <= $#mibfile) { my $line = $mibfile[$currentline]; # Sometimes DEFINITIONS ::= BEGIN will appear on the line following the mib name. # Look for DEFINITIONS ::= BEGIN with nothing (white space allowed) around it and a previous line with # only a single word with whitespace around it. if ($currentline > 0 && $line =~ /^\s*DEFINITIONS\s*::=\s*BEGIN\s*$/ && $mibfile[$currentline-1] =~ /^\s*(\S+)\s*$/) { # We should have found the mib name $mib_name = $1; print "\nSplit line DEFINITIONS ::= BEGIN found ($1).\n"; $mib_name =~ s/\s+//g; last; } elsif ($line =~ /(.*)DEFINITIONS\s*::=\s*BEGIN/) { $mib_name = $1; $mib_name =~ s/\s+//g; last; } $currentline++; } print "mib name: $mib_name\n"; if ($mib_name eq '') { print "\n\nAborting!!!\n"; print "Could not find DEFINITIONS ::= BEGIN statement in MIB file!\n\n"; exit (1); } if ($net_snmp_perl == 1) { require SNMP; $SNMP::save_descriptions = 1; # Need them only for looking up variable descriptions. # Do TRAP definition by hand to be able to pull out # the SUMMARY lines &SNMP::initMib(); print "\n\n***** Using UCD-SNMP / NET-SNMP Perl module *****\n\n"; } my $total_translations = 0; my $successful_translations = 0; my $failed_translations = 0; $currentline=0; #if ($net_snmp_perl == 0) if (1) { # Process the trap files by hand while ($currentline <= $#mibfile) { my $line = $mibfile[$currentline]; # Sometimes DEFINITIONS ::= BEGIN will appear on the line following the mib name. # Look for DEFINITIONS ::= BEGIN with nothing (white space allowed) around it and a previous line with # only a single word with whitespace around it. if ($currentline > 0 && $line =~ /^\s*DEFINITIONS\s*::=\s*BEGIN\s*$/ && $mibfile[$currentline-1] =~ /^\s*(\S+)\s*$/) { # We should have found the mib name print "\n\nSplit line DEFINITIONS ::= BEGIN found ($1).\n"; $mib_name = $1; $mib_name =~ s/\s+//g; print "Processing MIB: $mib_name\n"; print OUTPUTFILE "#\n#\n#\n#\n"; print OUTPUTFILE "MIB: $mib_name (file:$input) converted on " . scalar(localtime) . " using snmpttconvertmib $snmpttconvertmib_version\n"; $currentline++; # Increment to the next line next; } elsif ($line =~ /(.*)DEFINITIONS\s*::=\s*BEGIN/) { $mib_name = $1; $mib_name =~ s/\s+//g; print "\n\nProcessing MIB: $mib_name\n"; print OUTPUTFILE "#\n#\n#\n#\n"; print OUTPUTFILE "MIB: $mib_name (file:$input) converted on " . scalar(localtime) . " using snmpttconvertmib $snmpttconvertmib_version\n"; $currentline++; # Increment to the next line next; } # TRAP-TYPE (V1) / NOTIFICATION-TYPE (V2) # # eg: 'mngmtAgentTrap-23003 TRAP-TYPE'; # eg: 'ciscoSystemClockChanged NOTIFICATION-TYPE'; if ( $line =~ /(.*)\s*TRAP-TYPE.*/ || $line =~ /(.*)\s*(?