File: snmptt.html

package info (click to toggle)
snmptt 1.5-2
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 1,496 kB
sloc: perl: 6,822; sh: 184; python: 31; makefile: 12
file content (3045 lines) | stat: -rw-r--r-- 206,744 bytes
parent folder | download | duplicates (2)
<!DOCTYPE html>
<p><html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<meta name="generator" content=
"HTML Tidy for HTML5 for Linux version 5.6.0" />
<meta content="Alex Burger" name="Author" />
<meta content="Mozilla/4.78 [en] (Windows NT 5.0; U) [Netscape]"
name="GENERATOR" />
<link rel="StyleSheet" type="text/css" href="layout1.css" />
<title>SNMP Trap Translator</title>
</head></p>
<h1>SNMP Trap Translator v1.5</h1>
<p><strong>(<a href="http://www.snmptt.org">SNMPTT</a>)</strong></p>
<p>This file was last updated on: August 17th, 2022</p>
<p><a href="#License">License</a></p>
<p><a href="#What-is-it">SNMPTT</a></p>
<ul>
<li><a href="#What-is-it">What is it?</a></li>
<li><a href="#Downloading">Downloading</a>  </li>
<li><a href="#Requirements">Requirements</a>  </li>
<li><a href="#Whats-New">What's New</a>  </li>
<li><a href="#Upgrading">Upgrading</a>  </li>
<li><a href="#Installation">Installation</a>  <ul>
<li><a href="#Installation-Overview">Overview</a>  </li>
<li><a href="#Installation-Unix">Unix</a>  <ul>
<li><a href="#Installation-Unix-Package">Package Manager</a>  </li>
<li><a href="#Installation-Unix-Manual">Manual installation</a>  </li>
<li><a href="#Installation-Unix-Handlers">Net-SNMP handlers</a><ul>
<li><a href="#Installation-Unix-Standard">Net-SNMP Standard handler</a></li>
<li><a href="#Installation-Unix-Embedded">Net-SNMP Embedded handler</a></li>
</ul>
</li>
<li><a href="#Installation-Unix-Testing">Testing</a></li>
</ul>
</li>
<li><a href="#Installation-Windows">Windows</a>  </li>
<li><a href="#SecuringSNMPTT">Securing SNMPTT</a>  </li>
</ul>
</li>
<li><a href="#Configuration-Options">Configuration Options - snmptt.ini</a>  </li>
<li><a href="#Modes-of-Operation">Modes of Operation</a>  <ul>
<li><a href="#Modes-of-Operation-Daemon">Daemon Mode</a></li>
<li><a href="#Modes-of-Operation-Standalone">Standalone Mode</a></li>
</ul>
</li>
<li><a href="#Command-line-arguments">Command line arguments</a>  </li>
<li><a href="#Logging">Logging</a>  <ul>
<li><a href="#LoggingStandard">Standard</a>  </li>
<li><a href="#LoggingUnknown">Unknown Traps</a>  </li>
<li><a href="#LoggingSyslog">Syslog</a>  </li>
<li><a href="#LoggingEventLog">Windows EventLog</a>  </li>
<li><a href="#LoggingDatabase">Database</a>  <ul>
<li><a href="#LoggingDatabase-MySQL">MySQL</a>  </li>
<li><a href="#LoggingDatabase-PostgreSQL">PostgreSQL</a>  </li>
<li><a href="#LoggingDatabase-ODBC">ODBC</a>  </li>
<li><a href="#LoggingDatabase-Windows_ODBC">Windows ODBC</a>  </li>
</ul>
</li>
</ul>
</li>
<li><a href="#Executing-an-external-program">Executing an external program</a>  </li>
<li><a href="#SNMPTT.CONF-Configuration-file-format">SNMPTT.CONF Configuration file format</a>  <ul>
<li><a href="#SNMPTT.CONF-EVENT">EVENT</a>  </li>
<li><a href="#SNMPTT.CONF-FORMAT">FORMAT</a>  <ul>
<li><a href="#Variable-substitutions">Variable-substitutions</a>  </li>
</ul>
</li>
<li><a href="#SNMPTT.CONF-EXEC">EXEC</a>  </li>
<li><a href="#SNMPTT.CONF-PREEXEC">PREEXEC</a>  </li>
<li><a href="#SNMPTT.CONF-NODES">NODES</a>  </li>
<li><a href="#SNMPTT.CONF-MATCH">MATCH</a>  </li>
<li><a href="#SNMPTT.CONF-REGEX">REGEX</a>  </li>
<li><a href="#SNMPTT.CONF-SDESC">SDESC</a>  </li>
<li><a href="#SNMPTT.CONF-EDESC">EDESC</a>  </li>
</ul>
</li>
<li><a href="#SNMPTT.CONF-Configuration-file-Notes">SNMPTT.CONF Configuration file Notes</a>  </li>
<li><a href="#DNS">Name resolution / DNS</a>  </li>
<li><a href="#Sample-SNMPTT.CONF-file">Sample SNMPTT.CONF files</a>  <ul>
<li><a href="#Sample1-SNMPTT.CONF-file">Sample1 SNMPTT.CONF file</a>  </li>
<li><a href="#Sample2-SNMPTT.CONF-file">Sample2 SNMPTT.CONF file</a>  </li>
</ul>
</li>
<li><a href="#Notes">Notes</a>  <ul>
<li><a href="#Notes-trapd.conf">trapd.conf &amp; MIB files</a>  </li>
<li><a href="#Notes-ipv6">IPv6</a>  </li>
</ul>
</li>
<li><a href="#Limitations">Limitations</a>  </li>
<li><a href="#Feedback">Feedback &amp; Bugs</a>  </li>
<li><a href="#Integration-with-other-software">Integration with other software</a>  <ul>
<li><a href="#Nagios-Netsaint">Nagios</a>  </li>
<li><a href="#Icinga">Icinga</a>  </li>
<li><a href="#Zabbix">Zabbix</a></li>
<li><a href="#SEC">Simple Event Correlator (SEC)</a>  </li>
<li><a href="#EventWin">Windows Event Log forwarding</a>  </li>
<li><a href="#Hobbit">Xymon / Hobbit</a></li>
</ul>
</li>
</ul>
<h1><a name="License"></a>License</h1>
<p>Copyright 2002-2022 Alex Burger<br />
alex_b@users.sourceforge.net<br />
4/3/2002</p>
<p>This program is free software; you can redistribute it and/or modify<br />
it under the terms of the GNU General Public License as published by<br />
the Free Software Foundation; either version 2 of the License, or<br />
(at your option) any later version.</p>
<p>This program is distributed in the hope that it will be useful,<br />
but WITHOUT ANY WARRANTY; without even the implied warranty of<br />
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the<br />
GNU General Public License for more details.</p>
<p>You should have received a copy of the GNU General Public License<br />
along with this program; if not, write to the Free Software<br />
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA  </p>
<h1><a name="What-is-it"></a>What is it?</h1>
<p>SNMPTT (SNMP Trap Translator) is an SNMP trap handler written in Perl for use with the Net-SNMP <a href="http://www.net-snmp.org/man/snmptrapd.html">snmptrapd</a> program (<a href="http://www.net-snmp.org">www.net-snmp.org</a>). SNMPTT supports Linux, Unix and Windows.</p>
<p>Many network devices including but not limited to network switches, routers, remote access servers, UPSs, printers and operating systems such as Unix and Windows 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.</p>
<p>The notifications 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.</p>
<p>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.</p>
<p>The Net-SNMP program <strong>snmptrapd</strong> 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 using numeric OIDs:</p>
<pre><code>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)
</code></pre>
<p>Here is the same trap using symbolic OIDs.</p>
<pre><code>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)
</code></pre>
<p>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.</p>
<p>A more descriptive / friendly trap message can be created using SNMPTT's variable substitution. Following is the same trap, logged with SNMPTT:</p>
<p><code>Feb 12 13:37:13 server11 TRAPD: .1.3.6.1.4.1.232.0.3008 Normal "LOGONLY" server08 - Logical Drive Status Change: Status is now rebuilding</code></p>
<p>The definition for the cpqDa3LogDrvStatusChange trap in the SNMPTT configuration file would be defined as follows:</p>
<p><code>FORMAT Logical Drive Status Change: Status is now $3.</code></p>
<p>The $3 represents the third variable as defined in the MIB file, which for this particular trap, is the cpqDaLogDrvStatus variable.</p>
<p>Another example of an SNMPTT configuration entry is:</p>
<p><code>FORMAT Compaq Drive Array Spare Drive on controller $4, bus $5, bay $6 status is $3.</code></p>
<p>Which could result in the following output:</p>
<p><code>"Compaq Drive Array Spare Drive on controller 3, bus 0, bay 3 status is Failed."</code></p>
<p>SNMPTT can log to any of the following destinations: text log, syslog, Windows Event log or a SQL database such as MySQL, PostreSQL or an ODBC accessible database such as Microsoft SQL. External programs can also be run to pass th  e translated trap to an email client, paging software, Nagios, Icinga etc.</p>
<p>In addition to variable substitution, SNMPTT allows complex configurations allowing:</p>
<ul>
<li>the ability to accept or reject a trap based on the host name, ip address, network range, or variable values inside of the trap enterprise variables</li>
<li>execute external programs to send pages, emails etc</li>
<li>perform regular expression search and replace on the translated message such as translating the variable value "Building alarm 4" to "Moisture detection alarm"</li>
</ul>
<p>As of SNMPTT 1.5, both IPv4 and IPv6 are supported.</p>
<h1><a name="Downloading"></a>Downloading</h1>
<p>SNMPTT can be downloaded from the <a href="https://sourceforge.net/projects/snmptt/files/snmptt/">Sourceforge files page</a>.  The primary git source code repository is avaialble at <a href="https://sourceforge.net/p/snmptt/git/ci/master/tree/">Sourceforge</a> and a mirror is available at <a href="https://github.com/AlexB7/snmptt">GitHub</a>.</p>
<h1><a name="Requirements"></a>Requirements</h1>
<ul>
<li>Perl 5.6.1 or higher.  SNMPTT began development using 5.6.1 and although it is now developed with 5.30, it should still be backwards compatible 5.6.1.</li>
<li>To use snmptthandler-embedded, Net-SNMP's snmptrapd must be compiled with embedded Perl enabled (<strong>--enable-embedded-perl</strong> configuration option)</li>
</ul>
<h2>Perl Modules</h2>
<style type="text/css" rel="stylesheet">
table {
    /* Moved from layout1.css so that it doesn't conflict with snmptt.org web page */
    border-collapse: collapse;
    width: 70%;
  }

  td, th {
    border: 1px solid #aaaaaa;
    text-align: left;
    padding: 2px;
    max-width: 50em;
  }

  tr:nth-child(even) {
    background-color: #dddddd;
  }
</style>

<table>
<thead>
<tr>
<th style="text-align: left;">R/O</th>
<th style="text-align: left;">Program / Module</th>
<th style="text-align: left;">rpm</th>
<th style="text-align: left;">deb</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">Required</td>
<td style="text-align: left;"><a href="http://www.net-snmp.org">Net-SNMP</a> (formerly known as UCD-SNMP).  Specifically <strong>snmptrapd.</strong></td>
<td style="text-align: left;">net-snmp, net-snmp-utils</td>
<td style="text-align: left;">snmp, snmptrapd</td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="http://www.net-snmp.org/FAQ.html#How_do_I_install_the_Perl_SNMP_modules_">Net-SNMP Perl module</a>.  Only required for features that perform conversions between symbolic and numeric OIDs.  This is NOT the same as the Net::SNMP module availabe from CPAN.</td>
<td style="text-align: left;">net-snmp-perl</td>
<td style="text-align: left;">libsnmp-perl</td>
</tr>
<tr>
<td style="text-align: left;">Required</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/Text::ParseWords">Text::ParseWords</a> module (included with most distributions)</td>
<td style="text-align: left;">perl-Text-ParseWords</td>
<td style="text-align: left;"></td>
</tr>
<tr>
<td style="text-align: left;">Required</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/Getopt::Long">Getopt::Long</a> module (included with most distributions)</td>
<td style="text-align: left;"></td>
<td style="text-align: left;"></td>
</tr>
<tr>
<td style="text-align: left;">Required</td>
<td style="text-align: left;"><a href="http://search.cpan.org/search?module=POSIX">Posix</a> module (included with most if not all distributions)</td>
<td style="text-align: left;"></td>
<td style="text-align: left;"></td>
</tr>
<tr>
<td style="text-align: left;">Required</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/Config::IniFiles">Config::IniFiles</a> module</td>
<td style="text-align: left;">perl-Config-IniFiles (EPEL, PowerTools repos)</td>
<td style="text-align: left;">libconfig-inifiles-perl</td>
</tr>
<tr>
<td style="text-align: left;">Required</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/Time::HiRes">Time::HiRes</a> module (only required when using SNMPTT in daemon mode - required by <strong>snmptthandler</strong>)</td>
<td style="text-align: left;">perl-Time-HiRes</td>
<td style="text-align: left;">libtime-hires-perl</td>
</tr>
<tr>
<td style="text-align: left;">Required</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/Sys::Hostname">Sys::Hostname</a> module (included with most if not all distributions).</td>
<td style="text-align: left;"></td>
<td style="text-align: left;"></td>
</tr>
<tr>
<td style="text-align: left;">Required</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/File::Basename">File::Basename</a> module (included with most if not all distributions).</td>
<td style="text-align: left;"></td>
<td style="text-align: left;"></td>
</tr>
<tr>
<td style="text-align: left;">Required</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/Text::Balanced">Text::Balanced</a> module (included with most if not all distributions).</td>
<td style="text-align: left;">perl-Text-Balanced</td>
<td style="text-align: left;"></td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/Net::IP">Net::IP</a> module. Required for IPv6 support.</td>
<td style="text-align: left;">perl-Net-IP (EPEL repo)</td>
<td style="text-align: left;">libnet-ip-perl</td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/IO::Socket::IP">IO::Socket::IP</a> module (included with most if not all distributions). Required for DNS translations.</td>
<td style="text-align: left;"></td>
<td style="text-align: left;"></td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/Sys::Syslog">Sys::Syslog</a> module (included with most Unix distributions). Required for Syslog support using Unix sockets (local syslog).</td>
<td style="text-align: left;">perl-Sys-Syslog</td>
<td style="text-align: left;"></td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/Log::Syslog::Fast">Log::Syslog::Fast</a> and <a href="https://metacpan.org/pod/Log::Syslog::Constants">Log::Syslog::Constants</a> modules. Required for remote syslog and RFC5424 support.</td>
<td style="text-align: left;"></td>
<td style="text-align: left;"></td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/DBI">DBI</a> module.  Required for DBD::MySQL, DBD::PgPP and DBD::ODBC support.</td>
<td style="text-align: left;">perl-DBI</td>
<td style="text-align: left;">libclass-dbi-perl</td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/DBD::mysql">DBD::mysql</a> module.  Required for MySQL support.</td>
<td style="text-align: left;">perl-DBD-MySQL</td>
<td style="text-align: left;">libdbd-mysql-perl</td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/DBD::PgPP">DBD::PgPP</a> or <a href="https://metacpan.org/pod/DBD::Pg">DBD:Pg</a> module.  Required for PostgreSQL support.</td>
<td style="text-align: left;">perl-DBD-Pg</td>
<td style="text-align: left;">libdbd-pg-perl</td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/DBD::ODBC">DBD::ODBC</a> module.  Required for ODBC (SQL etc) access on Linux / Windows (Win32::ODBC not required if using DBD::ODBC)</td>
<td style="text-align: left;">perl-DBD-ODBC</td>
<td style="text-align: left;">libdbd-odbc-perl</td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/Win32::ODBC">Win32::ODBC</a> module.  Required for ODBC (SQL etc) access on Windows (DBD::ODBC not required if using Win32::ODBC)</td>
<td style="text-align: left;"></td>
<td style="text-align: left;"></td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/threads">threads</a> and <a href="https://metacpan.org/pod/Thread::Semaphore">Thread::Semaphore</a> modules (included with most if not all distributions).  Required when enabling threads for EXEC statements.</td>
<td style="text-align: left;">perl-threads</td>
<td style="text-align: left;">libthreads-perl</td>
</tr>
<tr>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;"><a href="https://metacpan.org/pod/Digest::MD5">Digest::MD5</a> module (included with most if not all distributions).  Required when enabling duplicate trap detection.</td>
<td style="text-align: left;">perl-Digest-MD5</td>
<td style="text-align: left;">libdigest-md5-perl</td>
</tr>
</tbody>
</table>
<p><br />   </p>
<p>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.7.x release. The Windows version has been tested with both native mode and under Cygwin.</p>
<p>SNMP V1, V2 and V3 traps have been tested.</p>
<p>The latest version of Net-SNMP is recommended.</p>
<p>Note:</p>
<ul>
<li>SNMPTT only requires the Net-SNMP Perl module if you want to have variable names translated into symbolic form, you want to be able to have <strong>snmptrapd</strong> pass traps using symbolic form, or you enable the options <strong>translate_integers</strong>, <strong>translate_trap_oid</strong> or <strong>translate_oids</strong>. Although not required, using the Perl module is recommended.  It is also required if you want to use the <strong>snmptthandler-embedded</strong> trap handler with snmptrapd.</li>
</ul>
<h1><a name="Whats-New"></a>What's New</h1>
<h2><strong>v1.5</strong> <strong>- August 17th, 2022</strong></h2>
<ul>
<li>Added PREEXEC support for unknown traps.  Results are stored in the variable <strong>$pu<em>n</em></strong>.  See the <strong>unknown_trap_preexec</strong> setting in <strong>snmptt.ini</strong>.</li>
<li>Added <strong>unknown_trap_nodes_match_mode</strong> setting to allow you to change how traps are handled when they do not match due to <strong>MATCH</strong> and <strong>NODES</strong>.  If set to 1, traps are considered skipped instead of unknown.  Statistics now include the number of skipped traps when enabled.</li>
<li>Added support for wildcards for the <strong>snmptt_conf_files</strong> setting in <strong>snmptt.ini</strong>.  Example: <strong>/etc/snmptt/snmptt.*.conf</strong></li>
<li>Added <strong>log_format</strong> <strong>snmptt.ini</strong> setting to allow you to define the STDOUT, text log and eventlog text format.</li>
<li>Added <strong>syslog_format</strong> <strong>snmptt.ini</strong> setting to allow you to define the syslog text format.  This will allow you to add a structured data section for RFC5424 syslog.</li>
<li>Added variable substitution <strong>$j</strong> to pull out the enterprise number from the full enterprise OID.  For example, for enterprise OID .1.3.6.1.4.1.232, <strong>$j</strong> would
  contain 232.</li>
<li>Added remote syslog support using the Perl module Log::Syslog::Fast which also allows you to specify the APP-NAME for RFC5424 syslog.
  Added the following <strong>snmptt.ini</strong> settings: <strong>syslog_module</strong>, <strong>syslog_remote_dest</strong>, <strong>syslog_remote_port</strong>, <strong>syslog_remote_proto</strong>, <strong>syslog_rfc_format</strong>, <strong>syslog_app</strong> and <strong>syslog_system_app</strong>.</li>
<li>Added reload support to the <strong>snmptt.service</strong> systemd file.  This will allow you to use the <strong>'systemctl reload snmptt'</strong> command to reload the configuration.</li>
<li>Added support for IPv6.  To enable, set <strong>ipv6_enable = 1</strong> in <strong>snmptt.ini</strong>.</li>
<li>Added support for sub-second sleep for spool folder processing.</li>
<li><strong>snmptt.ini</strong> can now be located in <strong>/etc/snmptt</strong> and is searched for at this
  location first.</li>
<li>Updated documentation on securing SNMPTT to ensure the snmptt user has read access to the configuration files.  This is required when issuing a reload.</li>
<li>Fixed a bug with <strong>daemon_uid</strong> that prevented SNMPTT from starting on FreeBSD
  (bug 47).</li>
<li>Fixed a bug where traps arriving with the hostname set to UNKNOWN were
  not being handled properly (bug 46).</li>
<li>Fixed a bug with <strong>MATCH</strong> which was preventing it from matching integers properly (bug 41).</li>
<li>Fixed a bug where the agent IP address was not handled correctly when
  it was received from Net-SNMP as <strong>IpAddress:x.x.x.x</strong> (bug 27).</li>
<li>Fixed a race condition bug with <strong>snmptthander</strong> and <strong>snmptthandler-embedded</strong>
  which could cause traps to be missed.  Spool files are now immediately locked
  after creation using flock().  If flock() is not supported, the spool file will be created
  with a temporary filename and then renamed after closing.</li>
<li>Fixed a bug with <strong>wildcard_expansion_separator</strong> which caused an issue when
  using wildcard separators that were longer than one character (bug 38).</li>
<li>Fixed a bug where quotes were not properly removed from some incoming traps.</li>
<li>Fixed bug with debug mode that was causing some debug mode output even when
  debug mode was off.</li>
<li>Fixed a bug where DNS resolution was not working for enterprise variables 
  when <strong>net_snmp_perl_enable</strong> was disabled.</li>
<li>Fixed a bug that prevented snmptt from starting when debug mode was disabled (bug 48).</li>
<li>Fixed debug output bug with snmptthandler-embedded (PR 1).</li>
<li>Fixed a bug with IPv6 address handling for NODES in snmptt.conf.</li>
<li>Fixed a bug that prevented the hostname from being extraced when IPv6 is disabled and the hostname is passed from Net-SNMP as UDP: [x.x.x.x]:xxxx-&gt;[x.x.x.x]:xxxx.</li>
<li>Changed <strong>net_snmp_perl_best_guess</strong> default from 0 to 2 as any modern system
  should support this.  See FAQ and <strong>snmptt.ini</strong> for details on this variable.</li>
<li>Enabled Perl warnings to help ensure code is following best practices.</li>
<li>Ran code against Perl::Critic to find non-optimal code.  Made various adjustments such as relacing bare words with variables and changing open() calls from two arguments to three.</li>
<li>Documentation was converted from html to markdown to make it easier to maintain and a full review was completed.  Many improvments have been made including a new section on integrating with Icinga.  The docs folder now contains <strong>.md</strong>, <strong>.html</strong> and <strong>.epub</strong> versions of the documentation.</li>
<li><strong>snmptthandler-embedded</strong>:<ul>
<li>Varbind types <strong>Gauge32</strong> and <strong>Hex-STRING</strong> now have the Gauge32: and Hex-STRING: text removed for incoming traps.  Unicode line endings are also removed (Perl 5.10 and higher).</li>
</ul>
</li>
<li><strong>snmpttconvertmib</strong>:<ul>
<li>Added <strong>--exec_file</strong> option to allow you to provide an EXEC command
inside of a file instead of specifying on the command line.  Useful for
commands that include quotes so that you don't have to worry about escaping on
the command line.  Also allows you to define multiple EXEC lines instead of 
just one.</li>
<li>Added <strong>--exec_mode</strong> option to allow you change how the EXEC line
is built.  Setting to <strong>0</strong> will append the format line to the end of the line
(default).  Setting to <strong>1</strong> does not append the format line to the end of the
line.  This is useful if you have added <strong>$Fz</strong> to the <strong>--exec</strong> line so that
SNMPTT can replace it with the FORMAT line.  Setting to <strong>2</strong> is similar to <strong>1</strong>,
but instead of SNMPTT having to replace <strong>$Fz</strong> with the FORMAT line, 
<strong>snmpttconvertmib</strong> will do the substitution.</li>
<li>Added <strong>--preexec</strong> and <strong>-preexec_file</strong> options.</li>
</ul>
</li>
</ul>
<h2><strong>v1.4.2</strong> <strong>- July 23rd, 2020</strong></h2>
<ul>
<li>Fixed a security issue with EXEC / PREXEC / unknown_trap_exec that could allow malicious shell code to be executed.</li>
<li>Fixed a bug with EXEC / PREXEC / unknown_trap_exec that caused commands to be run as root instead of the user defined in daemon_uid.</li>
</ul>
<h2><strong>v1.4</strong> <strong>- November 6th, 2013</strong></h2>
<ul>
<li>Added <strong>snmptt.ini</strong> option net_snmp_perl_cache_enable to enable caching of Net-SNMP Perl module OID and ENUM translations.  This may speed up translations and reduce CPU load when net_snmp_perl_enable and translate_* options are enabled.</li>
<li>Fixed bug with snmptthandler-embedded where IP addresses and OIDs were not being detected properly because they contained 'OID:', 'IpAddress:' etc.</li>
<li>Fixed bug with MATCH.  The PREEXEC $p variable could not be used with MATCH.  PREEXEC is now executed first if MATCH contains $p.</li>
<li>Fixed bug with syslog.  Log entries were supposed to be logged with snmptt[pid] but instad of the pid it was actually the effective user ID (2980512).</li>
<li>Fixed bug where the hostname is not detected properly when snmptrapd is configured to not use DNS.</li>
<li>Fixed bug where if the spool directory is not defined, files may be deleted from the wrong folder (3020696).</li>
<li>Fixed bug with syslog logging.  Function was not being called properly (3166749).</li>
<li>Fixed bug with MATCH where number ranges were not working (3397982).</li>
<li>Fixed bug with multi-line traps (2915658).</li>
<li>Fixed bug with LOGONLY severity.  EXEC was being executed even if the trap had a severity of LOGONLY (3567744).</li>
<li>Fixed bug with snmptt hanging if the log message sent to syslog contained a % symbol.  All %'s are now escaped before sending to syslog (3567748).</li>
<li>Fixed possible bug with MySQL.  Put CONNECT string on one line.</li>
<li>Fixed bug with not being able to write to the debug log file when running snmptt as non-root if the debug file didn't already exist with the correct permissions at startup.  The ownership of snmptt.debug is now set to daemon_uid before switching to the new uid.  Patch 3423525.</li>
<li>Installation documentation updates (bug 3425999).</li>
</ul>
<h2><strong>v1.3</strong> <strong>- November 15th, 2009</strong></h2>
<ul>
<li>Added snmptthandler-embedded - a Net-SNMP snmptrapd embedded Perl version of snmptthandler.</li>
<li>Added variable substitutions $Be, $Bu, $BE and $Bn for SNMPv3 securityEngineID, securityName, contextEngineID and contextName (requires snmptthandler-embedded handler).</li>
<li>Added <strong>snmptt.ini</strong> option <strong>duplicate_trap_window variable</strong> for duplicate trap detection.</li>
<li>Added LSB init keywords and actions to snmptt-init.d and changed the priority for start / stop so that it starts after snmptrapd and stops before snmptrapd.</li>
<li>Changed the default log path to /var/log/snmptt for Unix and c:\snmpt\log for Windows to make it easier to grant write permission to the snmptt process.</li>
<li>Changed umask for log files to 002 to ensure they are not created as world writable.</li>
<li>Fixed a bug where the the PID file was being created using the parent (root) PID instead of the child (daemon_uid) when daemon_uid is used.</li>
<li>The DEBUG log file will now be re-opened when a HUP signal is sent.</li>
<li>When debugging is enabled, flush buffers every sleep cycle so we can tail the debug log file.</li>
<li>Don't print messages to the console when starting in daemon mode unless debugging is enabled or an error occurs.</li>
<li>'Could not open debug output file!' is no longer reported when debugging is disabled.</li>
<li>Added snmptt.logrotate file from Ville Skytta.</li>
<li>Fixed a bug (1748512) with handling escaped quotes in a trap message.</li>
<li>Updated snmptt-net-snmp-test to test MIB descriptions.</li>
<li>SNMPTTConvertMIB:<ul>
<li>Fixed a bug (1678270) where a TRAP-TYPE / NOTIFICATION-TYPE line would not translate if it was split across two lines.</li>
</ul>
</li>
</ul>
<h2><strong>v1.2</strong> <strong>- June 16th, 2007</strong></h2>
<ul>
<li>When <strong>daemon_uid</strong> is used, two processes will now be spawned. The first process will be run as the same user that started SNMPTT (which should be root). The second will run as the <strong>daemon_uid</strong> user. This was changed so that SNMPTT could properly clean up the pid file on exit.</li>
<li>Added snmptt.ini option <strong>pid_file</strong> to allow for custom pid file locations when running in daemon mode.</li>
<li>Fixed bug where pid file did not contain the current pid of snmptt.</li>
<li>Added <strong>snmptt.ini</strong> options <strong>date_format</strong>, <strong>time_format</strong>, <strong>date_time_format</strong>, <strong>date_time_format_sql</strong> and <strong>stat_time_format_sql</strong> to allow the output format for <strong>$x</strong> and <strong>$X</strong> substitution variables, and the format of the date/time for text logs and SQL to be changed using <strong>strftime()</strong> variables. This allows for proper date/time data types to be used in SQL databases.</li>
<li>Added logging of trap statistics to a SQL table. Added <strong>*table_statistics</strong> <strong>snmptt.ini</strong> variable to define the table to be used.</li>
<li>Added ability to add custom columns to <strong>*_table</strong> and <strong>*_table_unknown</strong> tables. Added <strong>sql_custom_columns</strong> and <strong>sql_custom_columns_unknown</strong> <strong>snmptt.ini</strong> options.</li>
<li>Added <strong>snmptt.ini</strong> option <strong>unknown_trap_exec_format</strong> to allow custom output with substitutions.</li>
<li>Added the ability to log system messages to a text file in addtion to the existing syslog and Event Log.  Added <strong>snmptt.ini</strong> options <strong>log_system</strong> and log_system_file.</li>
<li>Added a work-around to the <a href="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=1638225&amp;group_id=12694&amp;atid=112694">Net-SNMP v5.4 traphandle bug (1638225)</a> where the host name was set to <UNKNOWN>. When detected, SNMPTT will use the host IP address instead.</li>
<li>Added a <strong>$H</strong> variable substitution to give the host name of the computer that is running SNMPTT, or a user defined value specified in the new <strong>snmptt_system_name</strong> <strong>snmptt.ini</strong> option.</li>
<li>Added MATCH support for bitwise AND</li>
<li>Added <strong>snmptt.ini</strong> option <strong>exec_escape</strong> to escape wildards (* and ?) in EXEC, PREEXEC and the unknown_trap_exec commands. This is enabled by default for Linux and Unix (or anything non-Windows) to prevent the wildcards from being expanded by the shell.</li>
<li>Moved <strong>unknown_trap_exec</strong> to Exec section in <strong>snmptt.ini</strong>.</li>
<li>Added 'use strict' pragma in source code.</li>
<li>Experimental:  Added threads (Perl ithreads) support for EXEC. When enabled, EXEC commands will launch in a thread to allow SNMPTT to continue processing other traps. Added <strong>snmptt.ini</strong> options <strong>threads_enable</strong> and <strong>threads_max</strong>.</li>
<li>Fixed bug where snmptt tried to log to syslog when changing UIDs even if syslog_system_enable was set to 0.</li>
<li>Fixed a bug in REGEX with handling of captures.  Text::Balanced module is now required.</li>
<li>Fixed a bug under Windows where SNMPTT was trying to log to syslog instead of the event log.</li>
<li>Fixed a bug where SNMPTT was attempting to log to syslog / eventlog when using the --time option.</li>
<li>Fixed a bug in MATCH where the i modifier was not handled correctly.</li>
<li>Added information to Nagios section of documentation for using SNMP traps as heartbeats by using freshness checks.</li>
<li>Added information to Nagios section of documentation for using freshness checks to automatically clear trap alerts.</li>
<li>SNMPTTConvertMIB:<ul>
<li>Fixed a bug (1438394) where ARGUMENTS lines that have $1, $2 etc instead of %0, %1 would not translate.</li>
<li>Fixed a bug where a --#SEVERITYMAP line would be used instead of --#SEVERITY.</li>
</ul>
</li>
</ul>
<h2><strong>v1.1</strong> <strong>- January 17th, 2006</strong></h2>
<ul>
<li>Added <strong>PREEXEC</strong> <strong>snmptt.conf</strong> file option to allow an external program to be run before processing the FORMAT and EXEC lines. The output of the external program is stored in the <strong>$p_n_</strong> variable where <strong><em>n</em></strong> is a number starting from 1. Multiple <strong>PREEXEC</strong> lines are permitted. The first <strong>PREEXEC</strong> stores the result of the command in <strong>$p1</strong>, the second in <strong>$p2</strong> etc. Any ending newlines are removed. The <strong>snmptt.ini</strong> parameter <strong>pre_exec_enable</strong> can be used to enable / disable it.</li>
<li><strong>MATCH</strong> statement now accepts any variable name instead of only enterprise variables. Example: MATCH $s:(Normal)</li>
<li>Added <strong>NODES MODE=</strong> snmptt.conf file option to allow you to select either <strong>POS</strong> (positive - the default) or <strong>NEG</strong> (negative) for <strong>NODES</strong> matches. If set to <strong>NEG</strong>, then <strong>NODES</strong> is a 'match' only if <em>none</em> of the <strong>NODES</strong> entries match.</li>
<li>Added <strong>unknown_trap_exec</strong> <strong>snmptt.ini</strong> option. If defined, the command will be executed for ALL unknown traps. Passed to the command will be all standard and enterprise variables, similar to <strong>unknown_trap_log_file</strong> but without the newlines.</li>
<li><strong>snmptt --dump</strong> which dumps all the configured EVENTs, now displays duplicate EVENT entries to assist with troubleshooting duplicate entries trap logs.</li>
<li>If the debug log file can not be opened, a message is now logged to syslog if <strong>syslog_system_enable</strong> is enabled, and to the Event Log if <strong>eventlog_system_enable</strong> is enabled</li>
<li>Fixed bug with PostgreSQL where some trap data was interpreted as 'placeholders' in the INSERT statement which caused logging errors. PostgreSQL now uses PREPARE / EXECUTE statements instead.</li>
<li>MySQL now uses PREPARE / EXECUTE statements instead of a single INSERT statement.</li>
<li>Fixed bug in <strong>NODES</strong> where <strong>NODES</strong> entries from previous EVENTs were not being purged correctly.</li>
<li>Fixed bug where <strong>snmptt --dump</strong> would attempt to log to syslog or the Event Log.</li>
<li>Fixed bug that prevented the wildcard <strong>.*</strong> from being accepted on the EVENT line.</li>
<li>Added Windows Event Log forwarding documentation to integration section.</li>
<li>SNMPTTConvertMIB:<ul>
<li>Fixed a bug when <strong>--format_desc=n</strong> was used that caused extra trailing whitespaces to be added for every non existent line in the description.</li>
<li>Fixed bug that prevented some MIBs from being accepted due to spacing in the <strong>DEFINITIONS::= line</strong>.</li>
<li>Fixed bug in that prevented <strong>--ARGUMENTS {}</strong> from being parsed due to spacing.</li>
</ul>
</li>
</ul>
<h2><strong>1.0</strong> <strong>- August 30, 2004</strong></h2>
<ul>
<li>SQL database connections are now opened after forking to the background when running in daemon mode, and after changing users when running SNMPTT as a non-root user. This should prevent 'gone away' and other connection problems with SQL databases due to lost handles.</li>
<li>Added <strong>mysql_ping_on_insert</strong>, <strong>postgresql_ping_on_insert</strong> and <strong>dbd_odbc_ping_on_insert</strong> options to 'ping' the database before doing an INSERT. Also added the options <strong>mysql_ping_interval</strong>, <strong>postgresql_ping_interval</strong> and <strong>dbd_odbc_ping_interval</strong> to periodically ping the database. These options will help ensure the connection to the database remains available. If an error is returned, it will attempt to reconnect to the database. This should prevent SNMPTT from having to be restarted if the SQL server is not available due to an outage or a connection timeout due to no activity.</li>
<li>Added variable substitution <strong>$Fz</strong> which when used on an EXEC line will dump the translated FORMAT line. This will allow for simplified EXEC lines when they are the same as the FORMAT line (minus the command to execute of course).</li>
<li>Added variable substitutions <strong>$Fa</strong>, <strong>$Ff</strong>, <strong>$Fn</strong>, <strong>$Fr</strong>, <strong>$Ft</strong>, for alarm (bell), form feed (FF), newline (LF, NL), return (CR) and tab (HT, TAB)</li>
<li>Added variable substitution <strong>$D</strong> to dump the description text for FORMAT and EXEC lines. The descriptions can be pulled from either the SNMPTT.CONF or MIB files. This is controlled by the <strong>description_mode</strong> and <strong>description_clean</strong> <strong>snmptt.ini</strong> options.</li>
<li>Added support for logging unknown traps to a SQL table</li>
<li>Added logging of statistical information for <strong>total traps received</strong>, <strong>total traps translated</strong>, <strong>total traps ignored</strong> and <strong>total unknown traps</strong>. Statistics are logged at shut down, and optionally at a defined interval defined by the new <strong>snmptt.ini</strong> variable <strong>statistics_interval</strong>. Logging can also be forced by sending the SIGUSR1 signal, or by creating a file called !statistics in the spool folder.</li>
<li>Added the error number reported by MySQL to MySQL errors (system syslog, eventlog etc)</li>
<li>Added <strong>/usr/local/etc/snmp</strong> and <strong>/usr/local/etc</strong> paths to the list of default directories searched for <strong>snmptt.ini</strong>.</li>
<li>Added some friendly error messages when required Perl modules are not available</li>
<li>Fixed bug with with handling traps in symbolic format (snmptrapd without -On)</li>
<li>Fixed bug with with using printing $ symbols in FORMAT and EXEC lines</li>
<li>Added <a href="http://kodu.neti.ee/%7Eristo/sec/">Simple Event Correlator (SEC)</a> integration documentation</li>
<li>SNMPTTConvertMIB:<ul>
<li>Fixed bug that prevented the variable list (OBJECTS) of V2 MIB files from being converted</li>
<li>Fixed bug that caused an infinite loop processing the VARIABLES/OBJECTS section if the line in the MIB file contained spaces after the closing bracket</li>
</ul>
</li>
</ul>
<h2><strong>0.9</strong> <strong>- November 3rd, 2003</strong></h2>
<ul>
<li>Syslog messages are now logged with snmptt[pid] instead of TRAPD for traps, and snmptt-sys[pid] instead of SNMPTT for system messages</li>
<li>Added the option daemon_uid which causes snmptt to change to a different user (uid) after launching on Unix systems running in daemon mode</li>
<li>Fixed bug that prevented ip addresses from being detected correctly with translate_value_oids</li>
<li>Fixed bug with MATCH that caused integer ranges from not being handled correctly</li>
<li>Separated SNMPTT, SNMPTTCONVERT, SNMPTTCONVERTMIB and FAQ / Troubleshooting documentation into separate documents</li>
</ul>
<h2><strong>0.8</strong> <strong>-</strong> <strong>September 16th</strong><strong>, 2003</strong></h2>
<ul>
<li>Added MATCH keyword support to allow trap matching based on values contained inside the trap enterprise variables</li>
<li>REGEX now supports substitution with captures and the modifiers i, g and e.  The e modifier allows for complex REGEX expressions.</li>
<li>Added support for remote MySQL and PostgreSQL databases</li>
<li>Added PostgreSQL support for <a href="http://search.cpan.org/search?dist=DBD-Pg">DBD:Pg</a></li>
<li>An EVENT can now contain mulitple EXEC lines</li>
<li>An EVENT can now contain mulitple NODES lines</li>
<li>Added the option dynamic_nodes to allow NODES files to be either loaded at startup or loaded each time an EVENT is processed</li>
<li>Added trapoid column for database logging to contain the actual trap received.  The eventid column will contain the actual matched entry from the .conf file (which could be a wildcard OID)</li>
<li>Fixed bug that prevented some variables from displaying the correct values because the received trap OID was replaced with the actual EVENT entry</li>
<li>Fixed bug that caused OIDs not to be translated correctly with translate_value_oids enabled</li>
<li>Agent IP address is now used instead of 'host' IP address for NODES matches, the 'hostname' column in database logs and the $A variable</li>
<li>Variable $A now prints the agent host name.  $aA prints the agent IP address.</li>
<li>Variable $E now prints the enterprise in symbolic form.  $e prints the numeric OID</li>
<li>Variable $O now prints the trap in symbolic form.  $o prints the numeric OID</li>
<li>Added new variable substitution <strong>$i</strong> to print the actual matched entry from the .conf file (which could be a wildcard OID)</li>
<li>Added the configuration option dns_enable to enable DNS lookups on host and agent IP addresses</li>
<li>If DNS is enabled, NODES entries are resolved to IP addresses and the IP address is used to perform the match.  This will allow for aliases to be used.</li>
<li>Added the option resolve_value_ip_addresses to resolve ip addresses contained inside enterprise variable values</li>
<li>Changed snmptt.ini setting translate_trap_oid to translate_log_trap_oid</li>
<li>Changed snmptt.ini setting translate_oids to translate_value_oids</li>
<li>Added configuraiton settings: translate_enterprise_oid_format, translate_trap_oid_format, translate_varname_oid_format and db_translate_enterprise</li>
<li>$O follows translate_trap_oid_format, and $o is always the numerical trap OID</li>
<li>$E follows translate_enterprise_oid_format, and $e is always the numerical enterprise OID</li>
<li>The enterprise column when logging to a database now follows the db_translate_enterprise setting</li>
<li>Fixed bug with $# to report the correct number of enterprise variables (was 1 lower than it should have been)</li>
<li>Fixed bug with handling traps that contain quoted values that span multiple lines</li>
<li>PID file now created (/var/run/snmptt.pid or ./snmptt.pid) when running in daemon mode on Linux / Unix.  snmptt-init.d script updated to remove the pid file when shutting down snmptt.</li>
<li>Added <a href="http://www.nagios.org">Nagios</a> / Netsaint integration documentation</li>
<li>Added contrib folder</li>
<li>SNMPTTConvertMIB<ul>
<li>Now prints the variables contained in each trap definition unless --no_variables is set.  When using --net_snmp_perl it will also resolve the Syntax (INTEGER, OCTETSTR etc) and Description.  If it's an INTEGER, will also print out the enumeration tags if any exist.</li>
<li>Improved compatability with MIB files</li>
</ul>
</li>
</ul>
<h2><strong>0.7</strong> <strong>- April 17th</strong><strong>, 2003</strong></h2>
<ul>
<li>Fixes a vulnerability that prevents the possibility of injected commands contained in traps from being executed when using the EXEC feature</li>
<li>Added the ability for traps passed from snmptrapd or loaded from the snmptt.conf files to contain symbolic OIDs such as linkDown and IF-MIB::linkUp.  This feature requires the UCD-SNMP / Net-SNMP Perl module</li>
<li>Added the configuration options <strong>translate_trap_oid</strong> and translate_oids to have the trap OID and OID values contained in the trap variables converted from numerical OID to symbolic form before logging.  This feature requires the UCD-SNMP / Net-SNMP Perl module</li>
<li>Added support for logging of traps using PostgreSQL via DBI / DBD::PgPP</li>
<li>Added REGEX keyword support to allow user definable search and replace on FORMAT / EXEC lines</li>
<li>NODES entry can now contain a CIDR address (eg: 192.168.10.0/23), or a network range (192.168.10.0-192.168.11.255)</li>
<li>NODES entry can now contain a mix of host names, IP addresses, CIDR addresses, network ranges and filenames</li>
<li>Added the ability to force a reload of the configuration files while running in daemon mode by placing a file called !reload in the spool directory</li>
<li>Added snmptt-net-snmp-test program to perform various translations of numeric and symbolic OIDS to assist with determining if the installed Perl module<br />
    will function as expected with SNMPTT</li>
<li>Fixed bug that prevented quoted text from being logged correctly to SQL databases</li>
<li>Fixed bug that would prevent the translation of integer values to enumeration tags and variable name substitutions when using Net-SNMP 5.0.x</li>
<li>SNMPTTConvertMIB<ul>
<li>FORMAT / EXEC line can now contain any of the following:<ul>
<li>--#SUMMARY or DESCRIPTION (use DESCRIPTION only if --#SUMMARY does not exist)</li>
<li>description or --#SUMMARY (use --#SUMMARY only if DESCRIPTION does not exist)</li>
<li>--#SUMMARY and DESCRIPTION</li>
<li>DESCRIPTION and --#SUMMARY</li>
</ul>
</li>
<li>When using the DESCRIPTION to build the FORMAT / EXEC line, can now choose between using the first line of the DESCRIPTION field, or the first x number of sentences</li>
<li>The use of the --#SUMMARY and DESCRIPTION line for the FORMAT / EXEC line can be disabled</li>
<li>Support for multiple --#SUMMARY lines</li>
<li>Support for --#SEVERITY lines</li>
<li>The default of using the $* wildcard can be disabled</li>
<li>Conversion of the DESCRIPTION section to SDESC / EDESC can be disabled</li>
<li>EXEC line can be specified on the command line</li>
<li>NODES line can be specified on the command line</li>
</ul>
</li>
</ul>
<h2><strong>0.6 - March</strong> <strong>25th, 2003</strong></h2>
<ul>
<li>Logging:</li>
<li>
<ul>
<li>Added support for logging of traps using DBD::ODBC</li>
<li>Fixed bug with Win32::ODBC connection not being closed on exit of SNMPTT</li>
<li>MySQL code cleanup</li>
<li>Added support for logging traps to the NT Event Log including the ability to select the Event Log level based on the severity level defined in the snmptt.conf file</li>
<li>Improved syslog support by adding the ability to select the syslog level based on the severity level defined in the snmptt.conf file</li>
<li>Added syslog and NT Event Log support for SNMPTT 'system' events such as startup, shutdown, errors handling spool directory / files, database connectivity errors etc</li>
<li>Added the option <strong>keep_unlogged_traps</strong> to have SNMPTT erase the spooled trap file only after it successfully logs to at least one or all log systems.  This will help prevent traps from being lost due to logging problems.</li>
</ul>
</li>
<li>Added ability to translate integer values to enumeration tags defined in MIB files.  This feature requires the UCD-SNMP / Net-SNMP Perl module</li>
<li>Added new variable substitutions: <strong>$v_n_</strong> (variable name), <strong>$+<em>n</em></strong>(variable name:value), <strong>$-<em>n</em></strong> (variable name (type):value), <strong>$+*</strong> (same as $+<em>n</em> but wildcard), and <strong>$-*</strong> (same as $-<em>n</em> but wildcard).  Translation of the variable name using the MIB requires the UCD-SNMP / Net-SNMP Perl module.</li>
<li>If a variable is passed from snmptrapd that is blank, snmptt will replace it with (null)</li>
<li>Fixed bug that would prevent variables numbered 10 or higher from being translated correctly</li>
<li>Fixed bug with handling trap data that contains spaces but is not inside of quotes</li>
<li>Code cleanup to remove Perl warnings (-w)</li>
<li>Added separate debug file for snmptthandler</li>
<li>Cleaned up defaults code for snmptthandler</li>
<li>Added examples folder containg a sample snmptt.conf file and sample trap file</li>
<li>Added FAQ section to this document</li>
<li>Snmpttconvertmib<ul>
<li>Code cleanup</li>
<li>Now uses new command line arguments (snmpttconvertmib -h for help).</li>
<li>Can now use either snmptranslate or the SNMP Perl module (Net-SNMP) to process MIB files</li>
<li>Can now add a NODES line when converting MIB files</li>
<li>Now checks the version of snmptranslate before converting the mib to ensure snmptranslate is called correctly</li>
<li>Fixed bug which would cause the last notification of a v2 MIB file not to be converted correctly</li>
</ul>
</li>
</ul>
<h2><strong>0.5 - February 12th, 2003</strong></h2>
<ul>
<li>Spool file list sorted before processing to ensure traps are processed in the order they are received when in daemon mode</li>
<li>Added <strong>use_trap_time</strong> variable to config file for daemon mode to have SNMPTT use either the time from the spool file, or the current time.  Changed SNMPTTHANDLER to output the current date and time on the first line of the spool file</li>
<li>Fixed bug with default variable settings being ignored.  Defaults were not being set correctly if variable was not defined in the .ini file.</li>
<li>Fixed bug with SNMPTT ignoring the daemon mode parameter in the .ini file</li>
<li>Fixed bug with Nodes list not being flushed out for each processed trap when running in daemon mode</li>
<li>Added <strong>strip_domain</strong> and <strong>strip_domain_list</strong> configuration options to enable / disable the removal of the domain name from the host name passed to SNMPTT.  Defaults to disabled (do not  strip domain name)</li>
<li>SNMPTTCONVERTMIB now prepends the contents of the --#TYPE line (if present) to the --#SUMMARY line to provide a more descriptive FORMAT / EXEC line</li>
</ul>
<h2><strong>0.4 - November 18th, 2002</strong></h2>
<ul>
<li>Variable substitution changes:</li>
<li>
<ul>
<li>$X = Date, $x = Time instead of $x being both date and time</li>
<li>$N = Event name instead of $S</li>
<li>Added $c, $@, $O, $o, $ar, $R, $aR, $G, $S</li>
</ul>
</li>
<li>Configuration moved to a .ini file</li>
<li>MySQL support via DBI under Linux and Windows</li>
<li>ODBC support via Win32::ODBC under Windows</li>
</ul>
<h2><strong>0.3 - September 11th, 2002</strong></h2>
<ul>
<li>Daemon mode support for SNMPTT.  When running as a daemon, SNMPTTHANDLER script is used to spool traps from SNMPTRAPD.</li>
<li>SNMPTTCONVERTMIB utility to convert trap / notify definitions from MIB files</li>
<li>Sample trap file (sample-trap) for testing</li>
<li>Command line options to SNMPTT</li>
<li>SNMPTT now strips UDP: and :<em>port</em> from IP addresses when using Net-SNMP 5.0+</li>
<li>NODES files can now contain comments</li>
<li>NODES files can now contain either host names or IP addresses</li>
<li>You can now have multiple definitions of the same trap so that different hosts / nodes can have different actions or one host have multiple actions</li>
<li>Configuration file can now contain a list of other configuration files to load</li>
</ul>
<h2><strong>0.2 - July 10th, 2002</strong></h2>
<ul>
<li>Improved debugging output</li>
<li>Severity substitution bug fix</li>
<li>SNMP V2 trap bug fix</li>
<li>UCD-SNMP v4.2.3 problem workaround</li>
</ul>
<h2><strong>0.1 - April 18th, 2002</strong></h2>
<ul>
<li>Initial release</li>
</ul>
<h1><a name="Upgrading"></a>Upgrading</h1>
<h2><strong>v1.4.2 to v1.5beta1</strong></h2>
<p>To upgrade from v1.4.2 to v1.5 you should:</p>
<ol>
<li>Replace <strong>snmptt</strong> with the new version.  Make sure the file is executable (<strong>chmod +x <em>filename</em></strong>).</li>
<li>Replace <strong>snmptthandler-embedded</strong> with the new version.  Make sure the file is executable (<strong>chmod +x <em>filename</em></strong>).</li>
<li>Replace <strong>snmpttconvertmib</strong> with the new version.  Make sure the file is executable (<strong>chmod +x <em>filename</em></strong>).</li>
<li>For systemd systems, replace the <strong>snmptt.service</strong> service file with the new version.</li>
<li>Backup your <strong>snmptt.ini</strong> file, replace it with the new version, and make any necessary configuration changes to it.</li>
<li>Secure your <strong>/etc/snmp</strong> or <strong>/etc/snmptt</strong> folder as described in the <strong>Securing SNMPTT</strong> section of the documentation.</li>
<li>To enable IPv6 support, set <strong>ipv6_enable = 1</strong> in <strong>snmptt.ini</strong>. </li>
</ol>
<p>Notes:  </p>
<ol>
<li>Starting with v1.5, you can use <strong>/etc/snmptt/</strong> instead of <strong>/etc/snmp/</strong> for your <strong>snmptt.ini</strong> file.  </li>
<li>DNS now requires the Perl module <strong>IO::Socket::IP</strong>.  </li>
<li>IPv6 requires the Perl module <strong>Net::IP</strong>.  </li>
</ol>
<h2><strong>v1.4 to v1.4.2</strong></h2>
<p>To upgrade from v1.4 to v1.4,1, you should:</p>
<ol>
<li>Replace <strong>snmptt</strong> with the new version.  Make sure the file is executable (<strong>chmod +x <em>filename</em></strong>).</li>
<li>Confirm that the <strong>snmptt</strong> user account is a member of the appropriate groups such as <strong>nagios</strong> for Nagios and <strong>icingacmd</strong> for Icinga2.</li>
<li>Backup your <strong>snmptt.ini</strong> file and then add the new option <strong>daemon_gid = snmptt</strong> below <strong>daemon_uid</strong>.</li>
<li>
<p>To increase security:</p>
<ul>
<li>If you are not currently using daemon mode and are running as root, please switch to daemon mode or run as different user such as <strong>snmptt</strong>.</li>
<li>
<p>Secure the spool folder with:</p>
</li>
<li>
<p><strong>chown -R snmptt.snmptt /var/spool/snmptt</strong></p>
</li>
<li>
<p><strong>chmod -R 750 /var/spool/snmptt</strong></p>
</li>
<li>
<p>Secure the /etc/snmp folder with</p>
</li>
<li>
<p><strong>chown -R root.root /etc/snmp</strong></p>
</li>
<li><strong>chmod 755 /etc/snmp</strong></li>
<li><strong>chown snmptt.snmptt /etc/snmp/snmptt*</strong></li>
<li><strong>chmod 660 /etc/snmp/snmptt*</strong></li>
</ul>
</li>
</ol>
<h2><strong>v1.3 to v1.4</strong></h2>
<p>To upgrade from v1.3 to v1.4, you should:</p>
<ol>
<li>Replace <strong>snmptt</strong> and <strong>snmptthandler-embedded</strong> with the new versions.  Make sure the files are executable (<strong>chmod +x <em>filename</em></strong>).</li>
<li>Backup your <strong>snmptt.ini</strong> 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.</li>
<li>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.</li>
<li>The new <strong>snmptt.ini</strong> option net_snmp_perl_cache_enable defaults to on, so disable if required.</li>
</ol>
<h2><strong>v1.2 to v1.3</strong></h2>
<p>To upgrade from v1.2 to v1.3, you should:</p>
<ol>
<li>Replace <strong>snmptt</strong> and <strong>snmpttconvertmib</strong> with the new versions.  Make sure the files are executable (<strong>chmod +x <em>filename</em></strong>).</li>
<li>Copy snmptt-init.d to /etc/init.d/snmptt.  Make sure the file is executable (<strong>chmod +x <em>filename</em></strong>).</li>
<li>Optional:  Install and configure the snmptthandler-embedded trap handler.  See <a href="snmptt.html#Installation-Unix-Embedded">Embedded handler</a> for details.</li>
<li>Backup your <strong>snmptt.ini</strong> 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.</li>
<li>Setup log rotation by copying snmptt.logrotate to /etc/logrotate.d/snmptt and modifying as needed for the correct paths, rotate frequency etc.</li>
<li>Enable any new features in <strong>snmptt.ini</strong> as required.</li>
</ol>
<h2><strong>v1.1 to v1.2</strong></h2>
<p>To upgrade from v1.1 to v1.2, you should:</p>
<ol>
<li>Replace <strong>snmptt</strong> and <strong>snmpttconvertmib</strong> with the new versions contained in the v1.2 package.  Make sure the files are executable (<strong>chmod +x <em>filename</em></strong>).</li>
<li>Backup your <strong>snmptt.ini</strong> file, replace it with the new version, and make any necessary configuration changes to it.</li>
<li>Enable any new features in <strong>snmptt.ini</strong> as required.</li>
<li>For Linux and Unix (or anything non-Windows), if you are using the <strong>daemon_uid</strong> option in <strong>snmptt.ini</strong>, 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.</li>
<li>For Linux and Unix (or anything non-Windows), the <strong>snmptt.ini</strong> <strong>exec_escape</strong> option is enabled by default which will escape wildcard characters (* and ?) for EXEC, PREEXEC and the unknown_trap_exec commands. Disable if required.</li>
</ol>
<h2><strong>v1.0 to v1.1</strong></h2>
<p>To upgrade from v1.0 to v1.1, you should:</p>
<ol>
<li>Replace <strong>snmptt</strong> and <strong>snmpttconvertmib</strong> with the new versions contained in the v1.1 package.  Make sure the files are executable (<strong>chmod +x <em>filename</em></strong>).</li>
<li>Backup your <strong>snmptt.ini</strong> file, replace it with the new version, and make any necessary configuration changes to it.</li>
<li>Enable any new features in <strong>snmptt.ini</strong> as required.</li>
</ol>
<h2><strong>v0.9 to v1.0</strong></h2>
<p>To upgrade from v0.9 to v1.0, you should:</p>
<ol>
<li>Replace <strong>snmptt</strong>, <strong>snmpttconvert</strong>, <strong>snmpttconvertmib</strong>, and <strong>snmptthandler</strong> with the new versions contained in the v1.0 package.  Make sure the files are executable (<strong>chmod +x <em>filename</em></strong>).</li>
<li>Backup your <strong>snmptt.ini</strong> file, replace it with the new version, and make any necessary configuration changes to it</li>
<li>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 <strong>mysql_ping_on_insert</strong>, <strong>postgresql_ping_on_insert</strong> or <strong>dbd_odbc_ping_on_insert</strong> to 0 in <strong>snmptt.ini</strong>. If you do not want the database to be pinged periodically, set <strong>mysql_ping_interval</strong>, <strong>postgresql_ping_interval</strong> or <strong>dbd_odbc_ping_interval</strong> to 0 in <strong>snmptt.ini</strong>.</li>
<li>Enable any new features in snmptt.ini as required</li>
<li>Test and report any issues to alex_b@users.sourceforge.net, or open a bug report at <a href="http://sourceforge.net/tracker/?group_id=51473&amp;atid=463393">Sourceforge</a>.</li>
</ol>
<h2><strong>v0.8 to v0.9</strong></h2>
<p>To upgrade from v0.8 to v0.9, you should:</p>
<ol>
<li>Replace snmptt with the new version contained in the v0.9 package.  Make sure the file is executable (chmod +x filename)</li>
<li>Backup your <strong>snmptt.ini</strong> file, replace it with the new version, and make any necessary configuration changes to it</li>
<li>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</li>
<li>Enable any new features in snmptt.ini as required</li>
<li>Test and report any issues to alex_b@users.sourceforge.net, or open a bug report at <a href="http://sourceforge.net/tracker/?group_id=51473&amp;atid=463393">Sourceforge</a>.</li>
</ol>
<h2><strong>v0.7 to v0.8</strong></h2>
<p>To upgrade from v0.7 to v0.8, you should:</p>
<ol>
<li>Replace snmptt and snmpttconvertmib with the new versions contained in the v0.8 package.  Make sure the files are executable (chmod +x filename)</li>
<li>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)</li>
<li>Backup your <strong>snmptt.ini</strong> file, replace it with the new version, and make any necessary configuration changes to it</li>
<li>In your snmptt.ini file, configure translate_log_trap_oid with translate_trap_oid value from old snmptt.ini</li>
<li>In your snmptt.ini file, configure translate_value_oids with translate_oids value from old snmptt.ini</li>
<li>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</li>
<li>In your snmptt.conf files, replace any $A with $aA unless you want agent host names to be used instead of IP addresses</li>
<li>In your snmptt.conf files, replace any $E with $e unless you want Enterprise trap OID in symbolic format</li>
<li>In your snmptt.conf files, replace any $O with $o unless you want Trap OID in symbolic format</li>
<li>In your snmptt.conf files, append a g to the end of all REGEX lines to enable global search and replace</li>
<li>Review other translate settings in snmptt.ini</li>
<li>Enable any new features in snmptt.ini as required</li>
<li>If you are using database logging, add a new column called trapoid</li>
<li>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</li>
<li>Test and report any issues to alex_b@users.sourceforge.net, or open a bug report at <a href="http://sourceforge.net/tracker/?group_id=51473&amp;atid=463393">Sourceforge</a>.</li>
</ol>
<h2><strong>v0.6 to v0.7</strong></h2>
<p>To upgrade from v0.6 to v0.7, you should:</p>
<ol>
<li>Replace <strong>SNMPTT</strong> and <strong>SNMPTTCONVERTMIB</strong> with the new versions contained in the v0.7 package</li>
<li>Backup your <strong>snmptt.ini</strong> file, replace it with the new version, and make any necessary configuration changes to it</li>
<li>Enable any new features in snmptt.ini as required</li>
<li>Test and report any issues to alex_b@users.sourceforge.net, or open a bug report at <a href="http://sourceforge.net/tracker/?group_id=51473&amp;atid=463393">Sourceforge</a>.</li>
</ol>
<h2><strong>v0.5 to v0.6</strong></h2>
<p>To upgrade from v0.5 to v0.6, you should:</p>
<ol>
<li>Replace <strong>SNMPTTHANDLER, SNMPTT</strong> and <strong>SNMPTTCONVERTMIB</strong> with the new versions contained in the v0.6 package</li>
<li>Backup your <strong>snmptt.ini</strong> file, replace it with the new version, and make any necessary configuration changes to it</li>
<li>Enable any new features in snmptt.ini as required</li>
<li>Test and report any issues to alex_b@users.sourceforge.net, or open a bug report at <a href="http://sourceforge.net/tracker/?group_id=51473&amp;atid=463393">Sourceforge</a>.  </li>
</ol>
<h2><strong>v0.4 to v0.5</strong></h2>
<p>To upgrade from v0.1, v0.2 to v0.3 to v0.4, you should:</p>
<ol>
<li>Set <strong>use_trap_time</strong> to <strong>0</strong> to have SNMPTT operate the same as v0.4, or leave as 1 (recommended default) and test</li>
<li>Replace <strong>both</strong> <strong>SNMPTTHANDLER</strong> and <strong>SNMPTT</strong> with the new versions contained in the v0.5 package</li>
<li>Backup your <strong>snmptt.ini</strong> file, replace it with the new version, and make any necessary configuration changes to it</li>
</ol>
<h2><strong>v0.1, v0.2 or v0.3 to v0.4</strong></h2>
<p>To upgrade from v0.1, v0.2 to v0.3 to v0.4, you should:</p>
<ol>
<li>In your snmptt.conf file, replace all <strong>$x</strong> with <strong>$x $X</strong> (see What's New section)</li>
<li>In your snmptt.conf file, replace all <strong>$S</strong> with <strong>$N (</strong>see What's New section)</li>
<li>Configure the snmptt.ini as described in this file - configuration options are no longer stored in the snmptt and snmptthandler scripts</li>
<li>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</li>
</ol>
<h1><a name="Installation"></a>Installation</h1>
<h2><a name="Installation-Overview"></a>Overview</h2>
<p>SNMPTT can be run in either daemon mode or standalone mode.  Daemon mode is recommended.  See <a href="#Modes-of-Operation" title="Modes of Operation">Modes of Operation</a> for more details.  </p>
<p>The following outlines the general steps required to install and configure SNMPTT:  </p>
<ol>
<li>Install Net-SNMP and SNMPTT as described below.</li>
<li>Copy the sample snmptt.conf to your configuration folder.</li>
<li><a href="#Configuration-Options">Modify snmptt.ini</a> to include the <strong>snmptt.conf</strong> file and set any desired options.</li>
<li>Start SNMPTT.</li>
<li>Test using the sample trap file.</li>
<li>Create an <strong>snmptt.conf</strong> file <a href="#SNMPTT.CONF-Configuration-file-format">by hand</a>, or using <a href="#SNMP-Trap-Translator-Convert-MIB">snmpttconvertmib</a>.</li>
<li>Configure your network devices to send traps to the Net-SNMP / SNMPTT machine.</li>
<li>Initiate a trap on your network device and check the SNMPTT log files for the result.</li>
<li>Secure the SNMPTT installation.</li>
</ol>
<h2><a name="Installation-Unix"></a>Installation - Unix</h2>
<h3><a name="Installation-Unix-Package"></a>Package Manager</h3>
<p>Packages are available for most Linux distributions and FreeBSD.  Check your package manager to see if they have the latest version.  If not, you can manually install using the steps below.</p>
<h3><a name="Installation-Unix-Manual"></a>Manual installation</h3>
<p>Steps:</p>
<ol>
<li>
<p>Install Net-SNMP and the Perl modules as listed int the <a href="#Requirements">Requirements</a> section.</p>
</li>
<li>
<p>Copy <strong>snmptt</strong> to /usr/sbin/ and ensure it is executable (<strong>chmod +x snmptt</strong>):</p>
<pre><code>cp snmptt /usr/sbin/
chmod +x /usr/sbin/snmptt
</code></pre>
</li>
<li>
<p>Create snmptt user:</p>
<ol>
<li>
<p>RedHat based systems:</p>
<pre><code>adduser -r snmptt
</code></pre>
</li>
<li>
<p>Debian based systems:</p>
<pre><code>adduser --system --group snmptt
</code></pre>
</li>
</ol>
</li>
<li>
<p>Create /etc/snmptt and set permissions.  Note: Starting with v1.5, you can use /etc/snmptt/ instead of /etc/snmp/ for your snmptt.ini file.m</p>
<pre><code>mkdir /etc/snmptt
chown -R snmptt.snmptt /etc/snmptt
chmod 750 /etc/snmptt
</code></pre>
</li>
<li>
<p>Copy <strong>snmptt.ini</strong> to <strong>/etc/snmptt</strong> and edit the options inside the file:</p>
<pre><code>cp snmptt.ini /etc/snmptt/
</code></pre>
<p>and</p>
<pre><code>vi /etc/snmptt/snmptt.ini
</code></pre>
</li>
<li>
<p>Either copy <strong>examples/snmptt.conf.generic</strong> to <strong>/etc/snmptt/snmptt.conf</strong> (renaming the file during the copy) or use the touch command to create the file (<strong>touch /etc/snmptt/snmptt.conf</strong>).</p>
<pre><code>cp examples/snmptt.conf.generic /etc/snmptt/snmptt.conf
</code></pre>
<p>or</p>
<pre><code>touch /etc/snmptt/snmptt.conf
</code></pre>
</li>
<li>
<p>Create the log folder <strong>/var/log/snmptt/</strong>:</p>
<pre><code>mkdir /var/log/snmptt
chown -R snmptt.snmptt /var/log/snmptt
chmod -R 750 /var/log/snmptt
</code></pre>
</li>
<li>
<p>Create the spool folder <strong>/var/spool/snmptt/</strong>:</p>
<pre><code>mkdir /var/spool/snmptt/
chown -R snmptt.snmptt /var/spool/snmptt
chmod -R 750 /var/spool/snmptt
</code></pre>
</li>
<li>
<p>Startup scripts are included for SystemD (uses <strong>systemctl</strong> to control services) and SysVinit systems.  Select one depending on your distribution.</p>
<ol>
<li>
<p>Systemd:</p>
<ol>
<li>
<p>Copy the script and remove executable flag if set.</p>
<pre><code>cp snmptt.service /usr/lib/systemd/system/snmptt.service
chmod -x /usr/lib/systemd/system/snmptt.service
</code></pre>
</li>
<li>
<p>Enable the service:</p>
<pre><code>systemctl enable snmptt.service
</code></pre>
</li>
<li>
<p>Start the service:</p>
<pre><code>systemctl start snmptt.service
</code></pre>
</li>
</ol>
</li>
<li>
<p>SysVinit:</p>
<ol>
<li>
<p>Copy the script:</p>
<pre><code>cp snmptt-init.d /etc/rc.d/init.d/snmptt
</code></pre>
</li>
<li>
<p>Add the service using chkconfig:</p>
<pre><code>chkconfig --add snmptt
</code></pre>
</li>
<li>
<p>Configure the service to start at runlevel 2345:</p>
<pre><code>chkconfig --level 2345 snmptt on
</code></pre>
</li>
<li>
<p>Start the service:</p>
<pre><code>service snmptt start
</code></pre>
</li>
</ol>
</li>
<li>
<p>Manually starting without SystemD or SysVinit:</p>
<pre><code>snmptt --daemon
</code></pre>
</li>
</ol>
</li>
<li>
<p>Check syslog to ensure SNMPTT started properly:</p>
<pre><code>grep snmptt /var/log/messages
grep snmptt /var/log/syslog
</code></pre>
<p>Example log messages:</p>
<pre><code>snmptt-sys[31442]: SNMPTT 1.5.2 started
snmptt-sys[31442]: Loading /etc/snmptt/snmptt.conf
snmptt-sys[31442]: Finished loading 64 lines from /etc/snmptt/snmptt.conf
snmptt: PID file: /var/run/snmptt.pid
snmptt-sys[31446]: Configured daemon_uid: snmptt
snmptt-sys[31446]: Changing to UID: snmptt (1002), GID: snmptt (1002)
</code></pre>
<p>Note: If SNMPTT doesn't start, try running it manually from the shell prompt to see if there are any missing Perl modules.</p>
</li>
<li>
<p>A log rotation script is included which can be used to rotate the log files on Red Hat and other systems.  Copy the file to the logrotate.d directory (renaming the file during the copy):</p>
<pre><code>cp snmptt.logrotate /etc/logrotate.d/snmptt
</code></pre>
<p>Edit the <strong>/etc/logrotate.d/snmptt</strong> and update the paths and rotate frequency as needed.</p>
<pre><code>vi /etc/logrotate.d/snmptt
</code></pre>
</li>
</ol>
<h3><a name="Installation-Unix-Handlers"></a>Net-SNMP handlers</h3>
<p>Next we will install the Net-SNMP handler.  There are two options:  The standard handler and the embedded handler.  The embedded handler is recommended.</p>
<h4><a name="Installation-Unix-Standard"></a>Net-SNMP Standard handler</h4>
<p>The standard handler is a small Perl program that is called by snmptrapd each time a trap is received when using daemon mode.  The limitations of this handler are:  </p>
<ul>
<li>Each time a trap is received, a process must be created to run the snmptthandler program and snmptt.ini is read each time</li>
<li>SNMPv3 EngineID and names are not passed by snmptrapd to snmptthandler</li>
</ul>
<p>The benefits of using this handler are:  </p>
<ul>
<li>Does not require Net-SNMP embedded Perl for snmptrapd</li>
<li>Has been around since v0.1 of SNMPTT</li>
<li>Sufficient for most installations</li>
</ul>
<p>Steps:</p>
<ol>
<li>
<p>Copy <strong>snmptthandler</strong> to /usr/sbin/ and ensure it is executable (<strong>chmod +x snmptthandler</strong>).</p>
<pre><code>cp snmptthandler /usr/sbin/
chmod +x /usr/sbin/snmptthandler
</code></pre>
</li>
<li>
<p>Manually start <strong>snmptthandler</strong> to make sure there are no missing Perl modules:</p>
<pre><code>/usr/sbin/snmptthandler
</code></pre>
<p>Missing Perl module example:</p>
<pre><code>Can't locate Time/HiRes.pm in @INC (you may need to install the Time::HiRes module) (@INC contains: /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5) at /usr/sbin/snmptthandler-embedded line 42.
BEGIN failed--compilation aborted at /usr/sbin/snmptthandler-embedded line 42.
</code></pre>
<p>No missing Perl modules example.  Errors below can be ignored:</p>
<pre><code>SNMPTTHANDLER started: Sun Feb 27 10:39:39 2022

s = 1645976379, usec = 360145
s_pad = 1645976379, usec_pad = 360145

Data received:
</code></pre>
<p>Press control-c to exit the handler.</p>
</li>
<li>
<p>For <strong>SNMPTT daemon mode</strong>:</p>
<ol>
<li>
<p>Modify (or create) the Net-SNMP <strong>snmptrapd.conf</strong> file by adding the following lines:</p>
<pre><code>disableAuthorization yes
traphandle default /usr/sbin/snmptthandler
</code></pre>
<p>Note:  You can locate the <strong>snmptrapd.conf</strong> file by running:</p>
<pre><code>snmpconf -i
</code></pre>
</li>
</ol>
</li>
<li>
<p>For <strong>SNMPTT standlone mode</strong>: </p>
<ol>
<li>
<p>Modify (or create) the Net-SNMP snmptrapd.conf file by adding the following lines:</p>
<pre><code>disableAuthorization yes
traphandle default /usr/sbin/snmptt
</code></pre>
<p>Note:  You can locate the <strong>snmptrapd.conf</strong> file by running:</p>
<pre><code>snmpconf -i
</code></pre>
<p>Note:   It is possible to configure snmptrapd to execute snmptt based on the specific trap received, but using the default option is preferred</p>
</li>
</ol>
</li>
<li>
<p>Permanently change snmptrapd to use the <strong>-On</strong> option by modifying the startup script:</p>
<ol>
<li>
<p>Systemd:  </p>
<p>Edit the unit file and add the <strong>-On</strong> option:</p>
<pre><code>systemctl edit --full snmptrapd.service
</code></pre>
<p>Change:</p>
<pre><code>Environment=OPTIONS="-Lsd"
</code></pre>
<p>to:</p>
<pre><code>Environment="OPTIONS=-Lsd -On"
</code></pre>
<p>Note:  Move the first quote to before OPTIONS.</p>
</li>
<li>
<p>SysVinit:  </p>
<p>Edit the <strong>/etc/rc.d/init.d/snmptrapd</strong> file and add <strong>"-On"</strong> to <strong>OPTIONS</strong>:</p>
<pre><code>vi /etc/rc.d/init.d/snmptrapd
</code></pre>
<p>Change:</p>
<pre><code>OPTIONS="-Lsd"
</code></pre>
<p>to:</p>
<pre><code>OPTIONS="-Lsd -On"
</code></pre>
</li>
</ol>
<p>Note:  <strong>The -On option is recommended</strong>.  This will make snmptrapd pass OIDs in numeric form and prevent SNMPTT from having to translate the symbolic name to numerical form.  If the <strong>Net-SNMP Perl module</strong> is not installed, then you MUST use the <strong>-On</strong> switch.  Depending on the version of Net-SNMP, some symbolic names may not translate correctly.  See the FAQ for more info.</p>
<p>As an alternative, you can edit the Net-SNMP configuration file <strong>/etc/snmp/snmp.conf</strong> to include the line: <strong>printNumericOids 1. </strong> This setting will take effect no matter what is used on the command line.</p>
</li>
<li>
<p>Start / restart snmptrapd using systemctl or service:</p>
<pre><code>systemctl restart snmptrapd
service snmptrapd restart
</code></pre>
</li>
<li>
<p>Check syslog to ensure SNMPTT started properly:</p>
<pre><code>grep snmptrapd /var/log/messages
grep snmptrapd /var/log/syslog
</code></pre>
</li>
<li>
<p>Follow the steps in the section <a href="#SecuringSNMPTT">Securing SNMPTT</a> to ensure SNMPTT has been configured securely.</p>
</li>
</ol>
<h4><a name="Installation-Unix-Embedded"></a>Net-SNMP Embedded handler</h4>
<p>The embedded handler is a small Perl program that is loaded directly into snmptrapd when snmptrapd is started.  The limitations of this handler are:  </p>
<ul>
<li>Requires embedded Perl for snmptrapd</li>
<li>Only works with daemon mode</li>
</ul>
<p>The benefits of using this handler are:  </p>
<ul>
<li>The handler is loaded and initialized when snmptrapd is started, so there is less overhead as a new process does not need to be created and initialization is done only once (loading of snmptt.ini).</li>
<li>SNMPv3 EngineID and names variables are available in SNMPTT (B* variables)</li>
</ul>
<p>Steps:</p>
<ol>
<li>
<p>Make sure <strong>snmptrapd</strong> has embedded Perl support enabled.  To see if it's enabled in your installation, type:</p>
<pre><code>snmptrapd -H 2&gt;&amp;1 | grep perl
</code></pre>
<p>If it returns <strong>perl   PERLCODE</strong> then embedded Perl is enabled.  If it's not enabled, you will need to find another Net-SNMP package with it enabled, or compile Net-SNMP using the <strong>--enable-embedded-perl</strong> configure option.</p>
</li>
<li>
<p>Copy <strong>snmptthandler-embedded</strong> to /usr/sbin/.  It does not need to be executable as it is called directly by snmptrapd.</p>
<pre><code>cp snmptthandler-embedded /usr/sbin/
chmod +x /usr/sbin/snmptthandler-embedded
</code></pre>
</li>
<li>
<p>Manually start <strong>snmptthandler-embedded</strong> to make sure there are no missing Perl modules:</p>
<pre><code>/usr/sbin/snmptthandler-embedded
</code></pre>
<p>Missing Perl module example:</p>
<pre><code>Can't locate Time/HiRes.pm in @INC (you may need to install the Time::HiRes module) (@INC contains: /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5) at /usr/sbin/snmptthandler-embedded line 42.
BEGIN failed--compilation aborted at /usr/sbin/snmptthandler-embedded line 42.
</code></pre>
<p>No missing Perl modules example.  Errors below can be ignored:</p>
<pre><code>Bareword "NETSNMPTRAPD_HANDLER_OK" not allowed while "strict subs" in use at /usr/sbin/snmptthandler-embedded line 264.
Execution of /usr/sbin/snmptthandler-embedded aborted due to compilation errors.
</code></pre>
</li>
<li>
<p>Configure snmptrapd and install the service:  </p>
<p>Modify (or create) the Net-SNMP snmptrapd.conf file by adding the lines below.  Note: You can locate the <strong>snmptrapd.conf</strong> file by running <strong>snmpconf -i</strong>.</p>
<pre><code>disableAuthorization yes
perl do "/usr/sbin/snmptthandler-embedded"
</code></pre>
</li>
<li>
<p>Permanently change snmptrapd to use the <strong>-On</strong> option by modifying the startup script:</p>
<ol>
<li>
<p>Systemd:  </p>
<p>Edit the unit file and add the <strong>-On</strong> option:</p>
<pre><code>systemctl edit --full snmptrapd.service
</code></pre>
<p>Change:</p>
<pre><code>Environment=OPTIONS="-Lsd"
</code></pre>
<p>to:</p>
<pre><code>Environment="OPTIONS=-Lsd -On"
</code></pre>
<p>Note:  Move the first quote to before OPTIONS.</p>
</li>
<li>
<p>SysVinit:  </p>
<p>Edit the <strong>/etc/rc.d/init.d/snmptrapd</strong> file and add <strong>"-On"</strong> to <strong>OPTIONS</strong>:</p>
<pre><code>vi /etc/rc.d/init.d/snmptrapd
</code></pre>
<p>Change:</p>
<pre><code>OPTIONS="-Lsd"
</code></pre>
<p>to:</p>
<pre><code>OPTIONS="-LsdOn"
</code></pre>
</li>
</ol>
<p>Note:  <strong>The -On option is recommended</strong>.  This will make snmptrapd pass OIDs in numeric form and prevent SNMPTT from having to translate the symbolic name to numerical form.  If the <strong>Net-SNMP Perl module</strong> is not installed, then you MUST use the <strong>-On</strong> switch.  Depending on the version of Net-SNMP, some symbolic names may not translate correctly.  See the FAQ for more info.</p>
<p>As an alternative, you can edit the Net-SNMP configuration file <strong>/etc/snmp/snmp.conf</strong> to include the line: <strong>printNumericOids 1. </strong> This setting will take effect no matter what is used on the command line.</p>
</li>
<li>
<p>Start / restart snmptrapd using systemctl or service:</p>
<pre><code>systemctl restart snmptrapd
service snmptrapd restart
</code></pre>
</li>
<li>
<p>Check syslog to ensure SNMPTT started properly:</p>
<pre><code>grep snmptrapd /var/log/messages
grep snmptrapd /var/log/syslog
</code></pre>
</li>
<li>
<p>Follow the steps in the section <a href="#SecuringSNMPTT">Securing SNMPTT</a> to ensure SNMPTT has been configured securely.</p>
</li>
</ol>
<p>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:  <strong>log_enable</strong>, <strong>syslog_enable</strong> and <strong>syslog_system_enable</strong>. </p>
<h3><a name="Installation-Unix-Testing"></a>Testing</h3>
<ol>
<li>
<p>Copy a sample trap file to the spool folder:</p>
<pre><code>cp examples/'#sample-trap.generic.daemon' /var/spool/snmptt/
</code></pre>
</li>
<li>
<p>Check the snmptt.log file for the trap.  Note:  The date is from the sample trap file.</p>
<pre><code>tail /var/log/snmptt/snmptt.log

Mon Aug 16 10:06:35 2004 .1.3.6.1.6.3.1.1.5.3 Normal "Status Events" router01 - Link down on interface 3.  Admin state: 2.  Operational state: 3
</code></pre>
</li>
<li>
<p>Check syslog for the trap from <strong>snmptt</strong>.  Note:  The date is from the sample trap file.</p>
<pre><code>grep 'snmptt\[' /var/log/messages
grep 'snmptt\[' /var/log/syslog

Feb 27 10:29:52 server1 snmptt[83096]: .1.3.6.1.6.3.1.1.5.3 Normal "Status Events" router01 - Link down on interface 3.  Admin state: 2.  Operational state: 3
</code></pre>
</li>
<li>
<p>Generate a <strong>linkDown</strong> trap using <strong>snmptrap</strong>:</p>
<pre><code>snmptrap -v 2c -c public 127.0.0.1 .1.3.6.1.6.3.1.1.5.3 .1.3.6.1.6.3.1.1.5.3 ifIndex i 2 ifAdminStatus i 1 ifOperStatus i 2
</code></pre>
</li>
<li>
<p>Check the syslog file for the trap from <strong>snmptrapd</strong>:</p>
<pre><code>grep snmptrapd /var/log/messages
grep snmptrapd /var/log/syslog

Feb 27 11:04:03 bink snmptrapd[84697]: 2022-02-27 11:04:03 localhost [UDP: [127.0.0.1]:40290-&gt;[127.0.0.1]:162]:#012.1.3.6.1.6.3.1.1.4.1.0 = OID: .1.3.6.1.6.3.1.1.5.3#011.1.3.6.1.2.1.2.2.1.1 = INTEGER: 2#011.1.3.6.1.2.1.2.2.1.7 = INTEGER: up(1)#011.1.3.6.1.2.1.2.2.1.8 = INTEGER: down(2)
</code></pre>
<p>Note:  If you see the error 'SELinux is preventing /usr/sbin/snmptrapd from write access on the directory snmptt', then SELinux needs to be configured to allow snmptrapd to write to the spool folder.</p>
</li>
<li>
<p>Check the snmptt.log file for the trap:</p>
<pre><code>tail /var/log/snmptt/snmptt.log

Sun Feb 27 11:04:03 2022 .1.3.6.1.6.3.1.1.5.3 Normal "Status Events" 127.0.0.1 - Link down on interface 2.  Admin state: 1.  Operational state: 2
</code></pre>
</li>
<li>
<p>Check syslog for the trap from <strong>snmptt</strong>.</p>
<pre><code>grep 'snmptt\[' /var/log/messages
grep 'snmptt\[' /var/log/syslog

Feb 27 11:04:07 server1 snmptt[83096]: .1.3.6.1.6.3.1.1.5.3 Normal "Status Events" 127.0.0.1 - Link down on interface 2.  Admin state: 1.  Operational state: 2
</code></pre>
</li>
</ol>
<p><strong>Troubleshooting:</strong></p>
<ol>
<li>Enable debug mode by defining both <strong>DEBUGGING = 0</strong> and <strong>DEBUGGING_FILE = /var/log/snmptt/snmptt.debug</strong> in <strong>/etc/snmptt/snmptt.ini</strong> and restart <strong>snmptt</strong>.  If the file is not created, check syslog for errors.  Either the DEBUGGING_FILE path is incorrect or there is a permissions error creating the debug log file.</li>
<li>Make sure permissions have been set for the various folders and files.</li>
<li>SELinux may interfere with <strong>snmptrapd</strong> and <strong>snmptt</strong>.  Disable or reconfigure at your own discretion.</li>
<li>Test running <strong>snmptt</strong> and the handlers as explained above to make sure there are no missing Perl modules.</li>
</ol>
<h2><a name="Installation-Windows"></a>Installation - Windows</h2>
<p>The Net-SNMP trap receiver does not currently support embedded Perl, so only the standard trap handler can be used with Windows.</p>
<ol>
<li>
<p>Create the directory c:\snmp and copy <strong>snmptt</strong> and <strong>snmptthandler</strong> to it.</p>
<pre><code>md c:\snmp
copy snmptt c:\snmpt\
copy snmptthandler c:\snmp\
</code></pre>
</li>
<li>
<p>Copy <strong>snmptt.ini-nt</strong> to <strong>%SystemRoot%\snmptt.ini</strong> (c:\windows\snmptt.ini) and edit the options inside the file.</p>
<pre><code>cp snmptt.ini-nt %SystemRoot%\snmptt.ini
</code></pre>
</li>
<li>
<p>Either copy examples\snmptt.conf.generic to c:\snmp\snmptt.conf (renaming the file during the copy) or create the file using notepad.</p>
<pre><code>copy examples\snmptt.conf.generic c:\snmp\snmptt.conf  
notepad c:\snmp\snmptt.conf
</code></pre>
</li>
<li>
<p>Create the log folder <strong>c:\snmp\log\</strong>.</p>
<pre><code>md c:\snmp\log
</code></pre>
</li>
<li>
<p>For <strong>SNMPTT standlone mode</strong>:</p>
<ol>
<li>
<p>Modify (or create) the Net-SNMP snmptrapd.conf file by adding the following line:</p>
<pre><code>traphandle default perl c:\snmp\snmptt
</code></pre>
<p>Note:   It is possible to configure snmptrapd to execute snmptt based on the specific trap received, but using the default option is preferred</p>
</li>
</ol>
</li>
<li>
<p>For <strong>SNMPTT daemon mode</strong>:</p>
<ol>
<li>Modify (or create) the Net-SNMP snmptrapd.conf file by adding the following line:<pre><code>traphandle default perl c:\snmp\snmptthandler
</code></pre>
</li>
</ol>
</li>
<li>
<p>Create the spool folder <strong>c:\snmptt\spool\</strong>.</p>
<pre><code>md c:\snmptt\spool
</code></pre>
</li>
<li>
<p>Launch snmptt using:</p>
<pre><code>snmptt --daemon
</code></pre>
</li>
<li>
<p>Start SNMPTRAPD using the command line:  SNMPTRAPD -On:</p>
<pre><code>snmptrapd -On
</code></pre>
<p>Note:  <strong>The -On option is recommended</strong>.  This will make snmptrapd pass OIDs in numeric form and prevent SNMPTT from having to translate the symbolic name to numerical form.  If the <strong>Net-SNMP Perl module</strong> is not installed, then you MUST use the <strong>-On</strong> switch.  Depending on the version of Net-SNMP, some symbolic names may not translate correctly.  See the FAQ for more info.</p>
<p>As an alternative, you can edit the Net-SNMP configuration file <strong>/etc/snmp/snmp.conf</strong> to include the line: <strong>printNumericOids 1. </strong> This setting will take effect no matter what is used on the command line.</p>
</li>
<li>
<p>Follow the steps in the section <a href="#SecuringSNMPTT">Securing SNMPTT</a> to ensure SNMPTT has been configured securely.</p>
</li>
</ol>
<p><strong>Windows EventLog:</strong></p>
<p>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.</p>
<p>The Event Message File is aincluded with SNMPTT is a pre-compiled binary DLL.  To compile the DLL yourself, see 'Compiling' below.</p>
<p>To install the DLL:</p>
<ol>
<li>
<p>Backup your system</p>
</li>
<li>
<p>Make sure Event Viewer is not open</p>
</li>
<li>
<p>Copy <strong>bin\snmptt-eventlog.dll</strong> to <strong>%windir%\system32</strong></p>
<pre><code>copy bin\snmptt-eventlog.dll %windir%\system32\
</code></pre>
</li>
<li>
<p>Launch the Registry Editor</p>
</li>
<li>
<p>Go to '<strong>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Eventlog\Application</strong>'</p>
</li>
<li>
<p>Create a new subkey (under Application) called <strong>SNMPTT</strong></p>
</li>
<li>
<p>Inside of the <strong>SNMPTT</strong> key, create a new String Value called <strong>EventMessageFile</strong>.  Give it a value of <strong>%windir%\system32\snmptt-eventlog.dll.</strong></p>
</li>
<li>
<p>Inside of the <strong>SNMPTT</strong> key, create a new DWORD Value called <strong>TypesSupported</strong>.  Give it a value of <strong>7</strong>.</p>
</li>
</ol>
<p>To un-install the DLL:</p>
<ol>
<li>
<p>Backup your system</p>
</li>
<li>
<p>Make sure Event Viewer is not open</p>
</li>
<li>
<p>Launch the Registry Editor</p>
</li>
<li>
<p>Go to '<strong>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Eventlog\Application</strong>'</p>
</li>
<li>
<p>Delete the key <strong>SNMPTT</strong></p>
</li>
<li>
<p>Delete the file <strong>%windir%\system32\snmptt-eventlog.dll</strong></p>
<pre><code>del %windir%\system32\snmptt-eventlog.dll
</code></pre>
</li>
</ol>
<p>Compiling snmptt-eventlog.dll (MS Visual C++ required)</p>
<ol>
<li>
<p>If your environment is not already set up for command line compilation, locate <strong>vcvars32.bat</strong>, start a command prompt, and execute it (vcvars32.bat).</p>
</li>
<li>
<p>cd into the directory where snmptt-eventlog.mc is located (included with SNMPTT) and execute the following commands:</p>
<pre><code>mc snmptt-eventlog.mc

rc /r snmptt-eventlog.rc

link /nodefaultlib /INCREMENTAL:NO /release /nologo -base:0x60000000 -machine:i386 -dll -noentry -out:snmptt-eventlog.dll snmptt-eventlog.res
</code></pre>
</li>
<li>
<p>Install the DLL as described above</p>
</li>
</ol>
<p><strong>Windows Service:</strong></p>
<p>To configure SNMPTT as a service under Windows, follow these steps.  More information can be obtained from the Windows Resource Kit.</p>
<ol>
<li>
<p>Install the Windows resource kit</p>
</li>
<li>
<p>Copy the <strong>srvany.exe</strong> program to <strong>c:\windows\system32</strong> from <strong>c:\Program Files\Resource Kit *</strong></p>
<pre><code>copy srvany.exe c:\%windir%\system32\
</code></pre>
</li>
<li>
<p>Install the SNMPTT service using:</p>
<pre><code>instsrv SNMPTT c:\windows\\system32\srvany.exe
</code></pre>
</li>
<li>
<p>Configure the service:</p>
<ol>
<li>
<p>Launch <strong>REGEDIT</strong></p>
</li>
<li>
<p>Go to <strong>HKLM\SYSTEM\CurrentControlSet\SNMPTT</strong></p>
</li>
<li>
<p>Create a key called: <strong>Parameters</strong></p>
</li>
<li>
<p>Inside of Parameters, create a Sting Value (REG_SZ) called <strong>Application</strong> with the value of: <strong>c:\perl\bin\perl.exe</strong></p>
</li>
<li>
<p>Inside of Parameters, create a Sting Value (REG_SZ) called <strong>AppParameters</strong> with the value of: <strong>c:\snmp\snmptt --daemon</strong></p>
</li>
</ol>
</li>
<li>
<p>Start the service from the control panel, or from a command prompt, type:</p>
<pre><code>net start snmptt
</code></pre>
</li>
<li>
<p>Note:  To remove the service, type:</p>
<pre><code>instsrv SNMPTT remove
</code></pre>
</li>
</ol>
<h1><a name="SecuringSNMPTT"></a>Securing SNMPTT</h1>
<p>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.  </p>
<p>For Linux and Unix, if you start SNMPTT as root, a user called 'snmptt' should be created and the <strong>snmptt.ini</strong> option <strong>daemon_uid</strong> should be set to the numerical user id (eg: 500) or textual user id (snmptt). <strong>Only define daemon_uid if starting snmptt using root.</strong>  </p>
<p>If you start SNMPTT as a non-root user, then <strong>daemon_uid</strong> is not required (and will probably not work).  </p>
<p>When using <strong>daemon_uid</strong> 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 <strong>daemon_uid</strong>. If the system syslog (<strong>syslog_system_enable</strong>) 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 looking the snmptt processes using <strong>ps</strong>.</p>
<p>For Windows, a local or domain user account called 'snmptt' should be created.  If running as a Windows 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.  </p>
<p>The script <strong>snmptthandler</strong> which is called from Net-SNMP's snmptrapd will be executed in the same security context as <strong>snmptrapd</strong>.</p>
<p>The SNMPTT user should be configured with the following permissions:</p>
<ul>
<li>read / delete access to spool directory to be able to read new traps, and delete processed traps</li>
<li>read access to configuration files (snmptt.ini and all snmptt.conf files)</li>
<li>write access to log folder /var/log/snmptt/ or c:\snmp\log\.</li>
<li>any other permissions required for EXEC statements to execute</li>
</ul>
<p>If <strong>snmptrapd</strong> is run as a non root / administrator, it should be configured with the following permissions below.  Note:  SELinux may prevent writing to the folder.</p>
<ul>
<li>write access to spool directory</li>
</ul>
<p>Grant access and secure the spool folder with:</p>
<pre><code>    chown -R snmptt.snmptt /var/spool/snmptt
    chmod -R 750 /var/spool/snmptt
</code></pre>
<p>Grant access and secure the log folder with:</p>
<pre><code>    chown -R snmptt.snmptt /var/log/snmptt
    chmod -R 750 /var/log/snmptt
</code></pre>
<p>If you are using <strong>/etc/snmp</strong> to store the SNMPTT configuration files, secure the folder with:</p>
<pre><code>    chown -R root.root /etc/snmp
    chmod 755 /etc/snmp
    chown snmptt.snmptt /etc/snmp/snmptt*
    chmod 660 /etc/snmp/snmptt*
</code></pre>
<p>If you are using <strong>/etc/snmptt</strong> to store the SNMPTT configuration files, secure folder with:</p>
<pre><code>    chown -R snmptt.snmptt /etc/snmptt
    chmod 750 /etc/snmptt
</code></pre>
<p>Note:  Starting with v1.5, you can use <strong>/etc/snmptt/</strong> instead of <strong>/etc/snmp/</strong> for your <strong>snmptt.ini</strong> file:</p>
<p>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.</p>
<h1><a name="Configuration-Options"></a>Configuration Options - snmptt.ini</h1>
<p>As mentioned throughout this document, configuration options are set by editing the <strong>snmptt.ini</strong> file.</p>
<p>For Linux / Unix, the following directories are searched to locate <strong>snmptt.ini</strong>:</p>
<blockquote>
<p><strong>/etc/snmptt/</strong><br />
<strong>/etc/snmp/</strong><br />
<strong>/etc/</strong><br />
<strong>/usr/local/etc/snmp/</strong><br />
<strong>/usr/local/etc/</strong></p>
</blockquote>
<p>Note:  <strong>/etc/snmptt/</strong> is new for v1.5.</p>
<p>For Windows, the file should be in <strong>%SystemRoot%\</strong>.  For example, <strong>c:\windows</strong>.</p>
<p>If an alternative location is desired, the <strong>snmptt.ini</strong> file path can be set on the command line using the <strong>-ini=</strong> parameter.  See <a href="#Command-line-arguments">Command Line Arguments</a>.</p>
<p>A sample <strong>snmptt.ini</strong> is provided in this package.  See the <a href="#Installation">Installation</a> section.</p>
<p>This file does not document all configuration options available in <strong>snmptt.ini</strong>.  Please view the <strong>snmptt.ini</strong> for a complete description of all options. </p>
<p>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:  <strong>log_enable</strong>, <strong>syslog_enable</strong> and <strong>syslog_system_enable</strong>.</p>
<h1><a name="Modes-of-Operation"></a>Modes of Operation</h1>
<p>SNMPTT can be run in two modes:  daemon mode and standalone mode.  Daemon mode is recommended.</p>
<h2><a name="Modes-of-Operation-Daemon"></a>Daemon mode</h2>
<p>When SNMPTT is run in daemon mode, the snmptrapd.conf file would contain a traphandle statement such as:</p>
<pre><code>traphandle default /usr/sbin/snmptthandler
</code></pre>
<p>or when using the embedded handler:</p>
<pre><code>perl do "/usr/sbin/snmptthandler-embedded"
</code></pre>
<p>When a trap is received by SNMPTRAPD, the trap is passed to the SNMPTT handler script which performs the following tasks:</p>
<ul>
<li>reads trap passed from snmptrapd</li>
<li>writes the trap in a new unique file to a spool directory such as /var/spool/snmptt</li>
<li>quits</li>
</ul>
<p>SNMPTT running in daemon mode performs the following tasks:</p>
<ul>
<li>loads configuration file(s) containing trap definitions at startup</li>
<li>reads traps passed from spool directory</li>
<li>searches traps for a match</li>
<li>logs, executes EXEC statement etc</li>
<li>sleeps for 5 seconds (configurable)</li>
<li>loops back up to 'reads traps passed from spool directory'</li>
</ul>
<p>Using SNMPTTHANDLER and SNMPTT in daemon mode, a large number of traps per minute would be handled easily.</p>
<p>Running SNMPTT with the --daemon command line option or setting the <strong>mode</strong> variable in the <strong>snmptt.ini</strong> file to <strong>daemon</strong> will cause SNMPTT to run in daemon mode.</p>
<p>By setting the snmptt.ini variable <strong>use_trap_time</strong> to <strong>1</strong> (default), the date and time used for logging will be the date and time passed inside the trap spool file.  If <strong>use_trap_time</strong> is set to <strong>0</strong>, the date and time that the trap was <em>processed</em> by SNMPTT is used.  Setting <strong>use_trap_time</strong> to <strong>0</strong> can result in inaccurate time stamps in log files due to the length of time SNMPTT sleeps between spool directory polling.</p>
<p>Note:  When running on a <strong>non</strong> Windows platform, SNMPTT will fork to the background and create a pid file in /var/run/snmptt.pid if <strong>daemon_fork</strong> 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.</p>
<p>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.</p>
<p>Statistical logging of total traps received, total traps translated and total unknown traps can be enabled by setting the <strong>statistics_interval</strong> 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.</p>
<p>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 <strong>statistics_interval</strong>.  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.  </p>
<h2><a name="Modes-of-Operation-Standalone"></a>Standalone mode</h2>
<p>To use SNMPTT in standalone mode, the snmptrapd.conf file would contain a traphandle statement such as:</p>
<pre><code>    traphandle default /usr/sbin/snmptt
</code></pre>
<p>When a trap is received by snmptrapd, the trap is passed to the <strong>/usr/sbin/snmptt</strong> script.  SNMPTT performs the following tasks:</p>
<ul>
<li>reads trap passed from snmptrapd</li>
<li>loads configuration file(s) containing trap definitions</li>
<li>searches traps for a match</li>
<li>logs, executes EXEC statements etc</li>
<li>snmptt exits</li>
</ul>
<p>With a 450 Mhz PIII (way back in 1998) and a 9000 line snmptt.conf containing 566 unique traps (EVENTs), it took 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.  Daemon mode should be used instead.</p>
<p>Running SNMPTT without the <strong>--daemon</strong> command line option will result standalone mode unless the <strong>mode</strong> variable in the <strong>snmptt.ini</strong> file is set to <strong>daemon</strong>.  For standalone mode, the <strong>mode</strong> variable in the <strong>snmptt.ini</strong> file should be set <strong>standalone</strong>.</p>
<p>Note: Enabling the Net-SNMP Perl module will greatly increase the startup time of SNMPTT.  Daemon mode is recommended.</p>
<h1><a name="Command-line-arguments"></a>Command line arguments</h1>
<p>The following command line arguments are supported:</p>
<pre><code>Usage:  
    snmptt [&lt;options&gt;]  
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)
</code></pre>
<h1><a name="Logging"></a>Logging</h1>
<h2><a name="LoggingStandard"></a>Logging - Standard</h2>
<p>Translated traps can be sent to standard output and to a log file.  The output format is:</p>
<blockquote>
<p><strong><em>date trap-oid severity category hostname</em> - <em>translated-trap</em></strong></p>
</blockquote>
<p>To configure standard output or regular logging, edit the <strong>snmptt.ini</strong> file and modify the following variables:</p>
<pre><code>stdout_enable
log_enable
log_file
log_format
</code></pre>
<p>The output format can be changed from the above default by modifying the <strong>log_format</strong> setting.  See snmptt.ini for details.</p>
<h2><a name="LoggingUnknown"></a>Logging - Unknown traps</h2>
<p>Logging of unrecognized traps is possible.  This would be used mainly for troubleshooting purposes.</p>
<p>To configure unknown trap logging, edit the snmptt.ini file and modify the following variables:</p>
<pre><code>enable_unknown_trap_log
unknown_trap_log_file
</code></pre>
<p>Unknown traps can be logged to a SQL table as described in the <a href="#LoggingDatabase">Database</a> section.  </p>
<h2><a name="LoggingSyslog"></a>Logging - Syslog</h2>
<p>Translated traps can be sent to syslog.  The format of the entries will be similar to above without the date (as syslog adds the date):</p>
<blockquote>
<p><strong><em>trap-oid severity category hostname</em> - <em>translated-trap</em></strong></p>
</blockquote>
<p>Syslog entries normally start with: <strong>date hostname snmptt[pid]:</strong> </p>
<p>To configure syslog, edit the snmptt ini file and modify the following variables:</p>
<pre><code>syslog_enable
syslog_facility
syslog_level
syslog_module
syslog_remote_dest *
syslog_remote_port *
syslog_remote_proto *
syslog_rfc_format *
syslog_app *
syslog_format
</code></pre>
<p>(*) Only applicable when using <strong>syslog_module</strong> = 1</p>
<p>When using the default <strong>syslog_module</strong> setting of 0, syslog messages are logged to the local system using Unix sockets following the RFC3164 standard.</p>
<p>To enable RFC5424 or remote syslog server support, set <strong>syslog_module</strong> to 1 and define the (*) settings.  Be sure to enable UDP or TCP syslog reception in your syslog server.  See snmptt.ini for details on each setting.</p>
<p>SNMPTT system errors and messages such as startup, shutdown, trap statistics etc can be sent to syslog by editing the snmptt.ini file and modifying the following variables:</p>
<pre><code>syslog_system_enable
syslog_system_facility
syslog_system_level
</code></pre>
<p>Syslog system entries normally start with: <strong>date hostname snmptt-sys[pid]:</strong></p>
<p>The following errors are logged:</p>
<blockquote>
<p>SNMPTT (version) started <strong>(*)</strong><br />
Unable to enter spool dir <em>x</em> <strong>(*)</strong><br />
Unable to open spool dir <em>x</em> <strong>(*)</strong><br />
Unable to read spool dir <em>x</em> <strong>(*)</strong><br />
Could not open trap file <em>x</em> <strong>(*)</strong><br />
Unable to delete trap file <em>x</em> from spool dir <strong>(*)</strong><br />
Unable to delete !reload file spool dir <strong>(*)<br />
</strong>Unable to delete !statistics file spool dir <strong>(*)</strong><br />
Reloading configuration file(s) <strong>(*)</strong><br />
SNMPTT (version) shutdown <strong>(*)</strong><br />
Loading <em>snmpttconfigfile</em> <strong>(*)</strong><br />
Could not open configuration file: <em>snmpttconfigfile</em><strong>(*)</strong><br />
Finished loading <em>x</em> lines from <em>snmpttconfigfile</em> <strong>(*)</strong><br />
MySQL error: Unable to connect to database<br />
SQL error: Unable to connect to DSN<br />
Can not open log file <em>logfile</em><br />
MySQL error: Unable to perform PREPARE<br />
MySQL error: Unable to perform INSERT INTO (EXECUTE)<br />
DBI DBD::ODBC error: Unable to perform INSERT INTO<br />
Win32::ODBC error: Unable to perform INSERT INTO<br />
PostgreSQL error: Unable to connect to database<br />
PostgreSQL error: Unable to perform PREPARE<br />
PostgreSQL error: Unable to perform INSERT INTO (EXECUTE)  </p>
<p><strong>* (daemon mode only)</strong></p>
</blockquote>
<h2><a name="LoggingEventLog"></a>Logging - Windows EventLog</h2>
<p>When running under Windows, translated traps can be sent to the 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):</p>
<blockquote>
<p><strong>trap-oid severity category hostname translated-trap</strong></p>
</blockquote>
<p>To configure eventlog support, edit the snmptt ini file and modify the following variables:</p>
<pre><code>eventlog_enable
eventlog_type
</code></pre>
<p>SNMPTT system errors can be sent to the Event Log by editing the snmptt.ini file and modifying the following variables:</p>
<pre><code>eventlog_system_enable
</code></pre>
<p>The following errors are logged.  Note that each error contains a unique EventID:  </p>
<blockquote>
<p>EventID 0: SNMPTT (version) started <strong>(*)</strong><br />
EventID 3: Unable to enter spool dir <em>x</em> <strong>(*)</strong><br />
EventID 4: Unable to open spool dir <em>x</em> <strong>(*)</strong><br />
EventID 5: Unable to read spool dir <em>x</em> <strong>(*)</strong><br />
EventID 6: Could not open trap file <em>x</em> <strong>(*)</strong><br />
EventID 7: Unable to delete trap file <em>x</em> from spool dir <strong>(*)</strong><br />
EventID 20: Unable to delete !reload file spool dir <strong>(*)</strong><br />
EventID 21: Unable to delete !statistics file spool dir <strong>(*)</strong><br />
EventID 8: Reloading configuration file(s) <strong>(*)</strong><br />
EventID 1: SNMPTT (version) shutdown <strong>(*)</strong><br />
EventID 9: Loading <em>snmpttconfigfile</em> <strong>(*)</strong><br />
EventID 10: Could not open configuration file: <em>snmpttconfigfile</em><strong>(*)</strong><br />
EventID 11: Finished loading <em>x</em> lines from <em>snmpttconfigfile</em><strong>(*)</strong>
EventID 12: MySQL error: Unable to connect to database<br />
EventID 13: SQL error: Unable to connect to DSN <em>dsn</em><br />
EventID 14: Can not open log file <em>logfile</em><br />
EventID 23: MySQL error: Unable to perform PREPARE<br />
EventID 15: MySQL error: Unable to perform INSERT INTO (EXECUTE)<br />
EventID 16: DBI DBD::ODBC error: Unable to perform INSERT INTO<br />
EventID 17: Win32::ODBC error: Unable to perform INSERT INTO<br />
EventID 18: PostgreSQL error: Unable to connect to database<br />
EventID 22: PostgreSQL error: Unable to perform PREPARE<br />
EventID 19: PostgreSQL error: Unable to perform INSERT INTO (EXECUTE)  </p>
<p><strong>* (daemon mode only)</strong></p>
</blockquote>
<p>Note:</p>
<blockquote>
<p>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 <a href="#Installation%20-%20Windows">Installation section for Windows</a>.</p>
</blockquote>
<h2><a name="LoggingDatabase"></a>Logging - Database</h2>
<p>Translated and unrecognized traps can be sent to a database.  MySQL (tested under Linux), PostgreSQL (tested under Linux) and ODBC (tested under Windows) can be used.</p>
<p>After configuring database logging below, you can also enable unknown trap logging by editing the <strong>snmptt.ini</strong> file and modifying the following variables:</p>
<pre><code>enable_unknown_trap_log
db_unknown_trap_format
</code></pre>
<h2><a name="LoggingDatabase-MySQL"></a>DBD::MySQL</h2>
<p>To configure SNMPTT for MySQL, modify the following variables in the snmptt.ini file.</p>
<pre><code>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
</code></pre>
<p>Note:  Sample values are defined in the default ini file.  Defining mysql_dbi_table_unknown is optional.</p>
<p>The following MySQL script will create the database and table. Permissions etc should also be defined. Run '<strong>mysql</strong>' as root and enter:</p>
<pre><code>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));
</code></pre>
<p>Note: To store the traptime as a real date/time (<strong>DATETIME</strong> data type), change 'traptime VARCHAR(30),' to 'traptime DATETIME,' and set <strong>date_time_format_sql</strong> in <strong>snmptt.ini</strong> to <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>Note: If you do not want the auto-incrementing id column, remove the 'id INT...' line.</p>
<p>If logging of unknown traps to a SQL table is required, create the <strong>snmptt_unknown</strong> table using:</p>
<pre><code>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));
</code></pre>
<p>Note: To store the traptime as a real date/time (<strong>DATETIME</strong> data type), change 'traptime VARCHAR(30),' to 'traptime DATETIME,' and set <strong>date_time_format_sql</strong> in <strong>snmptt.ini</strong> to <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>If logging of statistics to a SQL table is required, create the <strong>snmptt_statistics</strong> table using:</p>
<pre><code>USE snmptt;

DROP TABLE snmptt_statistics;  
CREATE TABLE snmptt_statistics (  
stat_time VARCHAR(30),  
total_received BIGINT,  
total_translated BIGINT,  
total_ignored BIGINT,  
total_skipped BIGINT,  
total_unknown BIGINT);
</code></pre>
<p>Note: Only include <strong>total_skipped</strong> if <strong>unknown_trap_nodes_match_mode</strong> is set to <strong>1</strong>.</p>
<p>Note: To store the stat_time as a real date/time (<strong>DATETIME</strong> data type), change 'stat_time VARCHAR(30),' to 'stat_time DATETIME,' and set <strong>stat_time_format_sql</strong> in <strong>snmptt.ini</strong> to <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>Note: The variable lengths I have chosen above should be sufficient, but they may need to be increased depending on your environment.</p>
<p>To add a user account called '<strong>snmptt</strong>' with a password of '<strong>mytrap</strong>' for use by SNMPTT, use the following SQL statement:</p>
<pre><code>GRANT ALL PRIVILEGES ON \*.\* TO 'snmptt'@'localhost' IDENTIFIED BY 'mytrap';
</code></pre>
<h2><a name="LoggingDatabase-PostgreSQL"></a>DBD::PgPP (PostgreSQL)</h2>
<p>To configure SNMPTT for PostgreSQL, modify the following variables in the snmptt.ini file.</p>
<pre><code>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
</code></pre>
<p>Note: Sample values are defined in the default ini file. Defining <strong>postgresql_dbi_table_unknown</strong> is optional.</p>
<p>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.</p>
<pre><code>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
</code></pre>
<p>Note: To store the traptime as a real date/time (<strong>timestamp</strong> data type), change 'traptime VARCHAR(30),' to 'traptime timestamp,' and set <strong>date_time_format_sql</strong> in <strong>snmptt.ini</strong> to <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>If logging of unknown traps to a SQL table is required, create the snmptt_unknown table using:  </p>
<pre><code>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
</code></pre>
<p>Note: To store the traptime as a real date/time (<strong>timestamp</strong> data type), change 'traptime VARCHAR(30),' to 'traptime timestamp,' and set <strong>date_time_format_sql</strong> in <strong>snmptt.ini</strong> to <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>If logging of statistics to a SQL table is required, create the snmptt_statistics table using:  </p>
<pre><code>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_skipped BIGINT,  
total_unknown BIGINT);

GRANT ALL ON snmptt_statistics TO snmptt;  
\q
</code></pre>
<p>Note: Only include <strong>total_skipped</strong> if <strong>unknown_trap_nodes_match_mode</strong> is set to <strong>1</strong>.</p>
<p>Note: To store the stat_time as a real date/time (<strong>timestamp</strong> data type), change 'stat_time VARCHAR(30),' to 'stat_time timestamp,' and set <strong>stat_time_format_sql</strong> in <strong>snmptt.ini</strong> to <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>The variable lengths I have chosen above should be sufficient, but they may need to be increased depending on your environment.  </p>
<h2><a name="LoggingDatabase-ODBC"></a>DBD::ODBC</h2>
<p>SNMPTT can access ODBC data sources using either the DBD::ODBC module on Linux and Windows, or the WIN32::ODBC module on Windows.</p>
<p>To configure SNMPTT for ODBC access using the module DBD::ODBC, modify the following variables in the snmptt script.</p>
<pre><code>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';
</code></pre>
<p>Note:   </p>
<p>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.  </p>
<p>Defining <strong>dbd_odbc</strong>_table_unknown is optional.  </p>
<p>Sample values are defined in the default ini file.</p>
<p>The following MS SQL Server / Access script can create the table inside an existing database.  Permissions etc should also be defined.</p>
<pre><code>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);
</code></pre>
<p>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 <strong>date_time_format_sql</strong> in <strong>snmptt.ini</strong> to a compatible format. For example: <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>If logging of unknown traps to a SQL table is required, create the snmptt_unknown table using:  </p>
<pre><code>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);
</code></pre>
<p>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 <strong>date_time_format_sql</strong> in <strong>snmptt.ini</strong> to a compatible format. For example: <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>If logging of statistics to a SQL table is required, create the snmptt_statistics table using:  </p>
<pre><code>CREATE TABLE snmptt_statistics (  
stat_time character(30) NULL,  
total_received BIGINT NULL,  
total_translated BIGINT NULL,  
total_ignored BIGINT NULL,  
total_skipped BIGINT NULL,  
total_unknown BIGINT NULL);
</code></pre>
<p>Note: Only include <strong>total_skipped</strong> if <strong>unknown_trap_nodes_match_mode</strong> is set to <strong>1</strong>.</p>
<p>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 <strong>stat_time_format_sql</strong> in <strong>snmptt.ini</strong> to a compatible format. For example: <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>All variables are inserted into the database using '<strong>INSERT INTO</strong>' 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.  </p>
<h2><a name="LoggingDatabase-Windows_ODBC"></a>Win32::ODBC</h2>
<p>SNMPTT can access ODBC data sources using either the DBD::ODBC module on Linux and Windows, or the WIN32::ODBC module on Windows.</p>
<p>To configure SNMPTT for MS SQL via ODBC on Windows, modify the following variables in the snmptt script.</p>
<pre><code>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';
</code></pre>
<p>Note:   </p>
<p>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.  </p>
<p>Defining <strong>sql_win32_odbc</strong>_table_unknown is optional.  </p>
<p>Sample values are defined in the default ini file.</p>
<p>The following MS SQL Server script can create the table inside an existing database.  Permissions etc should also be defined.</p>
<pre><code>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);
</code></pre>
<p>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 <strong>date_time_format_sql</strong> in <strong>snmptt.ini</strong> to a compatible format. For example: <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>If logging of unknown traps to a SQL table is required, create the snmptt_unknown table using:  </p>
<pre><code>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);
</code></pre>
<p>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 <strong>date_time_format_sql</strong> in <strong>snmptt.ini</strong> to a compatible format. For example: <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>If logging of statistics to a SQL table is required, create the snmptt_statistics table using:  </p>
<pre><code>CREATE TABLE snmptt_statistics (  
stat_time character(30) NULL,  
total_received BIGINT NULL,  
total_translated BIGINT NULL,  
total_ignored BIGINT NULL,  
total_skipped BIGINT NULL,  
total_unknown BIGINT NULL);
</code></pre>
<p>Note: Only include <strong>total_skipped</strong> if <strong>unknown_trap_nodes_match_mode</strong> is set to <strong>1</strong>.</p>
<p>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 <strong>stat_time_format_sql</strong> in <strong>snmptt.ini</strong> to a compatible format. For example: <strong>%Y-%m-%d %H:%M:%S</strong>.</p>
<p>All variables are inserted into the database using '<strong>INSERT INTO</strong>' 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.  </p>
<h1><a name="Executing-an-external-program"></a>Executing an external program</h1>
<p>An external program can be launched when a trap is received.  The command line is defined in the <strong>snmptt.conf</strong> configuration file.  For example, to send a page using QPAGE (<a href="http://www.qpage.org">http://www.qpage.org</a>), the following command line could be used:</p>
<pre><code>qpage -f TRAP notifygroup1 "$r $x $X Compaq Drive Array Spare Drive on controller $4, bus $5, bay $6 status is $3."
</code></pre>
<p>$r is translated to the hostname, $x is the current date, and $X is the current time (described in detail below).</p>
<p>To enable or disable the execution of EXEC definitions, edit the snmptt.ini file and modify the following variable:</p>
<pre><code>exec_enable
</code></pre>
<p>It is also possible to launch an external program when an unknown trap is received. This can be enabled by defining <strong>unknown_trap_exec</strong> in <strong>snmptt.ini</strong>. Passed to the command will be all standard and enterprise variables, similar to <strong>unknown_trap_log_file</strong> but without the newlines.</p>
<h1><a name="SNMPTT.CONF-Configuration-file-format"></a>SNMPTT.CONF Configuration file format</h1>
<p>The configuration file (usually /etc/snmp/snmptt.conf or c:\snmp\snmptt.conf) contains a list of all the defined traps.</p>
<p>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:</p>
<ul>
<li>create additional snmptt.conf files  </li>
<li>add the file names to the <strong>snmptt_conf_files</strong> section in the snmptt.ini file.</li>
</ul>
<p>For example:</p>
<pre><code>snmptt_conf_files = &lt;&lt;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
</code></pre>
<p>The syntax of the snmptt.conf file  is:</p>
<blockquote>
<p><strong>EVENT</strong> event_name event_OID "category" severity</p>
<p><strong>FORMAT</strong> format_string</p>
<p>[<strong>EXEC</strong> command_string]</p>
<p>[<strong>PREEXEC</strong> command_string]</p>
<p>[<strong>NODES</strong> sources_list]</p>
<p>[<strong>MATCH</strong> [MODE=[or | and]] | [$n:[!][(    ) | n | n-n | &gt; n | &lt; n | x.x.x.x | x.x.x.x-x.x.x.x | x.x.x.x/x]]</p>
<p>[<strong>REGEX</strong> (    )(    )[i][g][e]]</p>
<p>[<strong>SDESC</strong>]<br />
[<strong>EDESC</strong>]</p>
<p>Note: Lines starting with a # are treated as comments and will be ignored.</p>
</blockquote>
<p>Note:  The EVENT and FORMAT line are REQUIRED.  Commands in [] are optional.  Do NOT include the []s in the configuration file!</p>
<h2><a name="SNMPTT.CONF-EVENT"></a>EVENT</h2>
<p><strong>EVENT</strong> event_name event_OID "category" severity</p>
<p><strong>event_name:</strong></p>
<blockquote>
<p>Unique text label (alias) <strong>containing no spaces</strong>.  This would match the name on the TRAP-TYPE or NOTIFICATION-TYPE line in the MIB file when converted using <strong>snmpttconvertmib</strong>.</p>
</blockquote>
<p><strong>event_OID:</strong></p>
<blockquote>
<p>Object identifier string in dotted format or symbolic notation <strong>containing no spaces</strong>.</p>
<p>For example, a Compaq (enterprise .1.3.6.1.4.1.232) cpqHoGenericTrap trap (trap 11001) would be written as:</p>
<blockquote>
<p>.1.3.6.1.4.1.232.0.11001</p>
</blockquote>
<p>Symbolic names can also be used if the Net-SNMP Perl module is installed and enabled by setting <strong>net_snmp_perl_enable</strong> in the snmptt.ini file.  For example:</p>
<blockquote>
<p>linkDown</p>
<p>IF-MIB::linkDown</p>
</blockquote>
<p>Notes:</p>
<ul>
<li>
<p>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 <a href="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=722075&amp;group_id=12694&amp;atid=312694">Net-SNMP patch page</a>.  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.</p>
</li>
<li>
<p>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).</p>
</li>
<li>
<p>There can be multiple entries for the same trap OID in the configuration file.  If <strong>multiple_event</strong> is enabled in the snmptt.ini, then it will process all matching traps.  If <strong>multiple_event</strong> is disabled, only the first matching entry will be used.</p>
</li>
</ul>
<p>Wildcards in dotted format notation can  also be used.  For example:</p>
<blockquote>
<p>.1.3.6.1.4.1.232.1.2.*</p>
</blockquote>
<p>Notes:</p>
<ul>
<li>
<p>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.</p>
</li>
<li>
<p>If you want to capture all undefined traps, you can create a wildcard event at the end of your last snmptt.conf file using <strong>.*</strong>.  For example:</p>
</li>
</ul>
</blockquote>
<pre><code> EVENT unknown .* "Status Events" Normal
</code></pre>
<blockquote>
<ul>
<li>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.</li>
</ul>
</blockquote>
<p><strong>category:</strong></p>
<ul>
<li>
<p>Character string enclosed in double quotes (").  Used when logging output (see above).</p>
</li>
<li>
<p>If the category is "<strong>IGNORE</strong>", no action will take place even if the snmptt.conf contains FORMAT and / or EXEC statements.</p>
</li>
<li>
<p>If the category is "<strong>LOGONLY</strong>", the trap will be logged as usual, but the EXEC statements will be ignored.</p>
</li>
</ul>
<p>Note:   If you plan on using an external program such as Nagios, you probably do not want any traps defined with <strong>LOGONLY</strong> as the EXEC line would never be used to submit the passive service check.</p>
<p><strong>severity:</strong></p>
<ul>
<li>Character string of the severity of the event.  Used in the output when logging.  Example: Minor, Major, Normal, Critical, Warning.  The <strong>snmptt.ini</strong> contains options to match the syslog level or NT Event Log type to the severity level.</li>
</ul>
<h2><a name="SNMPTT.CONF-FORMAT"></a>FORMAT</h2>
<p><strong>FORMAT</strong> format_string</p>
<p>There can be only one FORMAT line per EVENT.</p>
<p>The format string is used to generate the text that will be logged to any of the supported logging methods.</p>
<p><a name="Variable-substitutions"></a>Variable substitution is performed on this string using the following variables:</p>
<blockquote>
<p>$A - Trap agent host name (<strong>see Note 1</strong>)<br />
$aA - Trap agent IP address<br />
$Be - securityEngineID (snmpEngineID) (<strong>see Note 7</strong>)<br />
$Bu - securityName (snmpCommunitySecurityName) (<strong>see Note 7</strong>)<br />
$BE - contextEngineID (snmpCommunityContextEngineID) (<strong>see Note 7</strong>)<br />
$Bn - contextName (snmpCommunityContextName) (<strong>see Note 7</strong>)<br />
$c - Category<br />
$C - Trap community string<br />
$D - Description text from SNMPTT.CONF or MIB file (<strong>see Note 6</strong>)<br />
$E - Enterprise trap OID in symbolic format<br />
$e  - Enterprise trap OID in number format (.1.3.6.1.4.1.<em>n</em>)<br />
$j  - Enterprise number (<em>n</em>)<br />
$Fa  - alarm (bell) (BEL)<br />
$Ff  - form feed (FF)<br />
$Fn  - newline (LF, NL)<br />
$Fr  - return (CR)<br />
$Ft  - tab (HT, TAB)<br />
$Fz  - Translated FORMAT line (EXEC, log_format and syslog_format only)<br />
$G  - Generic trap number (0 if enterprise trap)<br />
$S  - Specific trap number (0 if generic trap)<br />
$H  - Host name of the system running SNMPTT<br />
$N  - Event name defined in .conf file of matched entry<br />
$i  - Event OID defined in .conf file of matched entry (could be a wildcard OID)<br />
$O - Trap OID in symbolic format (<strong>see Note 4</strong>)<br />
$o - Trap OID in numerical format (<strong>see Note 4</strong>)<br />
$p<em>n</em> - PREEXEC result n (1-<em>n</em>)<br />
$pu<em>n</em> - Unknown trap PREEXEC result n (1-<em>n</em>).  See <strong>unknown_trap_preexec</strong> setting in <strong>snmptt.ini</strong>.<br />
$R, $r  - Trap hostname (<strong>see Note 1</strong>)<br />
$aR, $ar - IP address<br />
$s  - Severity<br />
$T  - Uptime:  Time since network entity was initialized<br />
$X  - Time trap was spooled (daemon mode) or current time (standalone mode)<br />
$x  - Date trap was spooled (daemon mode) or current date (standalone mode)<br />
$# - Number of (how many) variable-bindings in the trap<br />
$$  - Print a $<br />
$@ - Number of seconds since the epoch of when the trap was spooled (daemon mode) or the current time (standalone mode)<br />
$<em>n</em>  - Expand variable-binding n (1-<em>n</em>) (<strong>see Note 2,5</strong>)<br />
$+<em>n</em>  - Expand variable-binding n (1-<em>n</em>) in the format of <em>variable name:value</em> (<strong>see Note 2,3,5</strong>)<br />
$-<em>n</em>  - Expand variable-binding n (1-<em>n</em>) in the format of <em>variable name (variable type):value</em> (<strong>see Note 2,3,5</strong>)<br />
$v<em>n</em>  - Expand variable name of the variable-binding n (1-<em>n</em>)(<strong>see Note 3</strong>)<br />
$*  - Expand all variable-bindings (<strong>see Note 5</strong>)<br />
$+*  - Expand all variable-bindings in the format of <em>variable name:value</em> (<strong>see Note 2,3,5</strong>)<br />
$-*  - Expand all variable-bindings in the format of <em>variable name (variable type):value</em> (<strong>see Note 2,3,5</strong>)  </p>
</blockquote>
<p>Example:</p>
<blockquote>
<p>FORMAT NIC switchover to slot $3, port $4 from slot $5, port $6</p>
</blockquote>
<p>Notes:</p>
<blockquote>
<p>For the text log file, the output will be formatted as:</p>
<blockquote>
<p><strong><em>date time trap-OID severity category hostname - format</em></strong></p>
</blockquote>
<p>For all other log files except MySQL, DBD::ODBC and Win32::ODBC, the output will be formatted as:</p>
<blockquote>
<p><strong><em>trap-OID severity category hostname - format</em></strong></p>
</blockquote>
<p>For MySQL, DBD::ODBC and Win32::ODBC, the <strong>formatline</strong> column will contain only the <strong>format</strong> text.</p>
</blockquote>
<p>Note (1):</p>
<blockquote>
<p>See the section '<a href="#DNS">Name Resolution / DNS</a>' for important DNS information.</p>
</blockquote>
<p>Note (2):</p>
<blockquote>
<p>If  <strong>translate_integers</strong> is enabled in the <strong>snmptt.ini</strong> file, SNMPTT will attempt to convert integer values received in traps into text by performing a lookup in the MIB file.<br />
You must have the Net-SNMP Perl module installed for this to work and you must enable support for it by enabling <strong>net_snmp_perl_enable</strong> in the snmptt.ini file.  </p>
<p>For this feature to work, you must ensure 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 Net-SNMP is correctly configured to process all the required mibs.  This is configured in the Net-SNMP <strong>/etc/snmp/snmp.conf</strong> file.  Alternatively, you can try setting the <strong>mibs_enviroment</strong> variable in <strong>snmptt.ini</strong> to <strong>ALL</strong> (no quotes) to force all MIBS to be initialized at SNMPTT startup.</p>
<p>If <strong>translate_integers</strong> is enabled while using stand-alone mode, it may take longer to process each trap due to the initialization of the MIB files.</p>
</blockquote>
<p>Note (3):</p>
<blockquote>
<p>$v<em>n</em>, $+<em>n</em> and $-<em>n</em> variable names and variable type are translated into the text name by performing a lookup in the MIB file.  You must have the Net-SNMP Perl module installed for this to work and you must enable support for it by enabling <strong>net_snmp_perl_enable</strong> in the snmptt.ini file.  If <strong>net_snmp_perl_enable</strong> is not enabled, the $v<em>n</em> variable will be replaced with the text 'variable<em>n</em>' where <em>n</em> is the variable number (1+).</p>
<p>For the name translation to work, you must ensure Net-SNMP is configured correctly with all the required MIBS.  If the option is enabled and the correct name is not returned, ensure Net-SNMP is correctly configured to process all the required mibs.  This is configured in the Net-SNMP <strong>snmp.conf</strong> file.  Alternatively, you can try setting the <strong>mibs_enviroment</strong> variable in <strong>snmptt.ini</strong> to <strong>ALL</strong> (no quotes) to force all MIBS to be initialized at SNMPTT startup.</p>
</blockquote>
<p>Note (4):</p>
<blockquote>
<p>If  <strong>translate_trap_oid</strong> is enabled in the <strong>snmptt.ini</strong> 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 Net-SNMP Perl module installed for this to work and you must enable support for it by enabling <strong>net_snmp_perl_enable</strong> in the snmptt.ini file.  If <strong>net_snmp_perl_enable</strong> is not enabled, it will default to using the numeric OID.   </p>
<p>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 <a href="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=722075&amp;group_id=12694&amp;atid=312694">Net-SNMP patch page</a>.</p>
</blockquote>
<p>Note (5):</p>
<blockquote>
<p>If  <strong>translate_oids</strong> is enabled in the <strong>snmptt.ini</strong> file, SNMPTT will attempt to convert any numeric OIDs found inside the variables passed inside the trap to symbolic form.  You must have the Net-SNMP Perl module installed for this to work and you must enable support for it by enabling <strong>net_snmp_perl_enable</strong> in the snmptt.ini file.  If <strong>net_snmp_perl_enable</strong> is not enabled, it will default to using the numeric OID.   </p>
<p>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 <a href="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=722075&amp;group_id=12694&amp;atid=312694">Net-SNMP patch page</a>.</p>
</blockquote>
<p>Note (6):</p>
<blockquote>
<p>The <strong>snmptt.ini</strong> <strong>description_mode</strong> 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 Net-SNMP Perl module installed and enabled.</p>
</blockquote>
<p>Note (7):</p>
<blockquote>
<p>These variables are only available when using the embedded trap handler for snmptrapd (snmptthandler-embedded).</p>
</blockquote>
<h2><a name="SNMPTT.CONF-EXEC"></a>EXEC</h2>
<p>[<strong>EXEC</strong> command_string]</p>
<p>There can be multiple EXEC lines per EVENT.</p>
<p>Optional string containing a command to execute when a trap is received.  The EXEC lines are executed in the order that they appear.</p>
<p>EXEC uses the same variable substitution as the FORMAT line.  You can use <strong>$Fz</strong> on the EXEC line to add the translated FORMAT line instead of repeating what you already defined on FORMAT.</p>
<p>Examples:</p>
<pre><code>EXEC /usr/bin/qpage -f TRAP alex "$r: $x $X - NIC switchover to slot $3, port $4 from slot $5, port $6"

FORMAT NIC switchover to slot $3, port $4 from slot $5, port $6
EXEC /usr/bin/qpage -f TRAP alex "$r: $x $X - $Fz"

EXEC c:\\snmp\\pager netops "$r: $x $X - NIC switchover to slot $3, port $4 from slot $5, port $6"
</code></pre>
<p>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.  </p>
<p>Note: If the trap severity is set to LOGONLY in the snmptt.conf file, EXEC will not be executed.</p>
<h2><a name="SNMPTT.CONF-PREEXEC"></a>PREEXEC</h2>
<p>[<strong>PREEXEC</strong> command_string]</p>
<p>There can be multiple PREEXEC lines per EVENT.</p>
<p>Optional string containing a command to execute after a trap is received but <strong><em>before</em></strong> the FORMAT and EXEC statements are processed. The output of the external program is stored in the <strong>$p<em>n</em></strong> variable where <strong><em>n</em></strong> is a number starting from 1. Multiple PREEXEC lines are permitted. The first PREEXEC stores the result of the command in <strong>$p1</strong>, the second in <strong>$p2</strong> etc. Any ending newlines are removed. The <strong>snmptt.ini</strong> parameter <strong>pre_exec_enable</strong> can be used to enable / disable <strong>PREEXEC</strong> statements.</p>
<p><strong>PREEXEC</strong> uses the same variable substitution as the FORMAT line.</p>
<p>Example:</p>
<pre><code>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
</code></pre>
<p>Sample output:</p>
<blockquote>
<p>Link down on interface 69("100BaseTX Port 1/6 Name SERVER1"). Admin state up. Operational state: down</p>
</blockquote>
<p>In the above example the result is in quotes because that is what comes back from snmpget (it is not added by SNMPTT).</p>
<p>Note: PREEXEC will execute even if the trap severity is set to LOGONLY in the snmptt.conf file.</p>
<h2><a name="SNMPTT.CONF-NODES"></a>NODES</h2>
<p>[<strong>NODES</strong> sources_list]</p>
<p>Used to limit which devices can be mapped to this EVENT definition. </p>
<p>There can be multiple NODES lines per EVENT.</p>
<p>Optional string containing any combination of host names, IP addresses, CIDR network address, network IP address ranges, or a filename.  If this keyword is omitted then ALL sources will be accepted.  Each entry is checked for a match.  As soon as one match occurs, searching stops.</p>
<p>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:</p>
<pre><code>NODES 192.168.1.0/24
</code></pre>
<p>Or, if you wanted devices on IPv4 subnet 192.168.1.0/24 and IPv6 subnet 2001:db8:a::/64:</p>
<pre><code> NODES 192.168.1.0/24 2001:db8:a::/64
</code></pre>
<p>If a filename is specified, it must be specified with a full path. </p>
<p>There are two modes of operation: <strong>POS</strong> (positive - the default) and <strong>NEG</strong> (negative). If set to <strong>POS</strong>, then <strong>NODES</strong> is a 'match' if <em>any</em> of the <strong>NODES</strong> entries match. If set to <strong>NEG</strong>, then <strong>NODES</strong> is a 'match' only if <em>none</em> of the <strong>NODES</strong> entries match. To change the mode of operation, use one of the following statements:</p>
<pre><code>NODES MODE=POS
NODES MODE=NEG
</code></pre>
<p>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.</p>
<p>Example 1:  </p>
<blockquote>
<p>This example will match any hosts called <strong>fred</strong>, <strong>barney</strong>, <strong>betty</strong> or <strong>wilma</strong>:  </p>
<pre><code>NODES fred barney betty wilma
</code></pre>
</blockquote>
<p>Example 2:  </p>
<blockquote>
<p>This example will match any hosts <strong>not</strong> called <strong>fred</strong>, <strong>barney</strong>, <strong>betty</strong> or <strong>wilma</strong>:  </p>
<pre><code>NODES fred barney betty wilma
NODES MODE=NEG
</code></pre>
</blockquote>
<p>Example 3:  </p>
<blockquote>
<p>This example will load the file /etc/snmptt-nodes (see below), and match any hosts called fred, barney, betty, wilma, 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:  </p>
<pre><code>NODES /etc/snmptt-nodes
</code></pre>
</blockquote>
<p>Example 4:  </p>
<blockquote>
<p>This example will load both files /etc/snmptt-nodes and /etc/snmptt-nodes2 (see above example):  </p>
<pre><code>NODES /etc/snmptt-nodes /etc/snmptt-nodes2
</code></pre>
</blockquote>
<p>Example 5:  </p>
<blockquote>
<pre><code>NODES 192.168.4.0/22 192.168.60.0-192.168.61.255 /etc/snmptt-nodes2
</code></pre>
</blockquote>
<p>Example 6:  </p>
<blockquote>
<pre><code>NODES fred /etc/snmptt-nodes pebbles /etc/snmptt-nodes2 barney
</code></pre>
</blockquote>
<p>where snmptt-nodes contains:</p>
<blockquote>
<pre><code>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
</code></pre>
</blockquote>
<p>Notes:</p>
<ul>
<li>
<p>The names are NOT case sensitive and comment lines are permitted by starting the line with a #.  </p>
</li>
<li>
<p>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.  </p>
</li>
<li>
<p>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.  </p>
</li>
<li>
<p>By default, NODES files are loaded when the snmptt.conf files are loaded (during startup of SNMPTT).  The snmptt.ini option <strong>dynamic_nodes</strong> can be set to 1 to have the nodes files loaded each time an EVENT is processed.  </p>
</li>
<li>
<p>See the section '<a href="#DNS">Name Resolution / DNS</a>' for important DNS information.</p>
</li>
<li>
<p>See the section <a href="#Notes-ipv6">IPv6</a> for important IPv6 information.</p>
</li>
</ul>
<h2><a name="SNMPTT.CONF-MATCH"></a>MATCH</h2>
<p>[MATCH [MODE=[or | and]] | [$n:[!][(    )[i] | n | n-n | &gt; n | &lt; n | x.x.x.x | x.x.x.x-x.x.x.x | x.x.x.x/x]]</p>
<p>Optional match expression that must be evaluated to true for the trap to be considered a match to this EVENT definition.</p>
<p>If a MATCH statement exists, and no matches evaluate to true, then the default will be to NOT match this EVENT definition.</p>
<p>The following Perl regular expression modifiers are supported:</p>
<blockquote>
<p>i - ignore case when trying to match</p>
</blockquote>
<p>The following command formats are available:</p>
<blockquote>
<p><strong>MATCH MODE=[or | and]<br />
MATCH <em>$x:</em> [!] <em>(reg) [i]</em><br />
MATCH <em>$x:</em> [!] <em>n</em><br />
MATCH <em>$x:</em> [!] <em>n-n</em><br />
MATCH <em>$x:</em> [!] <em>&lt; n</em><br />
MATCH <em>$x:</em> [!] <em>&gt; n</em><br />
MATCH <em>$x:</em> [!] &amp; <em>n</em><br />
MATCH <em>$x:</em> [!] <em>x.x.x.x</em><br />
MATCH <em>$x:</em> [!] <em>x.x.x.x-x.x.x.x</em><br />
MATCH <em>$x:</em> [!] <em>x.x.x.x/x</em><br />
MATCH <em>$x:</em> [!] <em>x:x:x</em><br />
MATCH <em>$x:</em> [!] <em>x:x:x/x</em><br />
</strong>  </p>
</blockquote>
<p>where:  </p>
<blockquote>
<p><strong>or</strong> or <strong>and</strong> set the default evaluation mode for ALL matches<br />
<strong>$x</strong> is any variable (example: $3, $A, $* etc)<br />
<strong>reg</strong> is a regular expression<br />
<strong>!</strong> is used to negate the result (not)<br />
<strong>&amp;</strong> is used to perform a bitwise AND<br />
<strong>n</strong> is a number<br />
<strong>x.x.x.x</strong> is an IP address<br />
<strong>x.x.x.x-x.x.x.x</strong> is an IPv4 network address range<br />
<strong>x.x.x.x/x</strong> is an IPv4 CIDR network addresss<br />
<strong>x:x:x</strong> is an IPv6 addresss<br />
<strong>x:x:x/x</strong> is an IPv6 CIDR network addresss  </p>
</blockquote>
<p>Notes:  </p>
<ul>
<li>
<p>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 <strong>NODES</strong> keyword is recommended.  </p>
</li>
<li>
<p>If the match mode is 'or', once a match occurs no other matches are performed and the end result is true.  </p>
</li>
<li>
<p>If the match mode is 'and', once a match fails, no other matches are performed and the end result is false.  </p>
</li>
<li>
<p>To use parentheses ( or ) in the search expression, they must be backslashed (\).  </p>
</li>
<li>
<p>If no MATCH MODE= line exists, it defaults to 'or'.  </p>
</li>
<li>
<p>There can be only one match mode per EVENT.  If multiple MATCH MODE= lines exists, the last one in the list is used.</p>
</li>
<li>
<p>See the section <a href="#Notes-ipv6">IPv6</a> for important IPv6 information.</p>
</li>
</ul>
<p>Examples:  </p>
<blockquote>
<p>$2 must be between 1000 and 2000:  </p>
<pre><code>MATCH $2: 1000-2000
</code></pre>
<p>Any one of the following 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':  </p>
<pre><code>MATCH $3: 52
MATCH $4: 192.168.1.10-192.168.1.20
MATCH $s: (Major)
</code></pre>
<p>$6 must be IPv6 address 2002:0000:0000:1234:abcd:ffff:c0a8:0101 or in subnet 2002:0000:0000:1234:0000:0000:0000:0000/64:</p>
<pre><code>MATCH $6: 2002::1234:abcd:ffff:c0a8:0101
MATCH $6: 2002:0000:0000:1234:0000:0000:0000:0000/64
</code></pre>
<p>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:  </p>
<pre><code>MATCH $3: &gt;20  
MATCH $5: !(alarm|critical)  
MATCH $6: (\(1\) remaining)  
MATCH $7: (power)i  
MATCH MODE=and
</code></pre>
<p>The integer $1 must have bit 4 set:  </p>
<pre><code>MATCH $1: &amp;8
</code></pre>
</blockquote>
<h2><a name="SNMPTT.CONF-REGEX"></a>REGEX</h2>
<p>[<strong>REGEX</strong>(    )(    )[i][g][e]]</p>
<p>Optional regular expression to perform a search and replace on the translated FORMAT / EXEC line.  Multiple REGEX (    )(    ) lines are permitted.</p>
<p>First (    ) contains the search expression.<br />
 Second (    ) contains the replacement text</p>
<p>The following Perl regular expression modifiers are supported:</p>
<blockquote>
<p>i - ignore case when trying to match left side<br />
g - replace all occurances instead of only the first<br />
e - execute the right side (eval) as code</p>
</blockquote>
<p>To use substitution with captures (memory parenthesis) or the <strong>e</strong> modifier, you must first enable support in the snmptt.ini file by setting <strong>allow_unsafe_regex</strong> 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, <strong>BE SURE THAT THE SNMPTT CONFIGURATION FILES ARE SECURE!</strong></p>
<p>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.</p>
<p><strong>Example:</strong></p>
<blockquote>
<p>FORMAT line before:  UPS has       detected a      building alarm.       Cause: UPS1 Alarm #14: Building alarm 3.  </p>
<pre><code>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
</code></pre>
<p>FORMAT line after:  The big UPS has detected a building alarm. Cause: UPS1 Alarm #14: Computer ROOM high temperature</p>
<p>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.</p>
</blockquote>
<p><strong>Example:</strong></p>
<blockquote>
<p>FORMAT line before:  Alarm (1) and (2) has been triggered  </p>
<pre><code>REGEX (\(1\))(One)  
REGEX (\(2\))((Two))
</code></pre>
<p>FORMAT line after:  Alarm One and (Two) has been triggered</p>
</blockquote>
<p>If <strong>allow_unsafe_regex</strong> is enabled, then captures can be used in the replacement text.  </p>
<p><strong>Example:</strong></p>
<blockquote>
<p>FORMAT line before:  The system has logged exception error 55 for the service testservice  </p>
<pre><code>REGEX (The system has logged exception error (\d+) for the service (\w+))(Service $2 generated error $1)
</code></pre>
<p>FORMAT line after:  Service testservice generated error 55</p>
</blockquote>
<p>If <strong>allow_unsafe_regex</strong> 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 (.).  </p>
<p><strong>Example 1:</strong></p>
<blockquote>
<p>FORMAT line before:  Authentication Failure Trap from IP address: C0 A8 1 FE  </p>
<pre><code>REGEX (Address: (\w+)\s+(\w+)\s+(\w+)\s+(\w+))("address: ".hex($1).".".hex($2).".".hex($3).".".hex($4))ei
</code></pre>
<p>FORMAT line after:  Authentication Failure Trap from IP address: 192.168.1.254</p>
</blockquote>
<p><strong>Example 2:</strong></p>
<blockquote>
<p>FORMAT line before:  Authentication Failure Trap from IP address: C0 A8 1 FE  </p>
<pre><code>REGEX (Address: (\w+)\s+(\w+)\s+(\w+)\s+(\w+))("address:".sprintf("%03d.%03d.%03d.%03d",hex($1),hex($2),hex($3),hex($4)))ie
</code></pre>
<p>FORMAT line after:  Authentication Failure Trap from IP address: 192.168.001.254</p>
</blockquote>
<p><strong>Example 3</strong></p>
<blockquote>
<p>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.</p>
<p>FORMAT line before:  Peer:$+2  </p>
<p>FORMAT line after substitution, but before REGEX:  Peer:bgpPeerState.192.168.1.1:idle  </p>
<pre><code>REGEX (Peer:.\*\.(\d+\.\d+\.\d+\.\d+):(.\*))("Peer: $1 has transitioned to $2")e
</code></pre>
<p>FORMAT line after:  Peer: 192.168.1.1 has transitioned to idle</p>
</blockquote>
<p><strong>Example 4</strong></p>
<blockquote>
<p>This example is a sample of using Perl subroutines inside of a REGEX statement.  </p>
<p>FORMAT line before:  Extremely severe error has occured  </p>
<pre><code>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&lt;6;$i++) { $temp = $temp . " " . (int(rand 49) +1); } return $temp; } )ie
</code></pre>
<p>FORMAT line after:  Better get a lotto ticket!!  Here is a lotto number to try: 36 27 38 32 29 6</p>
</blockquote>
<p>Note:  The REGEX expression is executed on the final translated FORMAT / EXEC line, after all variable substitutions have been completed.</p>
<h2><a name="SNMPTT.CONF-SDESC"></a>SDESC</h2>
<p>[<strong>SDESC</strong>]</p>
<p>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.</p>
<h2><a name="SNMPTT.CONF-EDESC"></a>EDESC</h2>
<p>[<strong>EDESC</strong>]</p>
<p>Used to end the description section.</p>
<p>Example:</p>
<blockquote>
<pre><code>SDESC  
Trap used when power supply fails in  
a server.  
EDESC
</code></pre>
</blockquote>
<h1><a name="SNMPTT.CONF-Configuration-file-Notes"></a>SNMPTT.CONF Configuration file Notes</h1>
<p>When there are multiple definitions of the same trap in the configuration file, the following rules apply:</p>
<p><strong>A match occurs when:</strong></p>
<ul>
<li>The received trap OID matches a defined OID in the configuration file</li>
<li><strong>AND</strong> <strong>(</strong> the hostname matches a defined hostname in the NODES entry <strong>OR</strong> there is no NODES entry <strong>)</strong></li>
<li><strong>AND</strong> <strong>(</strong> the MATCH statement evaluates to TRUE <strong>OR</strong> the there is no MATCH entry  <strong>)</strong></li>
</ul>
<p><strong>If multiple_event is set to 1 in snmptt.ini:</strong></p>
<ul>
<li>A trap is handled as many times as it matches in the configuration file</li>
<li>If any number of exact matches exist, the wildcard match is NOT performed</li>
<li>If an exact match does NOT exist, the wildcard match IS performed if <strong>(</strong> the hostname matches a defined hostname in the NODES entry <strong>OR</strong> there is no NODES entry <strong>)</strong> <strong>AND</strong> <strong>(</strong> the MATCH statement evaluates to TRUE <strong>OR</strong> the there is no MATCH entry  <strong>)</strong></li>
</ul>
<p><strong>If multiple_event is set to 0 in snmptt.ini:</strong></p>
<ul>
<li>A trap is handled once using the first match in the configuration file</li>
<li>If an exact match exists, the wildcard match is NOT performed</li>
<li>If an exact match does NOT exist, the wildcard match IS performed if <strong>(</strong> the hostname matches a defined hostname in the NODES entry <strong>OR</strong> there is no NODES entry <strong>)</strong> <strong>AND</strong> <strong>(</strong> the MATCH statement evaluates to TRUE <strong>OR</strong> the there is no MATCH entry  <strong>)</strong></li>
</ul>
<h1><a name="DNS"></a>Name resolution / DNS</h1>
<p>Snmptrapd passes the IP address of the device sending the trap (host name), the host name of the device sending the trap (host name, if configured to resolve host names) and the IP address of the actual SNMP agent (agent).  </p>
<p>If the configuration setting <strong>dns_enable</strong> is set to 0 (dns disabled), then the host name of the AGENT will not be available for the <strong>$A</strong> variable, <strong>NODES</strong> 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.  </p>
<p>If the configuration setting <strong>dns_enable</strong> is set to 1 (dns enabled), then the host name of both the host and the AGENT will be resolved via DNS.  <strong>NODES</strong> entries will also be resolved to IP addresses before performing matches.  </p>
<p>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 <strong>strip_domain</strong> / <strong>strip_domain_list</strong> options to have SNMPTT strip the domain of any FQDN host.  See the <strong>snmptt.ini</strong> file for details.</p>
<p>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.  </p>
<p>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.  </p>
<h1><a name="Sample-SNMPTT.CONF-file"></a>Sample SNMPTT.CONF files</h1>
<h2><a name="Sample1-SNMPTT.CONF-file"></a>Sample1</h2>
<p>Note: The examples folder also contains a sample snmptt.conf file.</p>
<p>Following is a sample of two defined traps in <strong>snmptt.conf:</strong></p>
<pre><code>#  
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  
#  
#
</code></pre>
<h2><a name="Sample2-SNMPTT.CONF-file"></a>Sample2</h2>
<p>Following is a sample of a list of files to load in <strong>snmptt.ini:</strong></p>
<pre><code>snmptt_conf_files = &lt;&lt;END  
/etc/snmp/snmp-compaq.conf  
/etc/snmp/snmp-compaq-hsv.conf  
END
</code></pre>
<p>Following is a sample of one defined trap in <strong>/etc/snmp/snmptt-compaq.conf:</strong></p>
<pre><code>#  
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  
#
</code></pre>
<p>Following is a sample of one defined trap in <strong>/etc/snmp/snmptt-compaq-hsv.conf:</strong></p>
<pre><code>#  
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  
#
</code></pre>
<h1><a name="Notes"></a>Notes</h1>
<h2><a name="Notes-trapd.conf"></a>trapd.conf &amp; MIB files</h2>
<p>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.</p>
<p>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.</p>
<p>Some vendors provide a MIB file that contains TRAP or NOTIFICATION definitions.  snmpttconvertmib can be used to convert the file to snmptt.conf format.  </p>
<h2><a name="Notes-ipv6"></a>IPv6</h2>
<ul>
<li>For incoming traps, a simple Perl regular expression is used to detect an IPv6 address for the trap host and Agent IPs as it is assumed that Net-SNMP is passing a valid IPv6 address.  If the address has a zone index such as <strong>%ens160</strong> or <strong>%1</strong> appended to it, the zone index is removed.  Zone indexes are not removed from enterprise variable values.</li>
<li>When DNS is enabled to resolve enterprise variables, the trap host and Agent IP <strong>(dns_enabled = 1)</strong>, a complex regular expression is used to confirm that the IP address is valid before passing on to the <strong>IO::Socket::IP</strong> module for DNS resolution.  The <a href="https://community.helpsystems.com/forums/intermapper/miscellaneous-topics/5acc4fcf-fa83-e511-80cf-0050568460e4?_ga=2.113564423.1432958022.1523882681-2146416484.1523557976">Dartware</a> regular expression is used.  Also see <a href="https://raw.githubusercontent.com/richb-intermapper/IPv6-Regex/master/test-ipv6-regex.pl">here</a> for a test suite.</li>
<li>For <strong>NODES</strong> and <strong>MATCH</strong>, the <a href="http://search.cpan.org/search?module=Net::IP">Net::IP</a> module is used as it allows you to test to see if two IP addresses are the same or if one IP address is within the range of another.  IPv6 addresses can be represented in multiple ways so this module is used to ensure that an IP address such as <strong>2002:0000:0000:1234:abcd:ffff:c0a8:0101</strong> is matched to its shorthand version of <strong>2002::1234:abcd:ffff:c0a8:0101</strong>.  When running a modified version of the test suite above against Net::IP, it was found that it only passed 316 out of 490 tests compared to Dartmouth which passed 489 out of 490.  There may be issues with matching some IP addresses passed in enterprise variables for MATCH but  NODES should not be affected as Net-SNMP should be passing a supported format for both the host and agent IP addresses.</li>
</ul>
<h1><a name="Limitations"></a>Limitations</h1>
<h2><strong>Standalone mode only:</strong></h2>
<p>With a 450 Mhz PIII (way back in 1998) and a 9000 line snmptt.conf containing 566 unique traps (EVENTs), it took 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.  Daemon mode should be used instead.</p>
<p>Note: Enabling the Net-SNMP Perl module will greatly increase the startup time of SNMPTT.  Daemon mode is recommended.</p>
<h2><strong>Standalone or daemon mode:</strong></h2>
<p>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.</p>
<p>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.  </p>
<h1><a name="Feedback"></a>Feedback &amp; Bugs</h1>
<p>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.</p>
<p>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 <a href="http://sourceforge.net/tracker/?group_id=51473&amp;atid=463393">bugs</a> and <a href="http://sourceforge.net/tracker/?atid=463396&amp;group_id=51473&amp;func=browse">feature requests</a>.  </p>
<h1><a name="Integration-with-other-software"></a>Integration with other software</h1>
<h2><a name="Nagios-Netsaint"></a>Nagios</h2>
<h3>Overview</h3>
<p>This section will outline the basic steps to integrate SNMPTT with Nagios Core.  If you are using Nagios XI, see <a href="https://www.nagios.com/solutions/snmp-traps/">Handling SNMP Traps With Nagios</a>.</p>
<p>Before attempting to integrate SNMPTT with Nagios, please ensure that you have a fully functioning SNMPTT system that can at least log translated traps to a log file.</p>
<h3>Nagios Passive Service Checks</h3>
<p>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 <strong>submit_check_result</strong> script included with Nagios.  Once received by Nagios, Nagios will handle alerting for the trap.  </p>
<p>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 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.</p>
<p>The downside of using only one service entry is that you will only see the last trap that was received on the Nagios console.  Alerting will be handled by Nagios for each trap received 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.</p>
<h3>Nagios Volatile Services</h3>
<p>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.  Normally, a service is Nagios in 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 SNMP traps, we need to make sure we are contacted every time a trap comes in.</p>
<h3>Creating the Nagios service entry</h3>
<p>Following is a sample service entry for Nagios.</p>
<pre><code>define service{
    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
}
</code></pre>
<p>Note:  To simplify the configuration, you can create a service template.</p>
<p>Note:  Previous versions of this documentation defined a <strong>check_period</strong> of none, and did not set <strong>active_checks_enabled</strong> to 0.  As of SNMPTT 1.2, setting <strong>active_checks_enabled</strong> to 0 instead of setting <strong>check_period</strong> to 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.</p>
<h3>Creating the SNMPTT EXEC statement</h3>
<p>The Nagios distribution should contain the script <strong>submit_check_result</strong> in the <strong>contrib/eventhandlers</strong> directory.  Create a directory called <strong>eventhandlers</strong> under <strong>libexec</strong> (/usr/local/nagios/libexec) and copy the <strong>submit_check_result</strong> script to that directory.  Make sure the script is executable (<strong>chmod +x submit_check_result</strong>).  </p>
<p>The <strong>submit_check_result</strong> script expects the following arguments:  </p>
<blockquote>
<p><strong>host_name</strong>
<strong>svc_description</strong>
<strong>return_code</strong>
<strong>plugin_output</strong></p>
</blockquote>
<p>The possible return codes are: <strong>0</strong>=OK, <strong>1</strong>=WARNING, <strong>2</strong>=CRITICAL, <strong>-1</strong>=UNKNOWN.  See the top of the <strong>submit_check_result</strong> script for a detailed description of each argument.  </p>
<p>Create an <strong>EXEC</strong> statement such as the following for each <strong>EVENT</strong> entry in your snmptt.conf file:   </p>
<pre><code>EXEC /usr/local/nagios/libexec/eventhandlers/submit_check_result $r TRAP 1 "xxxxxx"
</code></pre>
<p>where "xxxxxx" is the text for the trap using the same format as the FORMAT statement.  For example:  </p>
<pre><code>EXEC /usr/local/nagios/libexec/eventhandlers/submit_check_result $r TRAP 1 "Drive $1 in bay $2 has failed"
</code></pre>
<p>The variable substitution <strong>$r</strong> is used to pass the host name, TRAP matches the service definition defined above, 1 represents a WARNING, and "xxxxxx" is the same text used for your FORMAT line.</p>
<p>Instead of repeating the same text as the FORMAT line, you can instead use the <strong>$Fz</strong> variable in the EXEC statement.  For example, to generate the EXEC command when using snmpttconvertmib:</p>
<p>Create a file called exec-commands.txt with (all on one line):</p>
<pre><code>/usr/local/nagios/libexec/eventhandlers/submit_check_result $r TRAP 1 "$Fz"
</code></pre>
<p>Run snmpttconvertmib using:</p>
<pre><code>snmpttconvertmib --in=/usr/share/snmp/mibs/mibname.mib --out=/etc/snmp/snmptt.conf --exec_mode=1 --exec_file=exec-commands.txt
</code></pre>
<p>Note:  Run snmpttconvertmib -h for information on the command line options.</p>
<p>You must make sure that the host definition in Nagios matches the hostname that will be passed from SNMPTT using the <strong>$r</strong> variable.  See the section '<a href="#DNS">Name Resolution / DNS</a>' for important DNS information.  </p>
<h3>Clearing received traps in Nagios</h3>
<p>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:  </p>
<pre><code>#!/bin/sh  
/bin/echo "OK: No recent traps received"  
exit 0
</code></pre>
<p>Be sure to create a command definition in your <strong>commands.cfg</strong> file.  See the 'Object configuration file options' section of the Nagios documentation.  </p>
<p>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 <strong>check_freshness</strong> and <strong>freshness_threshold</strong> in the service definition.  Using freshness checks is recommended over normal active checks (defined by <strong>normal_check_interval</strong>) 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 <strong>freshness_threshold</strong> seconds after the last passive result was received.  </p>
<p>For freshness checking to work, <strong>normal_check_interval</strong> must be set to <strong>1</strong>, <strong>valid check_period</strong> should be set to <strong>24x7</strong> and the following service definitions should be added. </p>
<pre><code>check_freshness         1           # Enable freshness checking
freshness_threshold     86400       # Reset trap alert every 24 hours.
</code></pre>
<h3>SNMP heartbeat monitoring</h3>
<p>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.  </p>
<p>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.  </p>
<pre><code>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.
</code></pre>
<p>Note:  For freshness checking to work, <strong>normal_check_interval</strong> must be set to <strong>1</strong>, and valid <strong>check_period</strong> should be set to <strong>24x7</strong>.  </p>
<p>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.  </p>
<p>Create the new <strong>myapp_heartbeat_alarm_set</strong> command for Nagios:  </p>
<pre><code>#!/bin/sh  
/bin/echo "CRITICAL: Heartbeat signal from MyApp was not received!"  
exit 2
</code></pre>
<p>Be sure to create a command definition in your <strong>commands.cfg</strong> file.  See the 'Object configuration file options' section of the Nagios documentation.  </p>
<p>Next, add an <strong>EXEC</strong> statement to the snmptt.conf file for the trap definition:  </p>
<pre><code>EXEC /usr/local/nagios/libexec/eventhandlers/submit_check_result $r MyApp_heartbeat 1 "Heartbeat signal from MyApp received."
</code></pre>
<p>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 <strong>CRITICAL</strong>.  </p>
<h2><a name="Icinga"></a>Icinga</h2>
<h3>Overview</h3>
<p>This section will outline the basic steps to integrate SNMPTT with Icinga.  Some of the configuration and scripts were copied from <a href="https://icinga.com/docs/icinga-2/snapshot/doc/07-agent-based-monitoring/#snmp-traps-and-passive-check-results">Icinga's SNMPTT documentation</a>.</p>
<p>Before attempting to integrate SNMPTT with Icinga, please ensure that you have a fully functioning SNMPTT system that can at least log translated traps to a log file.</p>
<h3>Icinga Passive Service Checks</h3>
<p>Passive service checks allow Icinga to process service check results that are submitted by external applications.  Using SNMPTT's EXEC statement, the received trap can be passed to Icinga via the curl program.  Once received by Icinga, Icinga will handle alerting for the trap.  </p>
<p>In this guide, we setup <strong>one</strong> service definition for each Icinga host that is to receive traps from SNMPTT.  The benefits of using only one service entry is that it  makes it easier to set up Icinga. 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.  </p>
<p>The downside of using only one service entry is that you will only see the last trap that was received on the Icinga console.  Alerting will be handled by Icinga for each trap received 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.  See Clearing received traps in Icinga below.</p>
<h3>Icinga Volatile Services</h3>
<p>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.  Normally, a service in Icinga 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 SNMP traps, we need to make sure we are contacted every time a trap comes in.</p>
<h3>Creating the Icinga service entry</h3>
<p>Following is a sample service entry for Icinga.</p>
<pre><code>object Service "TRAP" {  
  host_name = "server1.domain"  
  import "generic-service"

  check_command         = "dummy"  
  event_command         = "trap-reset-event"

  enable_notifications  = 1  
  enable_active_checks  = 0  
  enable_passive_checks = 1  
  enable_flapping       = 0  
  volatile              = 1  
  enable_perfdata       = 0

  vars.dummy_state      = 0  
  vars.dummy_text       = "Manual reset."

  vars.sla              = "24x7"  
}
</code></pre>
<p>Note:  To simplify the configuration, you can instead apply the service to hosts using an 'apply Service'.  See the <a href="https://icinga.com/docs/icinga-2/snapshot/doc/07-agent-based-monitoring/#snmp-traps-and-passive-check-results">Icinga SNMPTT documentation</a> for an example.</p>
<h3>Creating the SNMPTT EXEC statement</h3>
<p>Create an EXEC statement such as the following for each <strong>EVENT</strong> entry in your snmptt.conf file:  </p>
<pre><code>EXEC /usr/bin/curl -k -s -S -i -u apiuser:password -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/process-check-result' -d '{ "type": "Service", "filter": "host.name==\"$A\" &amp;&amp; service.name==\"TRAP\"", "exit_status": 2, "plugin_output": "xxxxxx", "check_source": "$A", "pretty": true }'
</code></pre>
<p>where <strong><em>apiuser</em>:<em>password</em></strong> is the API username and password, <strong><em>xxxxxx</em></strong> is the text for the trap using the same format as the FORMAT statement.  </p>
<p>The variable substitution <strong>$A</strong> is used to pass the host name for <strong>host.name</strong> and <strong>check_source</strong>, TRAP for <strong>service.name</strong> matches the service definition defined above, <strong>exit_status</strong> of <strong>1</strong> represents a <strong>WARNING</strong>, and <strong>xxxxxx</strong> is the same text used for your FORMAT line.</p>
<p>Instead of repeating the same text as the FORMAT line, you can instead use the <strong>$Fz</strong> variable in the EXEC statement.  For example, to generate the EXEC command when using snmpttconvertmib:</p>
<p>Create a file called exec-commands.txt with (all on one line):</p>
<pre><code>/usr/bin/curl -k -s -S -i -u apiuser:password -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/process-check-result' -d '{ "type": "Service", "filter": "host.name==\"$A\" &amp;&amp; service.name==\"TRAP\"", "exit_status": 2, "plugin_output": "$Fz", "check_source": "$A", "pretty": true }'
</code></pre>
<p>Run snmpttconvertmib using:</p>
<pre><code>snmpttconvertmib --in=/usr/share/snmp/mibs/mibname.mib --out=/etc/snmp/snmptt.conf --exec_mode=1 --exec_file=exec-commands.txt
</code></pre>
<p>Note:  Run snmpttconvertmib -h for information on the command line options.</p>
<p>An API user must be defined in api-users.conf with the permission <strong>actions/process-check-result</strong>.  Example:  </p>
<pre><code>object ApiUser "snmptt" {  
  password = "xxxxxxxxxxxxxxx"  
  permissions = [ "actions/process-check-result" ]  
}
</code></pre>
<p>You must make sure that the host definition in Icinga matches the hostname that will be passed from SNMPTT using the <strong>$A</strong> variable.  See the section '<a href="#DNS">Name Resolution / DNS</a>' for important DNS information.  </p>
<h3>Clearing received traps in Icinga</h3>
<p>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 Icinga console, open the TRAP service and click 'Check Now'.  This will cause the defined event check to be run (trap-reset-event in the example above) which will then change the status code to OK and clear the warning.  For this to work, you must define an Icinga command:  </p>
<pre><code>object EventCommand "trap-reset-event" {  
  command = [ ConfigDir + "/scripts/trap_reset_event.sh" ]

  arguments = {  
    "-i" = "$service.state_id$"  
    "-n" = "$host.name$"  
    "-s" = "$service.name$"  
  }  
}
</code></pre>
<p>Create the <strong>trap_reset_event.sh</strong> script in <strong>ConfDir</strong> <strong>/scripts</strong> (/etc/icinga2/scripts) and make sure it's executable (<strong>chmod +x</strong>).  </p>
<pre><code>#!/bin/bash

SERVICE_STATE_ID=""  
HOST_NAME=""  
SERVICE_NAME=""

show_help()  
{  
cat &lt;&lt;-EOF  
    Usage: ${0##*/} [-h] -n HOST_NAME -s SERVICE_NAME  
    Writes a coldstart reset event to the Icinga command pipe.

      -h                  Display this help and exit.  
      -i SERVICE_STATE_ID The associated service state id.  
      -n HOST_NAME        The associated host name.  
      -s SERVICE_NAME     The associated service name.  
EOF  
}

while getopts "hi:n:s:" opt; do  
    case "$opt" in  
      h)  
          show_help  
          exit 0  
          ;;  
      i)  
          SERVICE_STATE_ID=$OPTARG  
          ;;  
      n)  
          HOST_NAME=$OPTARG  
          ;;  
      s)  
          SERVICE_NAME=$OPTARG  
          ;;  
      '?')  
          show_help  
          exit 0  
          ;;  
      esac  
done

if [ -z "$SERVICE_STATE_ID" ]; then  
    show_help  
    printf "\n  Error: -i required.\n"  
    exit 1  
fi

if [ -z "$HOST_NAME" ]; then  
    show_help  
    printf "\n  Error: -n required.\n"  
    exit 1  
fi

if [ -z "$SERVICE_NAME" ]; then  
    show_help  
    printf "\n  Error: -s required.\n"  
    exit 1  
fi

if [ "$SERVICE_STATE_ID" -gt 0 ]; then  
    echo "[`date +%s`] PROCESS_SERVICE_CHECK_RESULT;$HOST_NAME;$SERVICE_NAME;0;Auto-reset (`date +"%m-%d-%Y %T"`)." &gt;&gt; /var/run/icinga2/cmd/icinga2.cmd  
fi
</code></pre>
<p>To have the TRAP service automatically cleared 20 minutes after the last trap was received, modify the service entry to enable active checks and define a check_interval:  </p>
<pre><code>enable_passive_checks = 1  
check_interval        = 1200
</code></pre>
<h2><a name="Zabbix"></a>Zabbix</h2>
<p>Information on handling SNMP traps with <a href="https://www.zabbix.com">Zabbix</a> can be found in the <a href="https://www.zabbix.com/documentation/current/manual/config/items/itemtypes/snmptrap">Zabbix documentation</a>.</p>
<h2><a name="SEC"></a>SEC - Simple Event Correlator</h2>
<h3>Overview</h3>
<p><a href="http://kodu.neti.ee/%7Eristo/sec/">Simple Event Correlator (SEC)</a> is a free and platform independent event correlation tool.</p>
<p>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 <a href="http://kodu.neti.ee/%7Eristo/sec/">SECs web page</a> and a good introduction to SEC can be found <a href="http://simple-evcorr.sourceforge.net/SEC-tutorial/article.html">here</a>.  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.</p>
<p>This section outlines one method of integrating SEC with SNMPTT.  Another method is documented in the <a href="https://web.archive.org/web/20050429210306/http://www.samag.com/articles/2005/0503/">March 2005 edition</a> of <strong>Sys Admin Magazine</strong> in an article written by Francois Meehan.  A copy of the article is available <a href="https://www.drdobbs.com/snmp-trap-handling-with-nagios/199102017">here</a>.</p>
<p>Here are a couple of examples of why you would want to integrate SNMPTT with SEC:   </p>
<ol>
<li>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.</li>
<li>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.</li>
</ol>
<p>The following outlines how the flow of traps between SNMPTT and SEC could take place:</p>
<ol>
<li>SNMPTT receives a trap.</li>
<li>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).</li>
<li>SEC monitors the log file for new entries.</li>
<li>SEC correlates the messages from the log file.</li>
<li>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).</li>
<li>SNMPTT will process the new trap as it would any other trap by logging to snmptt.log, a SQL table etc.</li>
</ol>
<h3>Configuration Overview</h3>
<p>The following outlines how example 2 from above could be handled using SEC.  This is a slightly modified version of the example from the <a href="http://kodu.neti.ee/%7Eristo/sec/examples.html">SEC Examples page</a>.</p>
<p>The example provides the following:</p>
<ul>
<li>Prevents interface flapping from flooding the log files</li>
<li>Provides an 'unstable' and 'stable' alert based on how often the interface bounces.</li>
</ul>
<p>The following steps need to be completed:</p>
<ol>
<li>Modify the Cisco snmptt.conf file to output linkDown and linkUp messages to a separate log file.</li>
<li>Create a new snmptt.conf file to handle incoming alerts from SEC</li>
<li>Create a SEC configuration file to correlate the linkDown / linkUp messages and pass new alerts to a script</li>
<li>Create a script that will feed the messages from SEC back in to SNMPTT</li>
<li>Test</li>
</ol>
<h3>1. Modify the Cisco SNMPTT.CONF file</h3>
<p>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.</p>
<p>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.</p>
<pre><code>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" &gt;&gt; /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" &gt;&gt; /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  
#  
#  
#
</code></pre>
<h3>2. Create a new SNMPTT.CONF file for incoming SEC alerts</h3>
<p>A new SNMPTT.CONF file needs to be created which will handle the incoming traps from SEC.  </p>
<p>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.  </p>
<pre><code>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  
#  
#  
#
</code></pre>
<h3>3. Create a SEC configuration file</h3>
<p>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 <a href="http://kodu.neti.ee/%7Eristo/sec/examples.html">SEC Examples page</a> except comments and file paths have been modified.  </p>
<pre><code>########################################################  
          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
</code></pre>
<p>Here is a quick breakdown of what each rule does:  </p>
<p>First rule:  </p>
<ul>
<li>If a linkDown is received (node=x msg_text=cisco linkdown 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. </li>
<li>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.</li>
</ul>
<p>Second rule:  </p>
<ul>
<li>Allows only one 'CISCO x INTERFACE x DOWN' message to be processed over 60 seconds.</li>
</ul>
<p>Third rule:  </p>
<ul>
<li>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.</li>
<li>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.</li>
</ul>
<p>Fourth rule:  </p>
<ul>
<li>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.</li>
<li>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.</li>
</ul>
<h3>4. Create a script to pass a trap back to SNMPTT</h3>
<p>Following is a Perl script that passes the information passed from SEC back to SNMPTT by calling <strong>snmptthandler</strong> directly.  This file is basically a modified Perl version of the shell script available on the <a href="http://kodu.neti.ee/%7Eristo/sec/examples.html">SEC Examples page</a>.   </p>
<pre><code>#!/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;
</code></pre>
<h2><a name="EventWin"></a>Windows Event Log forwarding</h2>
<h3>Overview</h3>
<p>The Windows utility Event to Trap Translator (<strong>evntwin.exe</strong> and <strong>evntcmd.exe)</strong> 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).</p>
<p><strong>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.</strong></p>
<h3>SNMP Service</h3>
<p>The Windows SNMP Service is the Microsoft SNMP agent which 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.</p>
<p>Note: The Microsoft SNMP Trap Service is used to RECEIVE SNMP traps which is similar to the Net-SNMP <strong>snmptrapd.exe</strong> daemon. The Microsoft SNMP Trap Service is NOT used to send traps and is not required.</p>
<h3>Configuring the trap destination</h3>
<p>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:</p>
<ul>
<li>Open <strong>Administrative Tools</strong></li>
<li>Open <strong>Services</strong></li>
<li>Open <strong>Local Policies</strong></li>
<li>Open <strong>SNMP Service</strong></li>
<li>Click the <strong>Traps</strong> tab</li>
<li>Enter a community name and click Add to List</li>
<li>Click Add and enter the IP address of the management station</li>
<li>Click Apply</li>
<li>Click OK</li>
<li>Right-click on <strong>SNMP Service</strong> and select <strong>Restart</strong></li>
</ul>
<p>After the service is restarted, a <strong>coldStart</strong> trap will be sent to the management station. If SNMPTT has been configured to translate <strong>coldStart</strong> messages, you should see a log entry similar to the following:</p>
<p><strong>Thu Sep 9 21:33:06 2004 .1.3.6.1.6.3.1.1.5.1 Normal "Status Events" server1 - Device reinitialized (coldStart)</strong></p>
<p>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 <strong>Management and Monitoring Tools</strong> and then <strong>Simple Network Management Protocol</strong>.</p>
<h3>Configuring the Event to Trap Translator</h3>
<p>The following steps explain how to configure the Event to Trap Translator to forward system logon failures to SNMPTT:</p>
<ul>
<li>Launch <strong>evntwin.exe</strong></li>
<li>For <strong>Configuration Type</strong> select <strong>Custom</strong></li>
<li>Click the <strong>Edit</strong> button</li>
<li>Inside <strong>Event Sources</strong>, expand <strong>Security</strong> and then click <strong>Security</strong></li>
<li>Locate Event ID <strong>529</strong> (Logon Failure:%n%tReason:%t%tUnknown username or bad password%n.)</li>
<li>Click <strong>Add</strong></li>
<li>Click <strong>OK</strong></li>
<li>Click <strong>Apply</strong></li>
</ul>
<p>The SNMP agent should now forward all logon failures to the SNMP management station. A restart of the SNMP service should not be necessary.</p>
<h3>Configuring SNMPTT to accept the Microsoft traps</h3>
<p>An SNMPTT.CONF file needs to be created to handle the Microsoft traps. 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 <strong>snmptt.conf.microsoft</strong> file which needs to be included in the list of .conf files in the <strong>TrapFiles</strong> section in <strong>snmptt.ini</strong>:</p>
<pre><code>EVENT EventLog .1.3.6.1.4.1.311.1.13.1.* "Regular" Normal
FORMAT EventLog entry: $1
</code></pre>
<p>The first enterprise variable (<strong>$1</strong>) contains the complete text that is displayed in the Event Log Description box. Variables are described in more detail in the <strong>Advanced Section</strong>.</p>
<p>After creating the <strong>snmptt.conf.microsoft</strong> file and adding it to the <strong>snmptt.ini</strong>, restart SNMPTT.</p>
<h3>Testing</h3>
<p>To test that the trap is received by SNMPTT, a logon failure in Windows should be created.</p>
<p>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:</p>
<ul>
<li>Open <strong>Administrative Tools</strong></li>
<li>Open <strong>Local Security Policy</strong></li>
<li>Open <strong>Local Policies</strong></li>
<li>Open <strong>Audit Policy</strong></li>
<li>Enable auditing of failures for <strong>Audit account logon events</strong></li>
<li>Enable auditing of failures for <strong>Audit logon events</strong></li>
</ul>
<p>The settings should take effect immediately, and a reboot should not be required.</p>
<p>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 <strong>runas.exe</strong> command from command prompt. For example:</p>
<pre><code>runas /user:fakeuser cmd
</code></pre>
<p>When prompted for a password, press <strong>Enter</strong>.</p>
<p>SNMPTT should log something similar to the following:</p>
<p><strong>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.</strong></p>
<p>The text in the log entry should match the text in the <strong>Description</strong> field of the Event Log entry but without the formatting.</p>
<h3>Advanced Configuration</h3>
<h4>Specific EVENTs</h4>
<p>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.</p>
<p>To determine the trap OID that will be used for the EVENT, display the entry in <strong>evntwin.exe</strong> and combine the <strong>Enterprise OID</strong>, a <strong>0</strong> and the <strong>Trap Specific ID</strong>. For example, for the security event ID 529 used above:</p>
<blockquote>
<p>Enterprise OID: 1.3.6.1.4.1.311.1.13.1.8.83.101.99.117.114.105.116.121</p>
<p>Trap Specific ID: 529</p>
</blockquote>
<p>Based on the information above, the following EVENT line would be used::</p>
<pre><code>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
</code></pre>
<h4>Enterprise variables</h4>
<p>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.</p>
<p>The following lists the enterprise variables that can be used in SNMPTT for each trap:</p>
<ul>
<li>$1:Event Log Description</li>
<li>$2:Event Log User</li>
<li>$3:Event Log Computer</li>
<li>$4:?</li>
<li>$5:?</li>
<li>$6:Event to Trap Translator variable %1</li>
<li>$7:Event to Trap Translator variable %2</li>
<li>$8:Event to Trap Translator variable %3</li>
<li>$9:Event to Trap Translator variable %4</li>
<li>$<em>n</em>:Event to Trap Translator variable %<em>n-5</em></li>
</ul>
<p>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:</p>
<p><strong>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.</strong></p>
<p>By reviewing the Description field as defined in the <strong>evntwin.exe</strong> utility, a new cleaned up FORMAT line can be used that does not contain all the dots.</p>
<p>Following is the text from the Description field in <strong>evntwin.exe</strong> which will be used as a reference. Notice the use of %<em>n</em> 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 %<em>n</em> is a variable number.</p>
<p>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</p>
<p>The EVENT entry could be cleaned up using:</p>
<pre><code>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
</code></pre>
<h2><a name="Hobbit"></a>Xymon / Hobbit</h2>
<p>Information on handling SNMP traps with <a href="https://xymon.sourceforge.io/">Xymon</a> (formerly <a href="http://hobbitmon.sourceforge.net/">Hobbit</a>) can be found at <a href="http://cerebro.victoriacollege.edu/hobbit-trap.html">http://cerebro.victoriacollege.edu/hobbit-trap.html</a>.</p>