SNMP Scenario Scripting Guide

SNMP scenarios can be used to simplify the process of writing test cases to validate the basic behavior of SNMP enabled devices. SNMP scenarios are small text-based scripts that define interactions between CDRouter and the CPE device under test. Users may create SNMP scenarios to easily get, set and verify SNMP MIB objects on their device.

The scenario file you create will be executed by the snmp_scenarios.tcl test module, which can be added to your test package to run among all other tests.

To get started with SNMP scenarios, create an SNMP scenario script file on the local disk of your CDRouter system. The scenario script file may contain one or more “scenario” blocks denoted by the “SNMP” keyword. Each “scenario” contains one or more “commands” from the list below, which direct CDRouter to send SNMP requests to the DUT and interpret the response.

Once you have created your scenario script file, update the following testvars in your config file:

  • snmpScenarioPath - This must be set to the full path to the SNMP scenario script file you created. Multiple scenarios can be defined in this file, each with a unique name.

  • snmpScenarioInterface - CDRouter will send requests to the IPv4/IPv6 address of the DUT that corresponds to the interface named by this testvar. The values 'wan' and 'lan' correspond respectively to CDRouter’s primary WAN and LAN interfaces in the config file. Other interfaces defined in testvar_groups may be specified by name (eg. 'lan2', 'lan3', 'wan2', etc.).

    If CDRouter DOCSIS is also configured, the special value 'docsis' may be used to specify that CDRouter send SNMP requests to the Cable Modem of the DUT.

  • snmpScenarioIpVersion - This may be set to 'IPv4' or 'IPv6' to specify which address family should be used for SNMP requests. The DUT must have a reachable address on the interface specified by snmpScenarioInterface.

Scenario Script Format

Each SNMP scenario script file may contain one or more scenario blocks which are executed as a unit. Each scenario block is defined by the SNMP keyword and a unique name for the scenario block, followed by a list of commands to execute, all enclosed in curly braces (’{ }’).

SNMP example_scenario {

    <command> 
    <command> 
    <command> 
        :
        :
}

Each command is a keyword that may also have a number of arguments enclosed in curly braces. The table below lists all of the available commands that can be used in a scenario block:

Available Commands
GetRequest
GetNextRequest
SNMPWalk
SNMPTable
SetRequest
Delay
Log

Simple Example

Here is a simple SNMP scenario to request two OID values with a single GetRequest command. Each scenario must be given a unique name when it is defined. All MIB objects must be specified with their full numeric OID.

This SNMP scenario consists of one command. Some commands correspond directly to SNMP PDUs that can be sent, and may contain additional arguments to verify the response from the DUT

For example, the GetRequset command sends an SNMP GetRequest PDU to the DUT. The command contains a list of one or more oid arguments to specify which object OIDs to include in the PDU.

SNMP example_scenario {

  GetRequest {

    # get OID values from the mib-2 system and interfaces groups
    #   sysDescr.0 
    #   ifOperStatus.1
    oid .1.3.6.1.2.1.1.1.0
    oid .1.3.6.1.2.1.2.2.1.8.1
 
  }
}

The GetRequest command may also contain verify arguments to check whether the response from the DUT matches expected values. Here is another example:

SNMP example_scenario {

  GetRequest {

    # get OID values from the mib-2 system and interfaces groups
    #   sysDescr.0 
    #   ifOperStatus.1
    oid .1.3.6.1.2.1.1.1.0
    oid .1.3.6.1.2.1.2.2.1.8.1

    # verify the response
    verify .1.3.6.1.2.1.1.1.0       "OpenWrt"
    verify .1.3.6.1.2.1.2.2.1.8.1   "up(1)"
 
  }
}

Scenario Commands

SNMP Scenarios contain commands that map directly to executable commands in the Net-SNMP package bundled with CDRouter. For example, to set specific object values, use the SetRequest command and a valid OID instance. To read the values of objects, use the GetRequest, GetNextRequest, SNMPWalk, and SNMPTable commands.

When specifying OID’s in SNMP Scenario commands, they should be specified in numerical format (dotted-decimal) rather than symbolic names. When verifying the DUT’s response, value should exactly match the format presented by the Net-SNMP tools.

GetRequest, GetNextRequest, and SNMPWalk Commands

The GetRequest command may specify one or more full OID instances with the oid argument. The OID specified must match an object instance that exists on the DUT in order for the request to be successful.

The GetNextRequest command may specify one or more OIDs, which may or may not map to real objects defined in the MIB. The DUT will return the OID instance that comes immediately after the OID contained in the oid argument.

The SNMPWalk command may specify a single OID only, which may or may not map to a real object defined in the MIB. The result of an SNMPWalk command will be all of the OID instances that come immediately after the OID contained in the oid argument and also share the same OID prefix. The result of an SNMPWalk ends when the DUT returns an OID instance whose prefix does not match the oid argument or the end of the MIB database is reached.

GetNextRequest {

    # get next OID after mib-2 "system" group
    oid .1.3.6.1.2.1.1

}

“verify” argument

The optional verify argument can be used to verify the value of any OID instance returned by the DUT in a GetRequest, GetNextRequest, or SNMPWalk command. Multiple verify arguments can be specified to verify the values of different OIDs contained in the same response from the DUT.

Each verify argument takes the following form:

verify <oid> <value>

  • By default, verify will check to ensure that the value of the specified object exactly matches <value>. Values containing spaces or special characters should be placed in curly braces ({<value>}).

    GetRequest {
    ## ifOperStatus
    oid    .1.3.6.1.2.1.2.2.1.8.1
    verify .1.3.6.1.2.1.2.2.1.8.1 "up(1)"
}

  • [ any ]

    The any keyword ensures the object exists without regard for its value. This is useful for objects such as packet counters which may be constantly changing. Empty (null) values are also acceptable.

    verify .1.3.6.1.2.1.2.2.1.8.1 [ any ]

  • [ accept … ]

    The verify argument can also be configured to accept a list of values using the syntax [ accept value1 value2 ... ] . The value returned by the GetRequest, GetNextRequest, or SNMPWalk call will then be compared to the list of acceptable values.

    verify .1.3.6.1.2.1.2.2.1.8.1 [ accept "up(1)" "down(2)" ]

  • [ expr … ]

    The expr keyword can be used to compare whether numerical OID instance values are less than, greater than, or equal to a specific value. The special keyword 'VALUE' is used to represent the OID value returned by the DUT.

    verify .1.3.6.1.2.1.2.2.1.10.1 [ expr {VALUE > 0} ]

  • [ regexp … ]

    The verify argument can compare the value returned by the GetRequest, GetNextRequest, or SNMPWalk GetRequest call against a TCL regular expression if the exact value is not known. Any valid TCL regular expression string may be used and should be enclosed in curly braces (’{}’).

    # ifInOctets.1
verify .1.3.6.1.2.1.2.2.1.10.1 [ regexp {[0-9]+} ]

SNMPTable Command

The SNMPTable command requests all of the OID instances contained within a specific table of the MIB and displays them in a formatted table.

The oid argument must specify a single object OID corresponding to a MIB “table” definition, such as IF-MIB::ifTable.

SNMPTable {

    oid .1.3.6.1.2.1.2.2

}

“verify” argument

The verify argument is similar to its counterpart described above with the following exceptions:

  • Due to the way the Net-SNMP snmptable command presents its output, the verify argument must only specify the object name without any leading path or instance (eg. “ifInOctets”). This identifies the “column” of the table being verified.

  • The verify argument verifies every instance (row) of the named OID that the DUT returns, and it will print a separate PASS or FAIL message instance.

    SNMPTable {
    ## IF-MIB::ifTable
    oid    .1.3.6.1.2.1.2.2
    verify ifInOctets [ expr {VALUE > 0} ]
}

“contains” argument

The contains argument is only available with the SNMPTable command. It is identical to verify, but it only produces a single PASS or FAIL message to represent all instances returned by the DUT. If all instances of the OID meet the criteria of the verify argument, then a PASS message is printed. Otherwise, if any instance does not meet the verify criteria, a FAIL message is printed.

SNMPTable {
    ## IF-MIB::ifTable
    oid    .1.3.6.1.2.1.2.2
    contains ifInOctets [ expr {VALUE > 0} ]
}

SetRequest command

The SetRequest command is used to modify the value of a MIB object. The command must specify a full object OID instance using the oid argument, along with a value and type specification.

SetRequest {
    # sysName.0
    oid .1.3.6.1.2.1.1.5.0 {QA Cafe} STRING 
}

The following types can be specified:

- INTEGER         (eg. `{-2147483648}` )
- UNSIGNED        (eg. `{4294967295}` )
- STRING          (eg. `{QA Cafe}` )
- HEX_STRING      (eg. `{51 41 20 43 61 66 65}` )
- DECIMAL_STRING  (eg. `{81 65 32 67 97 102 101}` )
- OBJID           (eg. `{.1.3.6.1.2.1.1.1.0}` )
- TIMETICKS       (eg. `{14713580}` )
- IPADDRESS       (eg. `{192.168.1.1}` )
- BITS            (eg. `{0 4 7 8}` )
- FLOAT           (eg. `{-3.141592}` )
- DOUBLE          (eg. `{-3.141592653589793}` )
- INT64           (eg. `{-9223372036854775808}` )
- UINT64          (eg. `{18446744073709551615}` )

Delay Command

The Delay command can be used to insert an arbitrary delay, in milliseconds, anywhere within the scenario file. This can be useful for investigating timing issues between successive RPCs.

SNMP Delay_example {
   # Pause for 60 seconds
   Delay 60000
}

Log command

The Log command can be used to insert a user defined message into the log file. This command can be used anywhere within a scenario file.

SNMP log_example {
   Log "Here is a GetRequest for sysDescr.0"
}

Run a single scenario from the SNMP scenario file

Rather than running all SNMP scenarios defined in the scenario file all at once, it is possible to run the scenarios one at a time by setting the following testvar:

testvar snmpScenarioSingleMode   yes

If set to yes, then only a single SNMP scenario will be run for each iteration of the snmp_scenario_1 test. If the CDRouter test package is defined such that the snmp_scenario_1 test is repeated or looped, then each iteration of the snmp_scenario_1 test will run a subsequent scenario.