Introduction
InterMapper 4.5 introduces a new mechanism for displaying SNMP tables on demand. To use this feature, the proper definitions must be added to a Custom-SNMP probe file. The status windows of a device using that probe will have a clickable link that opens a window showing the specified table values.
When you view a table, InterMapper retrieves the information from the device immediately and displays it instantly. The information in an on-demand display is not part of the regular polling cycle, nor is it refreshed until you specifically request it.
On-demand displays are useful for digging down into a device when you suspect there might be a problem. You can use on-demand tables to view a routing table, ARP table, or other statistics that show an important status. The data is live, and the response is immediate.
Background
The SNMP protocol provides access to two types of variables, scalars and tables. Scalars are single values of a specific type: integer, string, counter, gauge, etc. Tables are composed of related arrays of scalars; you can visualize these related arrays as the columns. Each element in the array has a unique index that is the same for all the columns in the same table. All the elements in the table with the same index N represent row N of the table.
For example, the IP-MIB defines a table named "ipNetToMediaTable" that shows a device's ARP cache for its IPv4 interfaces. A schematic representation of ipNetToMediaTable might look like this:
+ ipNetToMediaTable
+ ipNetToMediaEntry [ipNetToMediaIfIndex,ipNetToMediaNetAddress]
- ipNetToMediaIfIndex "Interface"
- ipNetToMediaPhysAddress "MAC Address"
- ipNetToMediaNetAddress "IP Address"
- ipNetToMediaType "Type"
Here's how to interpret this information. Skipping over the second line for now, this "ipNetToMediaTable" has four variables, starting with ipNetToMediaIfIndex and ending with ipNetToMediaTable - these are the columns. The image in the introduction above shows the ipNetToMediaTable for a device with actual data. You'll notice that there are columns for each variable in the table. The quoted strings following the column names are human-readable labels to display instead of the formal names from the MIB.
Now that you understand the basic structure of ipNetToMediaTable and its four columns, you're probably wondering what is the role of the "ipNetToMediaEntry" line?
In SNMP, every value you retrieve has a unique ObjectID (OID). Tables are no different. With SNMP tables, the OID is formed by taking the column name and tacking on a row index that consists of one or more subid's. Every SNMP table can define its own mechanism for indexing the table, by combining values of its own columns.
In ipNetToMediaTable, the entry "ipNetToMediaEntry" indicates how this table indexes its rows. ipNetToMediaTable uses a set of subid's derived from the values of ipNetToMediaIfIndex and ipNetToMediaNetAddress. So the OID of a ipNetToMediaNetAddress is ipNetToMediaNetAddress.<ifIndex>.<ipNetToMediaNetAddress> or 1.3.6.1.2.1.4.22.1.3.<ifIndex>.<ipNetToMediaNetAddress>.
Tables Probe Syntax
With that background, the on-demand section of a custom SNMP probe mirrors the schematic representation above. It is delimited by <snmp-device-variables-ondemand> and </snmp-device-variables-ondemand> tags. Within these tags, there are a sequence of lines of comma-separated values defining one or more tables:
<snmp-device-variables-ondemand>
ipNetToMediaTable, 1.3.6.1.2.1.4.22.1, TABLE, "Maps from IP addresses to physical addresses."
ipNetToMediaTable/ipNetToMediaIfIndex, ipNetToMediaTable.1, DEFAULT, "Interface"
ipNetToMediaTable/ipNetToMediaPhysAddress, ipNetToMediaTable.2, HEXADECIMAL, "MAC Address"
ipNetToMediaTable/ipNetToMediaNetAddress, ipNetToMediaTable.3, DEFAULT, "IP Address"
ipNetToMediaTable/ipNetToMediaType, ipNetToMediaTable.4, STRING, "Type"
</snmp-device-variables-ondemand>
The first line defines a table "ipNetToMediaTable" using the new TABLE type. The second field "1.3.6.1.2.1.4.22.1" is an OID assignment for use in later definitions. The third field is the type "TABLE", and the fourth field is a human-readable description to display to the client of this table.
(Astute readers will notice that 1.3.6.1.2.1.4.22.1 is not the official OID of ipNetToMediaTable, but actually the OID of ipNetToMediaEntry. This is not a typo; in this first example, we're going to construct a definition of a table that doesn't require any MIB's to be loaded into InterMapper. In this example, ipNetToMediaTable is being used as an internal variable name; we could just as well have called it UncleBob.)
The four columns of the ipNetToMediaTable are defined similar to the TABLE, but with scalar types. In addition, the column variable names all begin with "ipNetToMediaTable/..." to indicate the table to which they belong. The second field is the OID of the table column. The third field is the type for display. The fourth field is a human-readable column title (optional).
The OID's for the four columns are allowed to use the OID assigned to ipNetToMediaTable in the TABLE line as a convenient shortcut. As an alternative, the OID's could all be specified exhaustively:
<snmp-device-variables-ondemand>
ipNetToMediaTable, .1 , TABLE, "Maps from IP addresses to physical addresses."
ipNetToMediaTable/ipNetToMediaIfIndex, 1.3.6.1.2.1.4.22.1.1, DEFAULT, "Interface"
ipNetToMediaTable/ipNetToMediaPhysAddress, 1.3.6.1.2.1.4.22.1.2, HEXADECIMAL, "MAC Address"
ipNetToMediaTable/ipNetToMediaNetAddress, 1.3.6.1.2.1.4.22.1.3, DEFAULT, "IP Address"
ipNetToMediaTable/ipNetToMediaType, 1.3.6.1.2.1.4.22.1.4, STRING, "Type"
</snmp-device-variables-ondemand>
A valid OID is still expected for the TABLE line; we use .1 for an ignored value because the field expects valid OID syntax.
More Simple Examples
Now that InterMapper 4.5 has a MIB compiler, you can use symbolic OID's in any OID field. Here's an example of the ipNetToMediaTable defined using the definitions in IP-MIB (and renamed UncleBob):
<snmp-device-variables-ondemand>
UncleBob, .1 , TABLE, "Maps from IP addresses to physical addresses."
UncleBob/IfIndex, IP-MIB::ipNetToMediaIfIndex, DEFAULT, "Interface"
UncleBob/PhysAddress, IP-MIB::ipNetToMediaPhysAddress, HEXADECIMAL, "MAC Address"
UncleBob/NetAddress, IP-MIB::ipNetToMediaNetAddress, DEFAULT, "IP Address"
UncleBob/Type, IP-MIB::ipNetToMediaType, STRING, "Type"
</snmp-device-variables-ondemand>
The on-demand table feature can also be used to query non-tables. Of course, non-tables are represented as tables with a single row:
<snmp-device-variables-ondemand>
sys, .1, TABLE, "System group"
sys/Description, sysDescr, DEFAULT
sys/Name, sysName, DEFAULT
sys/Contact, sysContact, DEFAULT
sys/OID, sysObjectID, DEFAULT
</snmp-device-variables-ondemand>
When a column variable doesn't specify a column title (in the fourth field), the column name, without the table prefix, is used instead.
It's important to note that table syntax differs slightly from the exact syntax required in the <snmp-device-variables> section. In the <snmp-device-variables> section, you would specify the .0 instance of sysDescr.0. With column variables, you never specify an index or instance.
A Complex Example
Since SNMP tables use the value of one of more columns in the row index, you can derive the values of these columns from the index itself. It's not necessary to explicitly query the column. In many cases, you can only derive the value of a column from the index; the column itself is not-accessible.
Here is an example of retrieving the four columns of ipNetToMediaTable using a two-variable query:
<snmp-device-variables-ondemand>
ipNetToMediaTable, 1.3.6.1.2.1.4.22.1, TABLE, "Maps from IP addresses to physical addresses."
ipNetToMediaTable/ipNetToMediaIfIndex, ipNetToMediaTable.4[0:1], DEFAULT, "Interface"
ipNetToMediaTable/ipNetToMediaPhysAddress, ipNetToMediaTable.2, HEXADECIMAL, "MAC Address"
ipNetToMediaTable/ipNetToMediaNetAddress, ipNetToMediaTable.4[1:4], DEFAULT, "IP Address"
ipNetToMediaTable/ipNetToMediaType, ipNetToMediaTable.4, STRING, "Type"
</snmp-device-variables-ondemand>
When InterMapper downloads this table from the table, it will retrieve only two columns: ipNetToMediaPhysAddress and ipNetToMediaType. From the index values of these two columns, the values of ipNetToMediaIfIndex and ipNetToMediaNetAddress can be derived.
In this example, the notation oid[a:b] means to fetch the OID oid and compute the value from the index:
[a:b] means start with the a'th subid and collect b subids.
[a:] means start with the a'th subid and collect the remaining subids
Augmenting Tables
You may run across MIB's that define a table that "augments" an existing 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 an augments definition as adding columns to an existing table.
In IF-MIB, an example of an augmenting table is ifXTable. ifXTable augments ifTable, providing a number of useful additions.
InterMapper's table syntax easily supports choosing columns from one or more tables that share the same index:
<snmp-device-variables-ondemand>
ifTable, .1, TABLE, "Partial ifTable & ifXTable"
ifTable/ifIndex, IF-MIB::ifIndex, DEFAULT
ifTable/ifDescr, IF-MIB::ifDescr, DEFAULT
ifTable/ifAlias, IF-MIB::ifAlias, DEFAULT
ifTable/ifName, IF-MIB::ifName, DEFAULT
</snmp-device-variables-ondemand>
Hyperlink Format
After you define a TABLE variable in the "ondemand" section of the probe, you can specify that variable in the <snmp-device-display> section as you would any other variable:
<snmp-device-display>
...
$ipNetToMediaTable
$sys
$UncleBob
</snmp-device-display>
When InterMapper renders the "display" section, it will display the table name as a hyperlink. People looking at the status window in InterMapper can click on the hyperlink to bring up the on-demand table window pictured in the introduction
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>
...
$\{ipNetToMediaTable:ARP Table}
</snmp-device-display>
Limitations
- You cannot use CALCULATION variables in a "ondemand" table. This is an implementation detail; CALCULATION types are not yet implemented.
- 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 and expect InterMapper to determine the correct index-derived OID expression.
|
