SNMP Trap component


The SNMP Trap Camel component sends SNMP Traps to an SNMP server. In this page, learn how to use the SNMP Trap component. 


Compatibility and support

The SNMP Trap component implements versions 1 and 2c and 3 of the SNMP protocol.

For information about the  Simple Network Management Protocol internet standard, see Wikipedia.

To use the SNMP Trap, please use the default udp (user datagram protocol).

Create a library for the SNMP component

  1. On the main menu, click Data Integration. On the left menu, click Libraries.
  2. Click the New Library button.
  3. Give a relevant name to your library and upload the following jars to your library:

    Camel version Library jars Supported SNMP Trap protocol versions
    2.18.3

    udp version1
    udp versrion 2c
    udp version 3

  4. Click Save.


About the SNMP component

URI format

snmp://hostname[:port][?Options]

The SNMP Trap component supports polling Object Identifier (OID) values from an SNMP enabled device and receiving traps.

You can append query options to the URI in the following format, ?option=value&option=value&…

SNMP producer

You can also use the component to request information using GET method.
The response body type is org.apache.camel.component.snmp.SnmpMessage

The SNMP producer can also send SNMP Traps to an SNMP enabled device.
The message body of an SNMP Trap can comprise:

  • a PDU object (to create an object using groovy)
  • or a message in XML format.

URI options

The SNMP component has no options.

The SNMP endpoint is configured using the URI syntax snmp:host:port with the following path and query parameters:

Path Parameters (2 parameters):

Name Description Default Type

host

Required Hostname of the SNMP enabled device


String

port

Required Port number of the SNMP enabled device


Integer

Query parameters (35 parameters):

Name Description Default Type

bridgeErrorHandler (consumer)

Enables bridging the consumer to the Camel routing Error Handler, which means any exceptions that occur while the consumer is trying to pick up, for example, incoming messages, are now processed as a message and handled by the routing Error Handler. By default, the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions that will be logged at WARN or ERROR level and ignored.

false

boolean

delay (consumer)

Sets update rate in seconds

60000

long

oids (consumer)

Defines which values you are interested in. Please have a look at the Wikipedia to get a better understanding. You may provide a single OID or a coma separated list of OIDs. For example: oids=1.3.6.1.2.1.1.3.0,1.3.6.1.2.1.25.3.2.1.5.1,1.3.6.1.2.1.25.3.5.1.1.1,1.3.6.1.2.1.43.5.1.1.11.1


String

protocol (consumer)

All SNMP messages are transported via the User Datagram Protocol (UDP).

udp

String

retries (consumer & trap producer)

Defines how many time a retry is made before canceling the request.

2

int

sendEmptyMessageWhenIdle (consumer)

If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.

false

boolean

snmpCommunity (consumer & trap producer)

Sets the community octet string for the snmp request.

public

String

snmpContextEngineId  (consumer & trap producer)

Sets the context engine ID field of the scoped PDU.


String

snmpContextName (consumer & trap producer)

Sets the context name field of this scoped PDU.


String

snmpVersion (consumer & trap producer)

Sets the snmp version for the request.

/!\

  • The value 0 stands for SNMPv1
  • The value 1 stands for SNMPv2c
  • The value 3 stands for SNMPv3

0

int

timeout (consumer & trap producer)

Sets the timeout value for the request in millis.

1500

int

treeList (consumer)

Sets the flag whether the scoped PDU will be displayed as the list if it has child elements in its tree

false

boolean

type (consumer & trap producer)

Specifies which operation to perform such as poll, trap, etc.


SnmpActionType

exceptionHandler (consumer)

Enables the consumer to use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option cannot be used. By default ,the consumer will deal with exceptions that are logged at WARN or ERROR level and ignore them.


ExceptionHandler

exchangePattern (consumer)

Sets the exchange pattern when the consumer creates an exchange.


ExchangePattern

pollStrategy (consumer)

A pluggable org.apache.camel.PollingConsumerPollingStrategy allowing you to provide your custom implementation to control error handling usually occurred during the poll operation before an Exchange have been created and being routed in Camel.


PollingConsumerPoll Strategy

synchronous (advanced)

Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).

false

boolean

backoffErrorThreshold (scheduler)

The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.


int

backoffIdleThreshold (scheduler)

The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.


int

backoffMultiplier (scheduler)

To let the scheduled polling consumer backoff if there has been a number of subsequent idles/errors in a row. The multiplier is then the number of polls that will be skipped before the next actual attempt is happening again. When this option is in use then backoffIdleThreshold and/or backoffErrorThreshold must also be configured.


int

greedy (scheduler)

If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.

false

boolean

initialDelay (scheduler)

Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).

1000

long

runLoggingLevel (scheduler)

The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.

TRACE

LoggingLevel

scheduledExecutorService (scheduler)

Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.


ScheduledExecutor Service

scheduler (scheduler)

To use a cron scheduler from either camel-spring or camel-quartz2 component.

none

ScheduledPollConsumer Scheduler

schedulerProperties (scheduler)

To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.


Map

startScheduler (scheduler)

Specifies whether the scheduler should be auto-started.

true

boolean

timeUnit (scheduler)

Time unit for initialDelay and delay options.

MILLISECONDS

TimeUnit

useFixedDelay (scheduler)

Controls whether fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.

true

boolean

authenticationPassphrase (security)

The authentication passphrase. If not null, authenticationProtocol must also be not null. RFC3414 11.2 requires passphrases to have a minimum length of 8 bytes.

If the length of authenticationPassphrase is less than 8 bytes an IllegalArgumentException is thrown. (SNMP version3)

Null

String

authenticationProtocol (security)

Authentication protocol to use if security level is set to enable authentication.
The possible values are:

  • None
  • MD5
  • SHA1
  • HMAC128SHA224

  • HMAC192SHA256

  • HMAC256SHA384

  • HMAC384SHA512

The None option for authentication protocol does not perform any authentication, and is therefore not recommended, since the USM would not be secure leaving the SNMP communication vulnerable.

Also note that if authentication is set to none, the authentication password will be disabled and all privacy protocol (encryption) options will also be disabled.

The authentication password should be a strong password or passphrase between 8 and 32 characters in length. This is used in conjunction with the authentication Protocol to perform authentication of SNMP version3 messages.

Null

String

privacyPassphrase (security)

The privacy passphrase. If not null, privacyProtocol must also be not null. RFC3414 11.2 requires passphrases to have a minimum length of 8 bytes. If the length of authenticationPassphrase is less than 8 bytes an IllegalArgumentException is thrown. (SNMP version3)

Null

String

privacyProtocol (security)

The privacy protocol ID to be associated with this user. If set to None=null, this user only supports unencrypted messages.

The possible values are:

  • None
  • TRIDES
  • AES128
  • AES192
  • AES256
  • DES

The privacy protocol is used to encrypt the contents of SNMP version3 messages after authentication has been performed.

Use the None value for privacy protocol disables encryption of SNMP version3 messages and is therefore not recommended.

Null

String

securityLevel (security)

Sets the security level for this target. The supplied security level must be supported by the security model dependent information associated with the securityName set for this target.

  • Value 1 – No authentication and no encryption. Anyone can create and read messages with this security level.
  • Value 2 – Authentication and no encryption. Only the user with the correct authentication key can create messages with this security level, but anyone can read the contents of the message.
  • Value 3 – Authentication and encryption. Only the user with the correct authentication key can create messages with this security level, and only the one with the right encryption/decryption key can read the contents of the message. (SNMP version3)

3

int

securityName (security)

Sets the security name to be used with this target. (SNMP version3)

Null

String

Spring Boot Auto-Configuration

The component supports 2 options, which are listed below.

Name Description Default Type

camel.component.snmp.enabled

Enables the SNMP component.

true

Boolean

camel.component.snmp.resolve-property-placeholders

Specifies whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.

true

Boolean

Example poll result

Let's say that you are polling the following OIDs:

OIDs

1.3.6.1.2.1.1.3.0
1.3.6.1.2.1.25.3.2.1.5.1
1.3.6.1.2.1.25.3.5.1.1.1
1.3.6.1.2.1.43.5.1.1.11.1
1.3.6.1.2.1.1.1.0

The result will be the following:


Result of toString conversion
<?xml version="1.0" encoding="UTF-8"?>
<snmp>
  <entry>
    <oid>1.3.6.1.2.1.1.3.0</oid>
    <value>6 days, 21:14:28.00</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.25.3.2.1.5.1</oid>
    <value>2</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.25.3.5.1.1.1</oid>
    <value>3</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.43.5.1.1.11.1</oid>
    <value>6</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.1.1.0</oid>
    <value>My Very Special Printer Of Brand Unknown</value>
  </entry>
</snmp>

You may notice there is one more result than requested….1.3.6.1.2.1.1.1.0.
In this instance, this extra occurrence was filled in by the device automatically. So, please be aware that your results may sometimes return more hits than originally expected.

OID starting with dot representation

.1.3.6.1.4.1.6527.3.1.2.21.2.1.50

The default snmpVersion is 0 which means version1 in the endpoint if the version is not set not set explicitly. Make sure you explicitly set snmpVersion. This default value should be changed, for example, when you want to query SNMP tables with different versions. Other possible values are version2c (value=1) and version3(value=3).

Examples:

  • Polling a remote device:
snmp:192.168.178.23:161?protocol=udp&type=POLL&oids=1.3.6.1.2.1.1.5.0


  • Setting up a trap receiver (Note that no OID info is needed here!):
snmp:127.0.0.1:162?protocol=udp&type=TRAP

You can get the community of SNMP TRAP with message header 'securityName' and the
peer address of the SNMP TRAP with message header 'peerAddress'.


  • Routing example in Java: (converts the SNMP PDU to XML String)
from("snmp:192.168.178.23:161?protocol=udp&type=POLL&oids=1.3.6.1.2.1.1.5.0").
convertBodyTo(String.class).
to("activemq:snmp.states");


  • Spring XML Schema

<route id="POLL">
    <from uri="snmp:192.168.178.23:161?protocol=udp&type=POLL&oids=1.3.6.1.2.1.1.5.0"/>
    <convertBodyTo type="java.lang.String"/>
    <to uri="activemq:snmp.states"/>
</route>

The SNMP Trap message

To send a Trap message to an SNMP device, you must first create a snmp4j PDU object. To create the PDU object, you can use the groovy language or use an XML message.

One or more object identifiers (OIDs) can be specified in PDU. A type and a value must accompany each object identifier. You must format each variable type.

The following explains how to write an XML message to send an SNMP Trap using URI.

XML Message

The XML message skeleton is like :

<?xml version="1.0" encoding="UTF-8"?>
<snmp version=XXX>
    ENTRY_LIST
</snmp>

The message is compatible with the toString conversion of polling solution.

The SNMP Trap can send messages for 3 protocols versions. Each version has its specificities in terms of type, parameter, and URI.

You can specify:

  • The OID value type to send the correct OID value type.
  • The characteristic parameter linked to SNMP version1.


The  PDU message version and the URI connection version must be the same version.

OID values types

The SNMP Trap can send multiple type of OIDs values.

If the type is not defined, the default OID value type used is String.


Type name Datatype description Usable in version
1 2c 3

Integer

Integer32

x x x

Unsigned

UnsignedInteger32

x x x

Gauge

Gauge32, a non-negative integer

x x x

String

OCTET STRING

x x x

HexString

OCTET STRING specified as hex string where bytes separated by colons (':')

x x x

DecimalString

OCTET STRING specified as decimal string where bytes are separated by dots ('.')

x x x

NullObj

Null value

x x x

ObjID

Object Identifier

x x x

TimeTicks

Time in 1/100th of seconds since agent initialized

x x x

IpAddress

IpAddress

x x x

Counter

Counter32, a non-negative integer

x x x

Counter64

Counter64


x x

Bits

OCTET STRING specified as binary string where bytes are separated by spaces

x x x

Parameter name

SNMP parameter tag name Type of value
Description Usable in version
1 2c 3

enterprise

Object Identifier

Indicates the type of object that generated the trap. x

agent-addr

IpAddress

The IP address of the SNMP agent that generated the trap. This is of course also in the IP header at lower levels but inclusion in the SNMP message format allows for easier trap logging within SNMP. Also, in the case of a multihomed host, this specifies the preferred address. x

generic-trap

Integer32

A code value specifying one of a number of predefined “generic” trap types. (see the table below) x

specific-trap

Integer32

A code value indicating an implementation-specific trap type. x

time-stamp

UnsignedInteger32

The amount of time since the SNMP entity sending this message last initialized or reinitialized. Used to time stamp traps for logging purposes. x

request-id

Integer32

An Integer that identifies a particular SNMP request. This index is echoed back in the response from the SNMP agent, allowing the SNMP manager to match an incoming response to the appropriate request.
x x

Generic trap type

Value Type Description
0 coldStart A coldStart trap signifies that the sending protocol entity is reinitializing itself so that the agent’s configuration or the protocol entity implementation can be altered.
1 warmStart A warmStart trap signifies that the sending protocol entity is reinitializing itself so that neither the agent configuration nor the protocol entity implementation can be altered.
2 linkDown A linkDown trap signifies that the sending protocol entity recognizes a failure in one of the communication links represented in the agent’s configuration.

A Trap-PDU of type linkDown contains, as the first element of its variable-bindings, the name and value of the ifIndex instance for the affected interface.

3 linkUp 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.

A Trap-PDU of type linkUp contains, as the first element of its variable-bindings, the name and value of the ifIndex instance for the affected interface.

4 authenticationFailure An authenticationFailure trap signifies that the sending protocol entity is the addressee of a protocol message that is not properly authenticated.
5 egpNeighborLoss An egpNeighborLoss trap signifies that an EGP neighbor for whom the sending protocol entity was an EGP peer has been marked down and the peer relationship no longer exists.

The Trap-PDU of the egpNeighborLoss contains, as the first element of its variable-bindings, the name and value of the egpNeighAddr instance for the affected neighbor.

6 enterpriseSpecific An enterpriseSpecific trap signifies that the sending protocol entity recognizes that some Enterprise-specific event has occurred. The specific-trap field identifies the particular trap that occurred.


The  PDU message version and the URI connection version must be the same version.

Examples


  • For SNMP version 1

    In this case, the SNMP Trap send the message type String : "My Very Special Printer Of Brand Unknown" on OID 1.3.6.1.2.1.1.1.0 of the MIB using SNMP udp protocol version 1.
    The version 1 parameters  used ares :

        • the enterprise with the OID value 1.3.6

        • the agent address  witht he IP value 10.0.12.13.14
        • the generic trap code with the integer value 3 meaning linkUp.
        • the specific trap code with the integer value 4
        • the time stamp with the long value 5000 milliseconds


Routing example in Java: (converts the XML String to SNMP PDU)
from("direct:snmptrap")
        .setBody(simple("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n" +
            "<snmp>\n" +
            "  <entry>\n" +
            "    <enterprise>1.3.6</enterprise>\n" +
            "  </entry>\n" +
            "  <entry>\n" +
            "    <agent-addr>10.0.12.13</agent-addr>\n" +
            "  </entry>\n" +
            "  <entry>\n" +
            "    <generic-trap>3</generic-trap>\n" +
            "  </entry>\n" +
            "  <entry>\n" +
            "    <specific-trap>4</specific-trap>\n" +
            "  </entry>\n" +
            "  <entry>\n" +
            "    <time-stamp>5000</time-stamp>\n" +
            "  </entry>\n"+
            "  <entry>\n" +
            "    <oid>1.3.6.1.2.1.1.1.0</oid>\n" +
            "    <value>My Very Special Printer Of Brand Unknown</value>\n" +
            "  </entry>\n" +
            "</snmp>"))
        .convertBodyTo(PDU.class)
        .to("snmp://snmp.host.com:162?type=TRAP");
Spring XML Schema
<route>
    <setBody>
        <simple><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<snmp>
  <entry>
    <enterprise>1.3.6</enterprise>
  </entry>
  <entry>
    <agent-addr>10.0.12.13</agent-addr>
  </entry>
  <entry>
    <generic-trap>3</generic-trap>
  </entry>
  <entry>
    <specific-trap>4</specific-trap>
  </entry>
  <entry>
    <time-stamp>5000</time-stamp>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.1.1.0</oid>
    <value>My Very Special Printer Of Brand Unknown</value>
  </entry>
</snmp>]]></simple>
    </setBody>
    <convertBodyTo type="org.snmp4j.PDU"/>
    <to uri="snmp://snmp.host.com:162?type=TRAP"/>
</route>


  • For version 2c

    In this case the SNMP Trap send the message type String : "My Very Special Printer Of Brand Unknown" on OID 1.3.6.1.2.1.1.1.0 of the MIB using SNMP udp protocol version 2c


Routing example in Java: (converts the XML String to SNMP PDU)
from("direct:snmptrap")
        .setBody(simple("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n" +
            "<snmp version=\"1\">\n" +
            "  <entry>\n" +
            "    <oid>1.3.6.1.2.1.1.1.0</oid>\n" +
            "    <value>My Very Special Printer Of Brand Unknown</value>\n" +
            "  </entry>\n" +
            "</snmp>"))
        .convertBodyTo(PDU.class)
        .to("snmp://snmp.host.com:162?type=TRAP&snmpVersion=1");
Spring XML Schema
<route>
    <setBody>
        <simple><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<snmp version="1">
  <entry>
    <oid>1.3.6.1.2.1.1.1.0</oid>
    <value>My Very Special Printer Of Brand Unknown</value>
  </entry>
</snmp>]]></simple>
    </setBody>
    <convertBodyTo type="org.snmp4j.PDU"/>
    <to uri="snmp://snmp.host.com:162?type=TRAP&amp;snmpVersion=1"/>
</route>
  • For SNMP version 3

    In this case the SNMP Trap send the message type String : "My Very Special Printer Of Brand Unknown" on OID 1.3.6.1.2.1.1.1.0 of the MIB using SNMP udp protocol version 3
    The URI version 3 parameters  used ares :

        • the security level with the integer value 3 meaning authentication and encryption.
        • thesecurity name with the string value aSecurityName.

        • the authentication protocol with the string value  SHA1
        • the authentication passphrase with the string value  passphrase
        • the privacy protocol with the string value DES
        • the privacy passphras with the string value passphrase
        • the SNMP context name with the string value aContextName


Routing example in Java: (converts the XML String to SNMP PDU)
from("direct:snmptrap")
        .setBody(simple("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n" +
            "<snmp version=\"3\">\n" +
            "  <entry>\n" +
            "    <oid>1.3.6.1.2.1.1.1.0</oid>\n" +
            "    <value>My Very Special Printer Of Brand Unknown</value>\n" +
            "  </entry>\n" +
            "</snmp>"))
        .convertBodyTo(PDU.class)
        .to("snmp://snmp.host.com:162?type=TRAP&snmpVersion=3&securityLevel=3" +
                "&securityName=aSecurityName" +
                "&authenticationProtocol=SHA1"+
                "&authenticationPassphrase=passphrase" +
                "&privacyProtocol=DES"+
                "&privacyPassphrase=passphrase"+
                "&snmpContextName=aContextName");    
Spring XML Schema
<route>
    <setBody>
        <simple><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<snmp version="3">
  <entry>
    <oid>1.3.6.1.2.1.1.1.0</oid>
    <value>My Very Special Printer Of Brand Unknown</value>
  </entry>
</snmp>]]></simple>
    </setBody>
    <convertBodyTo type="org.snmp4j.PDU"/>
    <to uri="snmp://snmp.host.com:162?type=TRAP&amp;snmpVersion=3&amp;securityLevel=3&amp;securityName=aSecurityName&amp;authenticationProtocol=SHA1&amp;authenticationPassphrase=passphrase&amp;privacyProtocol=DES&amp;privacyPassphrase=passphrase&amp;snmpContextName=aContextName"/>
</route>
Messages with different value types
<?xml version="1.0" encoding="UTF-8"?>
<snmp version="3">
  <entry>
    <oid>1.3.6.1.2.1.1.3.201</oid>
    <value type="Integer">12</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.25.3.2.1.5.1</oid>
    <value type="Unsigned">2</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.25.3.2.1.5.1</oid>
    <value type="Gauge">2</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.25.3.2.1.5.1</oid>
    <value type="Counter">2</value>
  </entry>
  <entry>
     <oid>1.3.6.1.2.1.25.3.2.1.5.1</oid>
    <value type="Counter64">2</value>
  </entry>
  <entry>
    <oid>1.3.6.1.4.1.8072.2.3.2.2</oid>
    <value type="String">a string</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.43.5.1.1.11.1</oid>
    <value type="HexString">61:62:79:74:65</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.43.5.1.1.11.1</oid>
    <value type="DecimalString">97.98.121.116.101</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.43.5.1.1.11.1</oid>
    <value type="Bits">1100001 1100010 1111001 1110100 1100101</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.43.5.1.1.11.1</oid>
    <value type="NullObj"/>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.43.5.1.1.11.1</oid>
    <value type="ObjID">1.3.6.1.2.1.43.5.1</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.43.5.1.1.11.1</oid>
    <value type="TimeTicks">1000</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.43.5.1.1.11.1</oid>
    <value type="IpAddress">127.0.0.1</value>
  </entry>
  <entry>
    <oid>1.3.6.1.2.1.1.1.0</oid>
    <value>My Very Special Printer Of Brand Unknown</value>
  </entry>
</snmp>

Related Links