The <snmp-device-variables-ondemand> Section

Many devices store information in SNMP tables. InterMapper can retrieve this tabular information and display the data "on demand", that is, when requested by user action. When you view a table, InterMapper retrieves the information from the device immediately and displays it in a separate window. The information in an on-demand window is not part of the regular polling cycle, nor is it refreshed until you specifically request it. The image below shows a sample on-demand window.

On-demand tables are useful for digging down into a device when you suspect there might be a problem. You can create on-demand tables to view a routing table, ARP table, or other statistics that that are kept within tables.

Background on SNMP Tables

The SNMP protocol provides access to two types of variables:

Scalar variables contain single values such as strings (that could represent system description or firmware version), integers (number of interfaces), counters (number of errors), gauges (CPU temperature and memory utilization), etc.
Table variables hold information about similar entities within a device. These entities could be interfaces in a router or switch, users associated with a wireless access point, virtual machines in a server, etc. Each entity's information is represented by a row, whose columns are variables (which are themselves scalars) that hold information about the entity. A row is often called an "entry" in a MIB; each column is specified by an OID prefix plus a unique index that specifies a particular row.

For example, MIB-II defines a table named "ifTable" that gives information about a device's interfaces. An outline of ifTable looks like this:

+ ifTable
  + ifEntry [ifIndex]
    - ifIndex       "Interface Index"
    - ifDescr       "Description"
    - ifType        "Link type"
    - ifSpeed       "Link speed"
    - ifPhysAddress "MAC Address"
    - ifOperStatus  "Operational status"
    - ifAdminStatus "Administrative status"
    -  ... and so on...

Here's how to interpret this information. The ifTable is composed of a sequence of ifEntrys which form the rows of the table. Each row (each ifEntry) has a number of variables: we show only some of them, starting with ifIndex and ending with ifAdminStatus. These variables become the columns of each row.

The image above shows the window of an on-demand table for ifTable. The columns match the variables mentioned above. The window also shows the number of rows in the table (at lower left), the time the data was retrieved, and the Refresh button to retrieve current data.

Table Indexes

Each row of an SNMP table has a unique index. The index for ifTable is the "interface index", that loosely represents the port number of the interface. Individual values are represented by the column name followed by its index. For example:

 ifSpeed.3 (or the OID 1.3.6.1.2.1.2.2.1.3)

would represent the ifSpeed for row 3 of the table. The "column name" is ifSpeed (1.3.6.1.2.1.2.2.1), and the index is the ".3".

Table Syntax

An on-demand table in a custom SNMP probe mirrors the outline above. Its definition consists of a sequence of lines of comma-separated values defining the variables of one or more tables:

<snmp-device-variables-ondemand>
  ifTable,               .1,                  TABLE,       "Information about the physical interfaces"
  ifTable/ifIndex,       1.3.6.1.2.1.2.2.1.1, DEFAULT,     "Interface Index"  <!-- using OID for column -->
  ifTable/ifDescr,       1.3.6.1.2.1.2.2.1.2, DEFAULT,     "Description"     <!-- using OID for column -->
  ifTable/ifType,        1.3.6.1.2.1.2.2.1.3, STRING,      "Link Type  "     <!-- using OID for column -->
  ifTable/ifSpeed,       1.3.6.1.2.1.2.2.1.5, DEFAULT,     "Link Speed"      <!-- using OID for column -->
  ifTable/ifPhysAddress, ifPhysAddress,       HEXADECIMAL, "MAC Address"     <!-- using column name from MIB -->
  ifTable/ifOperStatus,  ifOperStatus,        STRING,      "Opn'l"           <!-- using column name from MIB -->
  ifTable/ifAdminStatus, ifAdminStatus,       DEFAULT,     "Admin"           <!-- using column name from MIB -->
</snmp-device-variables-ondemand>

This example shows an on-demand table for ifTable.

Note: The <snmp-device-variables-ondemand> section must contain fewer than 50 queries.

The remainder of the table is composed of comma-separated lines describing each variable.

The first line creates a table. The first field is the table's name that can be used to represent the table elsewhere in the probe file. The second field should be ".1". The third field ("TABLE") indicates that this is a new table. The fourth field is a human-readable description that is displayed in the on-demand window.
The remaining lines follow the format of <snmp-device-variables>. See their page for more information. The names in the first column contain the table name, a "/", and the name for the column.
The next four lines define variables (ifIndex, ifDescr, ifType and ifSpeed) that are to be columns of the table. They are defined using the numeric OID that represents the column for those values.
The final three lines define ifPhysAddress, ifOperStatus, and ifAdminStatus. They are defined using the name of the column from the MIB. This is entirely equivalent to writing out the full numeric OID.

The tables described here are available as the SNMP/Table Viewerprobe that's built into InterMapper. In addition, the probe file is available on the Table Viewer page of this manual.

Augmenting Tables

Certain MIB's define a table that "augments" another table. This simply means that the augmenting table uses the same index variables as another table. Since the index variables are the same, you can visualize this as adding columns to an existing table.

For example, in the IF-MIB, the ifXTable augments ifTable, providing a number of useful additions.

InterMapper's table syntax easily supports mixing columns from one or more tables that share the same table definition:

<snmp-device-variables-ondemand>
  ifXTable,               .1,                    TABLE,       "Extended ifTable"
  ifXTable/ifIndex,       IF-MIB::ifIndex,       DEFAULT,     "Interface index" 
  ifXTable/ifDescr,       IF-MIB::ifDescr,       DEFAULT,     "Description"
  ifXTable/ifName,        IF-MIB::ifName,        DEFAULT,     "Name"   <!-- ifXTable -->
  ifXTable/ifAlias,       IF-MIB::ifAlias,       DEFAULT,     "Alias"  <!-- ifXTable -->
  ifXTable/ifType,        IF-MIB::ifType,        STRING,      "Link Type  "
  ifXTable/ifSpeed,       IF-MIB::ifSpeed,       DEFAULT,     "Link Speed"
  ifXTable/ifHighSpeed,   IF-MIB::ifHighSpeed,   DEFAULT,     "Mbit/sec"
  ifXTable/ifPhysAddress, IF-MIB::ifPhysAddress, HEXADECIMAL, "MAC Address "
  ifXTable/ifOperStatus,  IF-MIB::ifOperStatus,  STRING,      "Opn'l"
  ifXTable/ifAdminStatus, IF-MIB::ifAdminStatus, DEFAULT,     "Admin"
</snmp-device-variables-ondemand>

In the example, ifName and ifAlias come from the ifXTable while the others are part of ifTable. Yet they all can be shown in the same on-demand window.

Derived Variables

Certain SNMP equipment uses the value of one of more columns as part of the row index. In many cases, the column itself is not accessible, and thus cannot be queried directly.

InterMapper has a facility that allows you to derive the values of these columns from the index itself, even from columns that are not accessible. The notation oid[a:b] means to fetch the OID oid and compute the value from the index:

[a:b] - start with the a'th subid and collect b subids.
[a:]  - start with the a'th subid and collect the remaining subids

Here is an example of retrieving the four columns of ipNetToMediaTable. Note that the table has been given the name "ARPTable", although the OID is ipNetToMediaEntry.

<snmp-device-variables-ondemand>
   ARPTable,                         .1,                      TABLE,      "Map from IP addresses to physical addresses."
   ARPTable/ipNetToMediaIfIndex,     ipNetToMediaType[0:1],   DEFAULT,    "Interface index"
   ARPTable/ipNetToMediaNetAddress,  ipNetToMediaType[1:4],   DEFAULT,    "IP Address"
   ARPTable/ipNetToMediaPhysAddress, ipNetToMediaPhysAddress, HEXADECIMAL,"MAC Address"
   ARPTable/ipNetToMediaType,        ipNetToMediaType,        STRING,     "Type"
</snmp-device-variables-ondemand>

When InterMapper displays table, it will retrieve only two columns: ipNetToMediaPhysAddress and ipNetToMediaType. It then uses the OID of ipNetToMediaPhysAddress to derive the values of ipNetToMediaIfIndex and ipNetToMediaNetAddress.

Here's how this works. The ipNetToMediaTable is defined to use two index values:

ipNetToMediaIndex (the row number of the interface)
ipNetToMediaNetAddress (the IP address of the device)

This means that the full OID used to retrieve an item from the table is its prefix followed by the ipNetToMediaIndex followed by ipNetToMediaNetAddress.

The notation ipNetToMediaType[0:1] returns the single value that immediately follows the OID of ipNetToMediaType (this is in fact the index); ipNetToMediaType[1:4] returns the following four values, which comprise the IP address used in the index.

Calculations within On-demand Tables

InterMapper 5.3 introduces the ability to have calculations in on-demand tables. This is useful for making calculations from values within the same row of the table. The calculations may also use constant values as well as parameters to the probe. In the example below:

1) declares the column "ifIndex"
2) calculates the value of (column "ifIndex" plus 1) times 2
3) uses the previous column to get the original ifIndex back
4) and 5) display the current value of ifInOctets and ifOutOctets
6) the calculated ratio between these two columns
7) and 8) show a circular reference which fails gracefully - Circular1 and Circular2 refer to each other and simply display "-" as a value.

<snmp-device-variables-ondemand>
  ifTableTest,                    .1,                         TABLE
  ifTableTest/ifIndex,            IF-MIB::ifIndex,            DEFAULT      <!-- #1 -->
  ifTableTest/ifIndexPlus1Times2, ($ifIndex + 1)*2,           CALCULATION  <!-- #2 -->
  ifTableTest/ifIndexBack,        $ifIndexPlus1Times2/2-1,    CALCULATION  <!-- #3 -->
  ifTableTest/TInOctets,          IF-MIB::ifInOctets,         DEFAULT      <!-- #4 -->
  ifTableTest/TOutOctets,         IF-MIB::ifOutOctets,        DEFAULT      <!-- #5 -->
  ifTableTest/ifRatio,            $TInOctets/$TOutOctets,     CALCULATION  <!-- #6 -->
  ifTableTest/Circular1,          $Circular2 - 1,             CALCULATION  <!-- #7 -->
  ifTableTest/Circular2,          $Circular1 + 1,             CALCULATION  <!-- #8 -->
</snmp-device-variables-ondemand>

Displaying On-demand Tables

After you define a TABLE variable in the "ondemand" section of the probe, you can specify that status window should display a link to the ondemand window. To do this, add the variable name to the <snmp-device-display> section of the probe:

<snmp-device-display>
   ...
   $ARPTable
</snmp-device-display>

The status window displays the table name as a hyperlink. Clicking on the hyperlink opens the on-demand table window shown at the top of the page.

If you want to replace the default table name displayed with your own text, you can specify the "alternate text" in the expanded variable form:

<snmp-device-display>
   ...
   ${ARPTable:View the entire ARP Table}
</snmp-device-display>

Limitations

On-demand variables must be in table form with a "/" in the variable name.
You cannot query tables in the regular <snmp-device-variables> section.
You cannot reference on-demand tables defined in other probes.
You cannot specify non-accessible MIB variables by their symbolic OID. Instead, use the "derived values" syntax to determine the correct index-derived OID expression.
You must no more than 50 variables in the <snmp-device-variables-ondemand> section or the query will not work.