new() - create a new Net::SNMPTrapd object

  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.

server() - return IO::Socket::IP object for server

  $snmptrapd->server();

Return IO::Socket::IP object for the created server. All IO::Socket::IP accessors can then be called.

get_trap() - listen for SNMP traps

  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.

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().

Allows the following accessors to be called.

remoteaddr() - return remote address from SNMP trap

  $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.

remoteport() - return remote port from SNMP 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.

datagram() - return datagram from SNMP trap

  $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.

process_trap() - process received SNMP trap

  $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()").

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.

version() - return version from SNMP trap

  $trap->version();

Return SNMP Trap version from a received and processed ("process_trap()") SNMP trap.

NOTE: This module only supports SNMP v1 and v2c.

community() - return community from SNMP trap

  $trap->community();

Return community string from a received and processed ("process_trap()") SNMP trap.

pdu_type() - return PDU type from 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.

varbinds() - return varbinds from SNMP trap

  $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; [...]

SNMP v1 SPECIFIC

The following methods are SNMP v1 trap specific.

ent_OID() - return enterprise OID from SNMP v1 trap

  $trap->ent_OID();

Return enterprise OID from a received and processed ("process_trap()") SNMP v1 trap.

agentaddr() - return agent address from SNMP v1 trap

  $trap->agentaddr();

Return agent address from a received and processed ("process_trap()") SNMP v1 trap.

generic_trap() - return generic trap from 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.

specific_trap() - return specific trap from SNMP v1 trap

  $trap->specific_trap();

Return specific trap type from a received and processed ("process_trap()") SNMP v1 trap.

timeticks() - return timeticks from SNMP v1 trap

  $trap->timeticks();

Return timeticks from a received and processed ("process_trap()") SNMP v1 trap.

SNMP v2c SPECIFIC

The following methods are SNMP v2c trap specific.

request_ID() - return request ID from SNMP v2c trap

  $trap->request_ID();

Return request ID from a received and processed ("process_trap()") SNMP v2c trap.

error_status() - return error status from SNMP v2c trap

  $trap->error_status();

Return error_status from a received and processed ("process_trap()") SNMP v2c trap.

error_index() - return error index from SNMP v2c trap

  $trap->error_index();

Return error index from a received and processed ("process_trap()") SNMP v2c trap.

error() - return last error

  printf "Error: %s\n", Net::SNMPTrapd->error;

Return last error.

dump() - Convert::ASN1 direct decode and hex dump

  $trap->dump();

or

  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.

Called as a method, operates on the value returned from the "datagram()" method. Called as a subroutine, operates on the value passed.

Output is printed directly to STDERR. Return is defined unless there is an error encountered in getting the datagram to operate on.