<snmp-device-variables-ondemand> Section

Many devices store information in SNMP tables. Intermapper can retrieve this tabular information and display the data on-demand, (when requested by a user). When you view a table, Intermapper immediately retrieves data from the device 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 following image shows a sample on-demand window:

On-demand tables are useful for investigating when you suspect there might be a problem with a device. You can create on-demand tables to view a routing table, ARP table, or other statistics that are stored in tables.

Background on SNMP Tables

The SNMP protocol provides access to the following variable types:

Scalar variables - contain single values such as strings (that can represent system description or a firmware version), integers (number of interfaces), counters (number of errors), gauges (CPU temperature and memory utilization), and so on.
Table variables - contain information about similar entities within a device. These entities can be interfaces to a router or switch, users associated with a wireless access point, virtual machines on a server, and so on. Each entity's information is represented by a row and the columns are variables (which are themselves scalars) that contain 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 provides information about a device's interfaces. An outline of ifTable is as follows:

+ 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...

The ifTable is composed of a sequence of ifEntrys that 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 above example 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 when data is retrieved, and the Refresh button to refresh the 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)

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

Table Syntax

An on-demand table in a custom SNMP probe mirrors the outline above. Its definition contains a sequence of lines of comma-separated values defining the variables of one or more tables. For example, the following is an on-demand ifTable:

<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>

NOTE:

The <snmp-device-variables-ondemand> section is limited to 50 queries.

The remainder of the table is composed of the following comma-separated lines that describe each variable:

The first line creates a table. The first field is the table name that can represent the table in the probe file. The second field should be called .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 <snmp-device-variables> format. See their respective page for more information. The first column contains the table name, a forward slash (/), and the name of the column.
The next four lines define variables (ifIndex, ifDescr, ifType, and ifSpeed) that define table columns. They are defined using the numeric OID that represents the column of those values.
The final three lines define ifPhysAddress, ifOperStatus, and ifAdminStatus. They are defined using the column name from the MIB. This is equivalent to the full numeric OID.

These tables are available as the SNMP/Table Viewer probe that is built into Intermapper. In addition, the probe file is available on the Table Viewer page of this manual.

Augmenting Tables

Certain MIBs define a table that augments another table. This means that the augmenting table uses the same index variables as another table. Since the index variables are the same, this similar to adding columns to an existing table.

For example, in the IF-MIB, the ifXTable augments the 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. For example,

<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. They all can be displayed in the same on-demand window.

Index-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 cannot be queried directly.

You can derive the values of these columns from the index itself, even from columns that are not accessible. The oid[a:b] notation fetches the OID oid and compute the value from the index. For example,

oid[a:b] - remove the subid's for "oid" then start with the a'th subid and collect b subids.
oid[a:]  - remove the subid's for "oid" then start with the a'th subid and collect the remaining subids

The following is an example of retrieving the four columns of ipNetToMediaTable. Note that the table is named ARPTable, although the OID is set to 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>

The ipNetToMediaTable uses the following index values:

ipNetToMediaIndex - the row number of the interface.
ipNetToMediaNetAddress - the IP address of the device.

The full OID used to retrieve a value from the table is its prefix (for example, ipNetToMediaType is 1.3.6.1.2.1.4.22.1.4, followed by a single subid for ipNetToMediaIndex followed by the four subids of ipNetToMediaNetAddress).

When Intermapper displays the table, it retrieves ipNetToMediaType, removes the prefix, starts at position 0 of the remainder and uses one subid for the ipNetToMediaIfIndex, and then starts at position 1 and takes the next four subids for the value of ipNetToMediaNetAddress.

Calculations Within On-Demand Tables

Intermapper provides the ability to use calculations in on-demand tables. This is useful for making calculations from values within the same row of the table. The calculations can 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) is 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 display a hyphen (-).

<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 on-demand section of the probe, you can specify that the status window displays a link to the on-demand window. To do this, add the variable name to the <snmp-device-display> section of the probe. For example,

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

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

To replace the default table name displayed with your own text, you can specify alternate text in the following expanded variable format:

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

Limitations

On-demand variables must be in table form with a forward slash (/) 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 declare no more than 50 variables in the <snmp-device-variables-ondemand> section or the query will not work.

Copyright © Fortra, LLC and its group of companies.
All trademarks and registered trademarks are the property of their respective owners.
6.6.3 | 202412230819 | January 2025