Including TrapdLamv1 includes in TrapdLamv2

Notice

See Installing SNMP Trapd v2 for installation instructions for SNMP Trapd v2.

Include files created using the TrapLamV1 mib2lam process are fully compatible with the TrapLamv2, but the routing used for non-GA includes will need to be transferred to the new master.includes format.

There are two types of routing used in the TrapLamV1:

1. Enterprise routing

This is the simplest for of direct routing and is used where there is a single include file covering the entire MIB set for a vendor.

These routes will look like this in the MoogTrapdLam.js (where “vendor” is typically an enterprise name).

LamBot.loadModule("trapModules/vendor/VendorTraps.include");
var vendor = new VendorTraps(botUtil);
...
 switch ( trapInfo.enterprise.toLowerCase() ) {

    // ENTERPRISE ROUTING
    // Vendor specific routing

    case "vendor" : vendor.processTrap(moogEvent,trapData,trapInfo); break;
    ...
}

For example, for Veritas this is:

LamBot.loadModule("trapModules/veritas/VeritasCCTraps.include");
var veritas = new VeritasCCTraps(botUtil);
...
 case "veritas" : veritas.processTrap(moogEvent,trapData,trapInfo); break;
...

Moving these routes to the master.includes requires creating a new route entry (if one does not already exist).

  1. Examine the include file and look for the “class” for the include. This is the first function statement at the very top of the file, just below the comments indicating the MIBs used and the creation. In this case, it would be “VeritasCCTraps”

    //---------------------------------------------------------------
    // VERITAS-COMMAND-CENTRAL-MIB
    //---------------------------------------------------------------
    
    //--------------------------------------------------------------------------
    // Module : VeritasCCTraps
    // Created on 2021-06-10T15:56:40.086Z
    //--------------------------------------------------------------------------
    
    
    function VeritasCCTraps(botUtil) {

    This is the same name as the --module parameter used in the mib2lam conversion process.

  2. 2. Construct the master.includes entry from the template:

    <Module> : { "route" : "<trap path>", "file" : "<path to include file>"} 

    Taking the Module from the include file, the route from the case statement and the include file path from the LamBot.loadModule statement.

    For the Veritas example above, this would result in a master.includes entry:

    "VeritasCCTraps" : { "route" : "veritas" , "file" : "trapModules/veritas/VeritasCCTraps.include" },

2. Sub-enterprise routing

If the mib2lam conversion process has been used below the enterprise level, for example for individual MIBs, then sub-enterprise routing will have been used. This uses both the simple “vendor” enterprise level and subsequent processing to determine a trap route.

For example, for EMC traps that cover a variety of MIBs the sub-enterprise routing is:

    case "emc"      :
      var emcModule;
      if ( trapData.snmptrapexpandedenterprise && Array.isArray(trapData.snmptrapexpandedenterprise) &&
        trapData.snmptrapexpandedenterprise.length >= 2 ) {

          emcModule=trapData.snmptrapexpandedenterprise[1];
      }
      switch ( emcModule.toLowerCase() ) {
        case "vplex"            : vplex.processTrap(moogEvent,trapData,trapInfo); break;
        case "eccgateway"       : eccgateway.processTrap(moogEvent,trapData,trapInfo);break;
        case "xtremio"      : xtremio.processTrap(moogEvent,trapData,trapInfo);break;
        case "ecs"        : emcecs.processTrap(moogEvent,trapData,trapInfo);break;
        case "emccelerra"   : emccelerra.processTrap(moogEvent,trapData,trapInfo);break;
        case "unity"      : emcunity.processTrap(moogEvent,trapData,trapInfo);break;
        default                 : unknownTraps.processTrap(moogEvent,trapData,trapInfo); break;
      }
    break;

A base route for the “emc” enterprise, and Individual sub-enterprise routes for VPlex, ECCGateway. XTremeIO etc. “leaves”. These sub-enterprise routes use the snmptrapExpandedEnterprise event attribute for the routing logic — extending the routing beyond the first OID octet.

Example of using snmpTrapExpandedEnterprise in MoogTrapLamV1

When a trap is received, the trapd_lam takes the trap identifier and expands this into a textual representation of the trap’s OID path.

For the three IPTrade include files used in the example above:

Taking a trap from each of the mibs...

# IPT-TURRET-MIB : eosLowMemory - v2c 
# 1.3.6.1.4.1.30191.1.7.0.1
# Data base free memory below a preconfigured threshold
snmptrap -v 2c -c public localhost '' 1.3.6.1.4.1.30191.1.7.0.1  \
                1.3.6.1.4.1.30191.1.7.2.1.5 i 1 \
                1.3.6.1.4.1.30191.1.7.2.1.3 i 1 \
                1.3.6.1.4.1.30191.1.7.2.1.2 i 1 \
                1.3.6.1.4.1.30191.1.7.2.1.4 i 1


# IPT-TPO-MIB : diskLowSpace - v2c 
# 1.3.6.1.4.1.30191.2.1.0.1
# Free space on disk below a preconfigured threshold
snmptrap -v 2c -c public localhost '' 1.3.6.1.4.1.30191.2.1.0.1  \
                1.3.6.1.4.1.30191.2.1.4 i 1


# IPT-TSS-VA-MIB : certificateWillExpire - v2c 
# 1.3.6.1.4.1.30191.3.1.0.8
# A certificate will expire in less than 30 days
snmptrap -v 2c -c public localhost '' 1.3.6.1.4.1.30191.3.1.0.8  \
                1.3.6.1.4.1.30191.3.1.20.1.3 i 1

...we’d end up with the following trap details:

  "snmpTrapObjectName": "eosLowMemory",
  "snmpTrapObjectId": "1.3.6.1.4.1.30191.1.7.0.1",
      "snmpTrapExpandedEnterprise": [
        "iptrade",
        "ipt-turret",
        "embeddedDB",
        "embeddedDBTraps",
        "eosLowMemory"
    ]
    "snmpTrapExpandedEnterprise": [
        "iptrade",
        "ipt-tpo",
        "sysinfo",
        "sysInfoTraps",
        "diskLowSpace"
    ],
    "snmpTrapObjectName": "diskLowSpace",
    "snmpTrapObjectId": "1.3.6.1.4.1.30191.2.1.0.1",
    "snmpTrapExpandedEnterprise": [
        "iptrade",
        "ipt-tss-va",
        "sysinfo",
        "sysInfoTraps",
        "certificateWillExpire"
    ],
    "snmpTrapObjectId": "1.3.6.1.4.1.30191.3.1.0.8",
    "snmpTrapObjectName": "certificateWillExpire",

Each trap has a different second element of the snmpTrapExpandedEnterprise, allowing sub-enterprise routing based on that value - “ipt-tss-va” or “ipt-tpo” or “ipt-turret”.

The resulting MoogTrapLamV1 code would look like this:

Firstly, switch on the “iptrade” enterprise and then switch based on the second element of the snmpTrapExpandedEnterprise, and call the associated include file’s processing layer:

LamBot.loadModule("trapModules/iptrade/IPTTPOTraps.include");
LamBot.loadModule("trapModules/iptrade/IPTTSSTraps.include");
LamBot.loadModule("trapModules/iptrade/IPTTurretTraps.include");
...
var iptturret = new IPTTurretTraps(botUtil);
var ipttss = new IPTTSSTraps(botUtil);
var ipttpo = new IPTTPOTraps(botUtil);
...

    case "iptrade" :

        var iptradeModule;
        if ( trapData.snmptrapexpandedenterprise && Array.isArray(trapData.snmptrapexpandedenterprise) &&
              trapData.snmptrapexpandedenterprise.length > 1 ) {

            iptradeModule = trapData.snmptrapexpandedenterprise[1];
        }
        switch(iptradeModule.toLowerCase() ) {
          case "ipt-tss-va" : ipttss.processTrap(moogEvent,trapData,trapInfo); break;
          case "ipt-tpo" : ipttpo.processTrap(moogEvent,trapData,trapInfo); break;
          case "ipt-turret" : iptturret.processTrap(moogEvent,trapData,trapInfo); break;
          default : unknownTraps.processTrap(moogEvent,trapData,trapInfo); break;
        }

    break;
  

2a. Converting sub-enterprise routing code to a master.include route

From the above code we can create three new entries for the master.includes, one for each possible value.

"IPTTurretTraps" : { "route" : "iptrade.ipt-turret" , "file" : "trapModules/iptrade/IPTTurretTraps.include" },
"IPTTPOTraps" : { "route" : "iptrade.ipt-tpo" , "file" : "trapModules/iptrade/IPTTPOTraps.include" },
"IPTTSSTraps" : { "route" : "iptrade.ipt-tss-va" , "file" : "trapModules/iptrade/IPTTSSTraps.include" },

Taking the Module name, the route (enterprise and snmpTrapExpandedEnterprise components) and the file name.

2b. Routing notation

The routing notation allows routing elements to be missing, so if the sub-enterprise routing is using a deeply nested item, then you do not need to detail every item. For example, if the full route for an include were...

"QlogicTraps" : { "route" : "qlogic.enet.qlasp.qlasptrap" , "file" : "trapModules/qlogic/QlogicTraps.include" },

...this route can be shortened to:

"QlogicTraps" : { "route" : "qlogic.qlasptrap" , "file" : "trapModules/qlogic/QlogicTraps.include" },

The intervening items (enet.qlasp) between the first and last switched item can be removed — simplifying the conversion of a TrapLamV1 code based route where the intermediate snmpExpandedEnterprise items may not have been listed or are not part of the routing logic. Any existing sub-enterprise routing will always have the first and the next switching item listed.

If there is any doubt about the route conversion, then you can rerun the mib2lam process with the newer mib2lam tooling, using the same starting point as the original include file. This will provide the new master.includes routing entry. There is no need to use the resulting include file itself, i.e. keep the exiting file, and just use the new routing data.

mib2lam

The mib2lam conversion utility has been modified to produce routing details suitable for the master.includes. For example, the following shows the changes in the output for the same conversion using the TrapdLamV1 mib2lam and the TrapdLamV2 process. Notice the difference in the instructions for adding the new include file to the trap lam processing.

V1 mib2lam - using lambot modifications

---------------------------- Deployment Instructions ----------------------------

 To deploy this module for the trapd_lam, perform the following actions:

 1. Put the module in the standard trap module location:

    - The traps in this module come from a single enterprise: qlogic, so can be put under a vendor directory
    - Create the following directotry $MOOGSOFT_HOME/bots/lambots/trapModules/qlogic
    - Copy the module file (/usr/share/moogsoft/custom/mib2lam/bin/../tmp/QLogicTraps.include to this directory as QLogicTraps.include

 2. Add the module to the trapd_lam lambot

    - At the top of the lambot (MoogTrapdLam.js) in the global section add the following:

      LamBot.loadModule("trapModules/qlogic/QLogicTraps.include");
      var qlogic = new QLogicTraps(botUtil);

     - Alternatively 
    
       - Add the following to the "modules" : [ ... ] section of the moog_trapd_lam.conf

         "trapModules/qlogic/QLogicTraps.include"

           - and add the following to the top of the lambot.

         var qlogic = new QLogicTraps(botUtil);
        


 3. Add routing to allow traps from the enterprise to be sent to this module. 

    - Generally this will be routed on the enterprise 'qlogic'
    - For an enterprise route, add the following to the routing section (switch/case statment) of the lambot.

      case "qlogic" : qlogic.processTrap(moogEvent,trapData,trapInfo);break;

    - If this is an sub-enterprise module - for example a single converted mib within a wider set:  
       - Either combine this with a top level module transferring enumerations, severitiies, related traps, 
         and trap functions 
        OR
       - Use a routing path path further down the snmptrpaExpandedEnterprise path.
       - For a sub-enterprise route all the traps in this module will support routing along the following 
         expanded enterprise path:

         [ qlogic,enet,qlasp,qlasptrap ]


--------------------------------------------------------------------------------

V2 mib2lam - using new master.includes

---------------------------- Deployment Instructions ----------------------------

 To deploy this module for the trapd_lam, perform the following actions:

 1. Put the module in the standard trap module location:

    - The traps in this module come from a single enterprise: qlogic, so can be put under a vendor directory
    - Create the following directotry $MOOGSOFT_HOME/bots/lambots/trapModules/qlogic
    - Copy the module file (/usr/share/moogsoft/custom/trapdlam/mib2lam/bin/../tmp/QLogicTraps.include to this directory as QLogicTraps.include


 2. Add the module to the included modules:

    - Add the module to the included modules, copy this line into the master.includes file ($MOOGSOFT_HOME/bots/lambots/trapModules/master.includes):
    - All the traps in this module will support routing along the following expanded enterprise path:
    - Check for errors on lam startup to ensure that there are no routing conflicts with existing modules. 

    "QLogicTraps" : { "route" : "qlogic.enet.qlasp.qlasptrap" , "file" : "trapModules/qlogic/QLogicTraps.include" }

--------------------------------------------------------------------------------