12.0 Sending Traps and Informs

 

12.1 Overview

12.2 Generating Traps

12.3 Manager Details for Sending Traps

12.4 Adding Manager Entries

12.5 Testing the Agent with Traps

12.6 Knowing the Details of the Trap Generated

12.7 Validating and Filtering Outgoing Traps

12.8 Implementing Your Own Table for Storing Manager Information

12.9 Implementing Informs

12.10 Sending Traps for Log Messages, implemented using Log4j

12.11 Running the Example

 

12.1 Overview

 

In addition to retrieving data from the Managed Resource and sending response to them, Agents have the ability to send unsolicited messages to Managers when they detect some significant event. An unsolicited message of this sort is called Trap (in SNMPv1) or Notification (in SNMPv2 and SNMPv3). The WebNMS Java Agent supports both Traps and Notifications in all the three versions of SNMP. Informs, on the other hand, are Notifications sent from the Agent, with a request to the Manager to acknowledge the receipt of such a Notification.

 

12.2 Generating Traps

 

For the SNMP Agent to generate a Trap/Notification, the respective MIB should have definition for that Trap/Notification. To define a Trap Type Construct (in SNMPv1 MIB Module) or Notification Type Construct (in  SNMPv2c Module) using MIB Editor, please refer to the 4.6 Adding a Trap/Notification section.

 

12.2.1 Method Generated for Traps

 

For each Trap/ Notification type construct in the MIB modules of the agent, the following method will be generated in the file <MainFileName>Trap.java:

Here the user is required to provide the inputs to the above methods. The required inputs are as follows:

With the above inputs, the method sendNotificfation() is called internally to send the trap/notification to the manager.

    Note: The names provided for the managed objects in notifHash and instanceHash should be exactly the same as that of the MIB module used for agent development.

12.2.2 Generating Trap on SET

 

It is possible to generate traps while setting a value to a variable for which trap is defined. The trap generation method is invoked on SNMP SET and is called from the respective xxxRequestHandler.java file. By default, this option is enabled . To view this,

12.3 Manager Details for Sending Traps

 

To notify the manager about the significant state of change in the agent, it is required to store the manager information in the agent side. To maintain the manager's information, we make use of the Trap Forwarding Tables of AGENT-SNMP-CONFIG-MIB.

 

Before moving into the Trap Forwarding Table, let us see a brief on IPv6 implementation in SNMP agent.

 

IPv4 is the generally used addressing model. Agent Toolkit introduces IPv6 (IP Version 6 protocol) model, which is a completely new and redesigned network-layer protocol defining an advanced addressing format of IPv4. IPv6 is a 128-bit identifier, addressing interfaces and set of interfaces. Agent Toolkit SNMP agent also provides the IPv6 addressing support apart from IPv4 for any network communication between the agent and the manager. Accordingly, the changes have been implemented in the trap forwarding table.

 

Note: When the agent needs to support IPv6 addressing model, it must run on JDK1.4.1 and later.

 

12.3.1 v1v2TrapForwardingTable  

 

The v1v2TrapForwarding Table with the OID .1.3.6.1.4.1.2162.10.3.1.2.2.1 has the following columns defined in it for storing v1/v2c Manager's information:

12.3.2 v3TrapForwardingTable

 

The v3TrapForwardingTable with the OID .1.3.6.1.4.1.2162.10.3.1.2.2.2 has the following columns defined in it for storing v3 Manager's information:

This table is multilingual by nature, i.e., it can forward any version of traps to the managers registered in the table. For a v3 trap, the agent calls the IsAccessAllowed() method according to VACM MIB for each variable binding OID and trap OID. If there is no access for the user in the VACM tables, the notification will not be sent to that management target.

 

12.4 Adding Manager Entries

 

There are two ways to add Manager entries in the Trap Forwarding Table. It can be done either : (1) Before Agent start-up or (2) During runtime.

 

12.4.1 Before Agent Startup

 

To specify the manager entries at startup, you can use MIB Compiler UI, Text File / XML File, Runtime Memory or the API.

 

Using MIB Compiler UI

    1. Choose the Project ->Settings menu of MIB Compiler UI. Please note that the version of the Agent has to be V1/V2c for working with v1v2TrapForwarding Table and V3 for working with V3TrapForwardingTable. This can be specified in the Project -> Settings menu -> General panel.

    2. Select v1v2TrapForwardingTable or v3TrapForwardingTable in the Trap Panel.

    3. Click Add. By default, you will have an entry with values : IPv4/IPv6, 127.0.0.1/0:0:0:0:0:0:0:1, 8003, Version 2, public, 5000, 0 and Active 1 in V1V2TrapForwardingTable and IPv4/IPv6, 0.0.0.0.0.0.0.1/127.0.0.1, 8003, Version 3, public, noAuthUser, 3, noAuthNoPriv, noAuth, 5000, 0, Active 1 for V3 Trap Forwarding Table. A wizard pops up wherein you can specify the manager entries (v1/v2 or v3).

    4. Click OK. The manager entry is added.

Using Text File / XML File

 

The entries configured in MIB Compiler UI are stored in the configuration files, V1V2TrapForwardingTable.xml or V1V2TrapForwardingTable.txt after generation. These files can be found under the <Agent Toolkit Home>/snmpprojects/projectname/agent/bin/conf directory.

 

To specify the type of storage option,

    1. Choose the Project -> Settings menu of MIB Compiler UI.

    2. Select the v1v2 or v3TrapForwardingTable from the Trap panel.

    3. Choose XML File or Text File from the Storage Type option. By default, XML File is chosen.

These files can also be edited to add manager entries. The V1V2TrapForwardingTable.xml given below has been edited for adding a new manager with host "128.0.0.1"  and manager port "8004".

    <?xml version="1.0" encoding="UTF-8"?>

    <Table>

    <row>

    <column name="managerHostType" value="1"></column>

    <column name="managerHost" value="127.0.0.1"></column>

    <column name="managerPort" value="8003" ></column>

    <column name="version" value="2" ></column>

    <column name="community" value="public" ></column>

    <column name="timeOut" value="1000" ></column>

    <column name="retries" value="0" ></column>

    <column name="rowStatus" value="1" ></column>

    </row>

     

    //Adding new row

    <row>

    <column name="managerHostType" value="1"></column>

    <column name="managerHost" value="128.0.0.1" ></column>

    <column name="managerPort" value="8004" ></column>

    <column name="version" value="2" ></column>

    <column name="community" value="public" ></column>

    <column name="timeOut" value="1000" ></column>

    <column name="retries" value="0" ></column>

    <column name="rowStatus" value="1" ></column>

    </row>

     

    </Table>

Similarly, IPv6 entries can be added in the V1V2cTrapForwardingTable.xml or .txt file and v3 entries in the  V3TrapForwardingTable.xml or .txt file. Please note that the agent has to be restarted for the changes to take effect. You can also access the new entries without restarting the agent. Make use of the following method in the main file for the agent to read the entries directly from the text file.

This method has to be added after the code for trapForwardingTable Request Handler instantiation. Please note that this method is in the SnmpTrapService class common to both V1V2 and V3 Trap Forwarding Tables.

 

Using Runtime Memory

 

Runtime memory can be used to store the Manager information in the Agent Memory . Using this option will not store the entries in text files or xml files.

 

To use the run time memory for adding Manager entries dynamically,

    1. Choose the Project -> Settings menu of MIB Compiler UI.

    2. Select v1v2TrapForwardingTable or v3TrapForwardingTable from the Trap panel.

    3. Select Runtime Memory from Storage Type.

    4. Add entries using the Add option.

After this, follow the steps given in adding entries "From the Manager" section of During Runtime (12.4.2) explained below. Please note that once the agent is killed, the added entries are removed from the memory.

 

Using API calls

 

For adding an entry through API calls, an entry similar to the one given below has to be included next to the trapListener.setTrapForwardingTable (forwardingTable) method in the generated Main file.

 

For v1v2TrapForwarding Table

For v3TrapForwarding Table

    forwardingTable.addV3ForwardingEntry(com.adventnet.snmp.snmp2.agent.V3SimpleTrapForwardingTable.createV3ForwardingEntry(new Integer(1), "127.0.0.1", new Integer(8004), new Integer(3), "public", "noAuthUser", new Long(3), new Integer(1), "noAuth", new Long(5000), new Long (0));

After adding these entries save the Main file and compile it. As per the entries added in V1 V2 Trap Forwarding Table / v3 Trap Forwarding Table, Traps will be forwarded to the Manager running at port 8004. You should be able to receive Traps at port 8004.

 

12.4.2 During Run Time (Dynamic Registration)

 

Manager entries can be added dynamically during runtime.

 

From the Manager

 

To add an Entry from remote,

    1. Load the AGENT-SNMP-CONFIG-MIB in MIB Browser application.

    2. Select v1v2TrapForwardingTable or v3TrapForwardingTable from the traptables module of agentConfiguration group.

    3. By selecting the respective table and clicking SNMP Table icon in MIB Browser will open up a wizard wherein entries can be added to the Trap Forwarding Table on clicking Add.

    4. The entries added from remote get updated in the text/xml file.

    5. Please note that it is possible to access the table from remote only if "Remote Configuration" is enabled in the Trap Panel (V1V2TrapForwardingTable/V3TrapForwardingTable) of Project -> Settings menu in MIB Compiler UI.

    6. You can also enable "Remote Configuration" option using the following API call if it is not chosen before generation.

This method has to be included in the initAdventNetSnmpAgent() method.

 

12.5 Disable Startup trap

 

By default, the generated agent sends coldstart trap at the agent startup to the managers being configured. The user can disable the trap at agent startup by enabling the option provided in the MIB Compiler UI by choosing Project->Settings->Source Generation ->Disable Startup Trap.

 

The Startup Trap can also be disabled by adding the following code in the main file before restartSnmpAgent( ) method

12.6 Testing the Agent for Traps

 

To test the Trap feature,

  1. Start the MIB Browser application.

  2. Open the Trap Viewer in MIB Browser application and start listening for Traps in the Manager's port specified in the Trap forwarding Table.

  3. Load the respective MIB in the MIB Browser application and start the Agent at the port (say default port) 8001 using run.bat or run.sh from <Agent Toolkit Home>/snmpprojects/projectname/agent/bin directory .

  4. At first, you receive a cold start trap. The details of the Trap can be viewed by selecting the Trap and right clicking on it.

  5. Now, SET a value to a variable for which Trap is defined.

  6. Value would be set for the variable and a Trap will be received in the Manager's Port (mentioned in the Trap Forwarding Table).

12.6 Knowing the Details of the Trap Generated (Reliable Traps)

 

There are times where the generated Traps could have been missed or lost during communication. In a situation like this, the Manager might not be aware as to how many traps were generated by the Agent and the details of those Traps. To overcome the uncertainty involved in receiving traps, the option of sending Reliable Traps is provided.

 

12.6.1 Implementing Reliable Traps

 

This feature can be implemented either from MIB Compiler UI or by using API calls.

 

Using MIB Compiler UI

By default, the Maximum number of Traps that can be stored by the Agent is 10 and so the last 10 traps are stored here. This value is configurable.

 

Using API Calls

 

Add the following piece of code in the Main file generated before the code for restartSnmpAgent.

12.6.2 Accessing the Trap Details

 

To know the information of Traps generated from the Agent's two tables, namely the notificationLogTable and notificationVarbindTable have been included under the notificationLogs group of AGENT-SNMP-CONFIG-MIB file. These tables help the Manager in finding out the details of the Traps by just sending a query to the Agent. Try acquiring the Trap details by loading the MIB in MIB Browser and querying.

 

The notificationLogTable stores information of the Traps sent from the Agent (Request ID, Version of the Trap, Time etc.,). The Varbind Table stores information of the varbind values present in the Trap PDU (such as OID, Value, Type, etc.,).

 

12.7 Validating and Filtering Outgoing Traps

 

There are times where the Traps generated by an Agent might be of no use to a Manager. In this case, the Agent drops those Traps without sending them to that particular Manager. This restriction is specified in a condition whereby every generated trap checks this condition and it is validated. If necessary, it is sent to the Manager, else dropped.

 

To implement this feature, add the following piece of code in the Agent Main File for implementing the feature. Instead of instantiating SnmpTrapService, you have to instantiate the TrapValidator class (replace SnmpTrapService with TrapValidator) wherever it is present in the Main file that is generated, along with the correct constructor that you are using in this class.

 

class TrapValidator extends SnmpTrapService{

/**

* The Constructor with TrapSessionPort from where the

* Traps will be sent from the Agent.

*/

public TrapValidator(int port){

super(port);

}

/**

* The method to Validate the Traps. This will get called before the sendTrap method.

* Sends the Traps to the Managers in the TFTable. You have to Instrument the

* validating conditions in this method fulfilling your requirement.

* @param pdu The Trap SnmpPDU.

* @param managerNode The ManagerHost for which the Trap is targeted.

* @param managerPort The ManagerPort for which the Trap is targeted.

* @returns true if the Trap is Valid and false if the Trap is Invalid.

*/

// Sample Condition

// This will restrict any Trap from the Agent, if the TargetPort is 8004 // and Host is localhost.

public boolean validateTrap(com.adventnet.snmp.snmp2.SnmpPDU pdu, String managerHost, int managerPort){

if (managerPort == 8004 && managerHost.equals("127.0.0.1")){

return false;

}

else {

return true;

}

}

}

 

12.8 Implementing Your Own Table for Storing the Manager Information

 

You can also define your own Trap Forwarding Table instead of using the default Trap Forwarding TABLE in AGENT-SNMP-CONFIG-MIB. To achieve this purpose: -

 

trapListener.setForwardingEntryOID(".1.3.6.1.4.1.2345.10.3.1.2.2.1.1");

trapListener.addRegistrationListener(hdlr);

12.9 Implementing Informs

 

SNMP Notifications can be sent as Traps or Inform requests. Traps are unreliable because the Manager does not send any acknowledgment on receiving the Trap. So, the Agent cannot determine if the Trap was received by the Manager. However, an SNMP Manager that receives an Inform request acknowledges the message with an SNMP response PDU. If the Manager does not receive an inform request, it does not send a response. If the Agent does not receive a response at all, the inform request can be sent again.

 

12.9.1 Implementing Informs

 

Informs can be implemented by adding the following piece of code in the generated Main file before the code for restartSnmpAgent

    trapListener.setInformFlag(true);

Save the file and compile the code. This would send all the Trap messages to the Manager in the form of Informs and wait for an acknowledgment message. To know more on testing, please refer to Testing Informs topic.

 

12.9.2 Testing Informs

 

To test the same,

12.10 Sending Traps for Log4j Log Messages

 

Agent Toolkit has a facility for sending Traps for the Log4j Log Messages using SNMPTrapAppender utility. To enable SNMPTrapAppender utility, a new class extending SNMPTrapAppender class of SNMPTrapAppender utility is bundled with the product. Using this class, there are two ways by which Traps can be sent for the Log4j log messages. They are :

12.10.1 Using the Agent's own SnmpTrapService.

 

In this approach, the existing SnmpTrapService (i.e. in WebNMS's Agent) is used to send the Log messages as Traps. Here the Traps are forwarded to all the Managers present in the Trap Forwarding Table which is associated with the Agent's SnmpTrapService. The Trap PDU is filled with the details of the Entries in the Forwarding Table.

 

The following are the steps that illustrates the method:

The log messages that are at the higher level of the threshold being set will be converted to trap. Here the default threshold level is WARN and all the log messages higher to this level will be sent as trap by using this utility.

 

12.10.2 Using the XML file Configuration

 

In this approach, the SNMPTrapAppender is configured with the details read from a XML file. Here the Log Message Traps are forwarded to a Single Manager specified in the XML file. A sample appender configuration file, SnmpTrapAppenderTestConfig.xml is bundled with the product under <Agent Toolkit Home>/conf/appenderConfig/ directory.

 

The following are the steps that illustrates the method:

    // The logger to log the messages

        private org.apache.log4j.Logger logger = org.apache.log4j.Logger.getLogger(getClass().getName());

        // boolean to specify whether the log4j has been initilized

        private boolean log4jInitialized = false;

    /**

     * Method to initialize the SnmpTrapAppender based on a XML config file.

     */

    public void initAppenderWithConfigFile(){

            String confFile = "conf/SnmpTrapAppenderTestConfig.xml";

    if (!log4jInitialized) {

    try {

    org.apache.log4j.xml.DOMConfigurator.configure(confFile);

    log4jInitialized = true;

    } catch (Exception ex) {

    org.apache.log4j.helpers.LogLog.error("Error initializing logging!", ex);

    }

    }

            if (!log4jInitialized)

                org.apache.log4j.helpers.LogLog.error("Logging initialization error.");

            else {

    logger.debug("This is a Debug Message");

    logger.error("An Error occured here");

    logger.info("Here's some info about that");

    logger.fatal("Help! I'm dying out here!");

    logger.fatal("Here's an Exception!", new Exception("Exception message"));

    }

The log messages that are above the threshold level will be converted to trap. Here by default, the threshold level is DEBUG and all the log messages above this level will be sent as traps.

 

Thus the utility can be used according to the environment chosen.

 

12.10.3 Testing the Agent

 

For simple testing with WebNMS Agent Toolkit,

Thus Traps can be sent for any kind of log messages.

 

12.11 Running the Example

 

To know more about Traps, please go through the example available in <Agent Toolkit Home>/examples/snmp/traps directory. The "simpletrap" example sends a Trap to the Agent on every SET request. The main file TrapExample.java forwards the trap to the Manager specified in it. The readme.html will help you understand how to run this example.

 

 

Copyright © 2013, ZOHO Corp. All Rights Reserved.