|
|
|
|
Various router/switch/network appliances and applications have the ability to send SNMP traps to indicate some event has transpired. Traverse has the ability to accept such SNMP traps from devices it is monitoring and display these messages as well as trigger an action using the Message Handler framework, when a pattern is matched.
In order for Traverse to process SNMP traps, the end devices need to be configured to send traps to the host running the Traverse Message Handler. Please refer to the respective documentation of the router, server or application to find out how to configure trap destinations. On a Cisco running IOS, a sample configuration command for sending SNMP traps to the DGE is:
snmp-server host ip.of.dge version 2c myCommunityID snmp
The Trap Message Source
The trap message source handles SNMP traps and by default it is configured to run on port 162. The configuration entry in <TRAVERSE_HOME>/etc/messages/snmp/00_src_snmp_trap.xml for the Message Handler is as follows:
<source type="trap" name="trap162">
<enabled>true</enabled>
<port>162</port>
<performHostnameLookup>false</performHostnameLookup>
<relay oid=".1.3.6.1.4.1.10844.1.1.255.1">
<destination host="localhost" port="9991" communityId="public"/>
<destination host="127.0.0.1" port="9991" communityId="public"/>
</relay>
<trapHandle oid=".1.3.6.1.4.1.10844.1.1.255.1">
<script>/tmp/trapreceived.sh</script>
</trapHandle>
</source>
You can choose to run the trap handler at an alternate (UDP) port other than the standard port 162 by modifying the port parameter. In that case, make sure to specify the alternate destination port number on remote devices that will send SNMP traps.
To avoid your changes getting overwritten during Traverse upgrades, you should add these entries as plug-ins in nn_src_yyy.xml configuration files in the <TRAVERSE_HOME>/plugins/messages/ directory.
The performHostnameLookup parameter controls whether the trap handler will attempt to resolve the host name of remote hosts when a trap is received. As slow DNS resolutions may impact performance, the default option disables this feature.
Once any of these values have been changed, the Message Handler will need to be restarted before the change is applied. At this point the trap handler should be ready to accept SNMP traps.
Relaying SNMP Traps
In certain cases, you may wish to relay the SNMP traps to another application. You can relay all or selected traps to one or more hosts:
<source type="trap" name="trap162">
<!-- forward traps to hostA -->
<relay oid=".1.3.6.1.4.1.10844.*">
<destination host="192.168.1.1" port="162" communityId="public"/>
</relay>
<!-- forward all other to hostB and hostC -->
<relay oid="default">
<destination host="192.168.2.2" port="162" communityId="public"/>
<destination host="192.168.5.5" port="8162" communityId="secret"/>
</relay>
</source>
In the above example, all enterprise traps for Technology MIB with prefix .1.3.6.1.4.1.10844 is relayed to a management agent (specified in destination element) running on host 192.168.1.1, on UDP port 162. Note the use of the * as wildcard in the oid parameter. If you wish to forward only specific traps, you can use exact OID.
The second relay configuration block has an oid value default, which has special meaning and covers any OID not explicitly specified in other relay blocks. The default OID is optional and if not specified, in the absence of a matching relay block, the trap will not be forwarded to any other host. In this case all traps are forwarded to two hosts, each with different port and community string.
Passing SNMP Traps to External Scripts
The trap handler also allows SNMP traps to be passed to external scripts, which can further process them:
<source type="trap" name="trap162">
<!-- forward nodeDeleted traps to a script -->
<trapHandle oid=".1.3.6.1.4.1.10844.1.1.255.2.1">
<script>/usr/bin/nodeDeleted.pl</script>
</trapHandle>
</source>
The same rules for wildcard (*) and default OID as relay configuration applies to trapHandle configuration. Upon match, the specified script is executed and trap information is made available via standard input (STDIN) in the following format, one entry per line in sequential order:
remote_device host_name
remote_device ip_address
system.sysUpTime.0 uptime
snmpTrap.snmpTrapEnterpriseOID enterprise_oid
varbind_oid1 varbind_value1
varbind_oid2 varbind_value2
[...]
varbind_oidN varbind_valueN
If DNS resolution is disabled, or failed, host_name will be same as ip_address. uptime represents number of seconds since remote agent was started or initialized.
Loading Enterprise MIBs for SNMP Traps
To load MIB files into the trap handler so that incoming traps are automatically converted into their MIB text definitions, copy the MIB files with extension .mib/.my/.txt into the plugin/mibs directory. The trap handler automatically loads all MIB files located in the <TRAVERSE>/etc/mibs and the <TRAVERSE>/plugin/mibs/ directory and looks for new files in these directories every minute.
If a match for the incoming OID is not found, the trap will be logged with the numeric OID. If a file cannot be parsed due to a syntax error or missing dependencies, an error message is logged. If you remove a MIB file from the mib directory, you must restart the message handler since this change will not be handled automatically (due to the possibilities of dependencies, etc.).
When you add a new MIB into the plugins/ directory, you must look at the IMPORTS directives in these MIB files to see the dependent MIB files and copy those into this directory as well and also look in these new files for additional IMPORTS directives. For example, in order to get the IF-MIB loaded, the following MIB definition files needed to be added because of the IMPORTS: