Net::SNMPTrapd - Perl implementation of SNMP Trap Listener
use Net::SNMPTrapd; my $snmptrapd = Net::SNMPTrapd->new() or die "Error creating SNMPTrapd listener: ", Net::SNMPTrapd->error; while (1) { my $trap = $snmptrapd->get_trap(); if (!defined($trap)) { printf "$0: %s\n", Net::SNMPTrapd->error; exit 1 } elsif ($trap == 0) { next } if (!defined($trap->process_trap())) { printf "$0: %s\n", Net::SNMPTrapd->error } else { printf "%s\t%i\t%i\t%s\n", $trap->remoteaddr, $trap->remoteport, $trap->version, $trap->community } }
Net::SNMPTrapd is a class implementing a simple SNMP Trap listener in Perl. Net::SNMPTrapd will accept traps on the default SNMP Trap port (UDP 162) and attempt to decode them. Net::SNMPTrapd supports SNMP v1 and v2c traps and SNMPv2 InformRequest and implements the Reponse.
Net::SNMPTrapd uses Convert::ASN1 by Graham Barr to do the decoding.
my $snmptrapd = Net::SNMPTrapd->new([OPTIONS]);
Create a new Net::SNMPTrapd object with OPTIONS as optional parameters. Valid options are:
Option Description Default ------ ----------- ------- -Family Address family IPv4/IPv6 IPv4 Valid values for IPv4: 4, v4, ip4, ipv4, AF_INET (constant) Valid values for IPv6: 6, v6, ip6, ipv6, AF_INET6 (constant) -LocalAddr Interface to bind to any -LocalPort Port to bind server to 162 -timeout Timeout in seconds for socket 10 operations and to wait for request
NOTE: IPv6 requires IO::Socket::IP. Failback is IO::Socket::INET and only IPv4 support.
Allows the following accessors to be called.
$snmptrapd->server();
Return IO::Socket::IP object for the created server. All IO::Socket::IP accessors can then be called.
my $trap = $snmptrapd->get_trap([OPTIONS]);
Listen for SNMP traps. Timeout after default or user specified timeout set in new method and return '0'. If trap is received before timeout, return is defined. Return is not defined if error encountered.
new
Valid options are:
Option Description Default ------ ----------- ------- -maxsize Max size in bytes of acceptable PDU. 65467 Value can be integer 1 <= # <= 65467. Keywords: 'RFC' = 484 'recommended' = 1472 -timeout Timeout in seconds to wait for 10 request. Overrides value set with new().
$trap->remoteaddr();
Return remote address value from a received (get_trap()) SNMP trap. This is the address from the IP header on the UDP datagram.
get_trap()
$trap->remoteport();
Return remote port value from a received (get_trap()) SNMP trap. This is the port from the IP header on the UDP datagram.
$trap->datagram([1]);
Return the raw datagram from a received (get_trap()) SNMP trap. This is ASN.1 encoded datagram. For a hex dump, use the optional boolean argument.
$trap->process_trap([OPTIONS]);
Process a received SNMP trap. Decodes the received (get_trap()) PDU. Varbinds are extracted and decoded. If PDU is SNMPv2 InformRequest, the Response PDU is generated and sent to IP address and UDP port found in the original datagram header (get_trap() methods remoteaddr() and remoteport()).
remoteaddr()
remoteport()
Called with one argument, interpreted as the datagram to process. Valid options are:
Option Description Default ------ ----------- ------- -datagram Datagram to process -Provided by get_trap()- -noresponse Binary switch (0|1) meaning 'Do not 0 send Response-PDU for InformRequest' -Send Response-
This can also be called as a procedure if one is inclined to write their own UDP listener instead of using get_trap(). For example:
$sock = IO::Socket::IP->new( blah blah blah ); $sock->recv($datagram, 1500); # process the ASN.1 encoded datagram in $datagram variable $trap = Net::SNMPTrapd->process_trap($datagram);
or
# process the ASN.1 encoded datagram in $datagram variable # Do *NOT* send Response PDU if trap comes as InformRequest PDU $trap = Net::SNMPTrapd->process_trap( -datagram => $datagram, -noresponse => 1 );
In any instantiation, allows the following accessors to be called.
$trap->version();
Return SNMP Trap version from a received and processed (process_trap()) SNMP trap.
process_trap()
NOTE: This module only supports SNMP v1 and v2c.
$trap->community();
Return community string from a received and processed (process_trap()) SNMP trap.
$trap->pdu_type([1]);
Return PDU type from a received and processed (process_trap()) SNMP trap. This is the text representation of the PDU type. For the raw number, use the optional boolean argument.
$trap->varbinds();
Return varbinds from a received and processed (process_trap()) SNMP trap. This returns a pointer to an array containing a hash as each array element. The key/value pairs of each hash are the OID/value pairs for each varbind in the received trap.
[{OID => value}] [{OID => value}] ... [{OID => value}]
An example extraction of the varbind data is provided:
for my $vals (@{$trap->varbinds}) { for (keys(%{$vals})) { $p .= sprintf "%s: %s; ", $_, $vals->{$_} } } print "$p\n";
The above code will print the varbinds as:
OID: value; OID: value; OID: value; [...]
The following methods are SNMP v1 trap specific.
$trap->ent_OID();
Return enterprise OID from a received and processed (process_trap()) SNMP v1 trap.
$trap->agentaddr();
Return agent address from a received and processed (process_trap()) SNMP v1 trap.
$trap->generic_trap([1]);
Return generic trap type from a received and processed (process_trap()) SNMP v1 trap. This is the text representation of the generic trap type. For the raw number, use the optional boolean argument.
$trap->specific_trap();
Return specific trap type from a received and processed (process_trap()) SNMP v1 trap.
$trap->timeticks();
Return timeticks from a received and processed (process_trap()) SNMP v1 trap.
The following methods are SNMP v2c trap specific.
$trap->request_ID();
Return request ID from a received and processed (process_trap()) SNMP v2c trap.
$trap->error_status();
Return error_status from a received and processed (process_trap()) SNMP v2c trap.
$trap->error_index();
Return error index from a received and processed (process_trap()) SNMP v2c trap.
printf "Error: %s\n", Net::SNMPTrapd->error;
Return last error.
$trap->dump();
Net::SNMPTrapd->dump($datagram);
This does not use any of the Net::SNMPTrapd ASN.1 structures; rather, it uses the Convert::ASN1 module debug routines (asn_dump and asn_hexdump) to attempt a decode and hex dump of the supplied datagram. This is helpful to eliminate the entire Net::SNMPTrapd module code when troubleshooting issues with decoding and focus solely on the ASN.1 decode of the given datagram.
asn_dump
asn_hexdump
Called as a method, operates on the value returned from the datagram() method. Called as a subroutine, operates on the value passed.
datagram()
Output is printed directly to STDERR. Return is defined unless there is an error encountered in getting the datagram to operate on.
None by default.
This distribution comes with several scripts (installed to the default "bin" install directory) that not only demonstrate example uses but also provide functional execution.
Convert::ASN1
This software is released under the same terms as Perl itself. If you don't know what that means visit http://perl.com/.
Copyright (C) Michael Vincent 2010
http://www.VinsWorld.com
All rights reserved
To install Net::SNMPTrapd, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::SNMPTrapd
CPAN shell
perl -MCPAN -e shell install Net::SNMPTrapd
For more information on module installation, please visit the detailed CPAN module installation guide.