The <snmp-device-variables> Section

InterMapper can retrieve MIB variables from a device and then test them against thresholds. The <snmp-device-variables>section defines the OIDs of MIB variables that are to be retrieved. These values are called probe variables and can then be compared to thresholds to create alarms, warnings, etc.

Each line of the <snmp-device-variables> section defines a particular variable to be retrieved. The definition is composed of four comma-separated attributes:

[VariableName], [OID], [Type], [Chart Legend (optional)]

The definitions of these attributes are:

• VariableName is the name used to represent the particular MIB value in this probe. A VariableName consists of letters, digits and an underscore, and must begin with a letter. VariableNames are not case-sensitive. These variable names will be represented in the probe as $VariableName. It is not necessary that a particular VariableName match the corresponding name in the MIB, although that is definitely convenient.
  
  Note: Versions of InterMapper prior to 4.2 required that variable names be enclosed in curly braces, e.g., ${VariableName}. This not necessary in version 4.2 and later, and both forms are now identical. If, however, you want to use a variable name that contains spaces, you must enclose the variable in curly brackets.
• OID is the Object ID for the particular probe variable. The OID can be expressed as a string of dotted numbers or as an OID name, if the corresponding MIB has been imported into InterMapper. An OID can also be an expression, if the type is "CALCULATION" (see note below).
  
  Notes:
  • Calculation variables have a slightly different form, as described below.
  • See Probe Calculations for a description of the functions and operators that are available in expressions. A scalar's OID must end in ".0" according to the SNMP specifications. See SNMP OIDs for a description of allowable formats for OIDs
  • See On-Demand SNMP Tables for a description of how your probe can display tabular information from a MIB.
  • When InterMapper retrieves a value, by default it issues an SNMP Get-Next-Request for the previous OID, unless the pdutype is set to "get-request" (see Probe Properties
    
• Type - may be one of the following:
  • Default - InterMapper deduces an applicable type from the SNMP type of the variable and displays it according to the "Format for DEFAULT types" table below.
  • Integer - values are coerced to a numeric value. If you have a string value returned "78Fred", the value as INTEGER will be 78.
  • Integer64 - values are coerced to a numeric value (up to 64-bits). If you have a string value returned "78Fred", the value as INTEGER will be 78.
  • Hexadecimal* - If the value is a number, it is displayed as a hex number, preceded by "0x" (0xFFFFFFFF). Otherwise, it is represented as a series of hex characters separated by spaces (44 61 72 77 69 6E 20 52 69 63 68 61 72).
  • Hexnumber - converts a string of hexadecimal digits into a number. For example, a string value of "FE" would be converted to the number 254.
  • Double - converts a string to the corresponding floating point number. Thus a string of "5.678" will be represented internally as a floating point number between 5 and 6, and displayed
  • Total-value - displays the actual value of a counter or gauge, not a computed rate value. This will always be an unsigned number.
  • Total64-value - displays the actual value of a counter or gauge, not a computed rate value. This will always be an unsigned number (up to 64-bits).
  • Per-second and Per-minute - force InterMapper to compute a rate for the particular variable by computing the difference between two successive samples and dividing by the elapsed time.
  • String* - sets a variable to the text string that corresponds to this OID's enumerated type, as defined in the MIB. (see below)
  • Calculation - sets the variable to the result of the calculation shown in the OID field.
  • TrapVariable - sets a variable based on the value received from an SNMP trap. A complete discussion of Trap Variables is available in About Custom SNMP Trap Probes
  • IPADDRESS - InterMapper displays a 4-byte octet string as an IPv4 address and a 16-byte octet string as an IPv6 address.
    * STRING and HEXADECIMAL are both strings; they can't be charted.
    
    Format for DEFAULT types:
    

    If the variable is of type...	InterMapper will display it as:
    Counter32, Counter64	=> Per-Second
    Unsigned32 (Gauge)	=> Total-Value
    Integer	=> Integer
    OctetString	=> String (if first digit printable) or Hexadecimal (if not)
    Object ID	=> String
    IPAddress	=> String
    TimeTicks	=> String

    
    
• Chart-legend is an optional field that provides a text label to be placed on any strip charts that incorporate this variable. Chart legends may contain embedded variable names in the form $VariableName.

Here is a sample <snmp-device-variables> section.

<snmp-device-variables>
   --Variable-name  OID --- TYPE ---- CHART LEGEND ------
   ipForwDatagrams, 1.3.6.1.2.1.4.6.0, PER-SECOND, "Forwarded datagrams"
   ipInHdrErrors,   1.3.6.1.2.1.4.4.0, PER-MINUTE, "IP received header err"
   tcpCurrEstab,    1.3.6.1.2.1.6.9.0, DEFAULT, "Number of TCP conn's"
   sysDescr,        1.3.6.1.2.1.1.1.0, DEFAULT
   -- Non-polled values:-- Calculation variables are computed each poll time
   SineValue, (10*sin(0.01*time())), CALCULATION, "10 * sin(0.01 * time())"
</snmp-device-variables>

Note:The OIDs above have a trailing ".0" to specify their full OID.

Calculation Variables

A Calculation type variable receives the result of an arithmetic expression. After all variables have been polled, InterMapper calculates the expression, and sets the value of its variable to the result. In the example above:

SineValue, (10*sin(0.01*time())), CALCULATION, "10 * sin(0.01 * time())"

The variable "SineValue" will be set to the value of the expression (10 * sin(0.01 * time()). This gives a sine wave that makes an attractive chartable value. Use "$SineValue" to refer to the variable elsewhere in the probe.

Built-in Variables

InterMapper provides a number of built-in variables, They are detailed in the Built-in Variable Reference topic. Three macros are described below.

Macros

InterMapper supports several macros that show information about a variable:

${variablename} or $variablename

In the <snmp-device-display> section of a probe file, an occurrence of a variable name (with or without the curly braces ({...}) is replaced with its value, rounded to the nearest integer. For example, if a calculation variable has the value of 3.14159265, using it in the <display-output> section results in the value of "3"; if the variable had the value 4.75 it is be displayed as "5". This value is chartable, that is, clicking it makes a new strip chart, or dragging it adds it to an existing chart. The ipForwDatagrams variable defined above could be referred to in either of these forms:

${ipForwDatagrams} or $ipForwDatagrams

${chartable: xxx : yyy}

In the <snmp-device-display> section of a probe file, the ${chartable: ...} macro creates an underlined value that can be clicked to add it to a strip chart. The macro also controls the field width and number of decimal places. There are two parameters:

• A formatting string that indicates the number and placement of the digits near the decimal point, and the variable to be formatted. The formatting string can be either a mask composed with the '#' symbol or a quoted printf specifier like those accepted by the sprintf function.
• A variable or an expression (but not a macro). InterMapper evaluates the expression and displays the result according to the formatting string.

Examples:

${chartable: #.## : 3 }:         3.14 -->        3.14
${chartable: #.####### : 3 }:    3.1415927 -->   3.1415927
${chartable: "%3d" : 3 }:        3 -->         __3 (with 2 leading spaces)
${chartable: "%9.7f" : 3}:       3.1415927 ->    3.1415927
${chartable: "%11.7f" : 3}:      3.1415927 ->  __3.1415927 (also with 2 leading spaces)
${chartable: #.####### : 3*100}: 314.1592650 --> 314.1592650
${chartable: "%9.7f" : 3*100}:   314.1592650 ->  314.1592650
${chartable: "%11.7f" : 3*100}:  314.1592650 ->  314.1592650 (no  leading spaces)

${variablename:legend}

In the <snmp-device-display> section of a probe file, the ${variablename:legend} macro is replaced with the legend field defined for that variable in the <snmp-device-variables> section. For example:

${ipForwDatagrams:legend}

results in the string "Forwarded datagrams".

${eval: expr}

In the <command-display> section of command-line probes, the <snmp-devicedisplay> section of SNMP probes, or the <script-output> section of TCP probes, use the ${eval} macro to perform calculations or to assign values to variables.

These macros are detailed inthe Built-in Variable Reference topic.

Enumerated Values

Many MIBs use an integer to represent one of several states. For example, ifOperStatus (1.3.6.1.2.1.2.2.1.8.x) is defined in MIB-II as:

INTEGER { up(1), down(2), testing(3) }

This means that the value 1 represents the "up" condition; 2 represents "down"; and 3 represents "testing".

If you define a variable to retrieve this value as INTEGER or DEFAULT, the probe will display the value as a number. If you define it as a STRING, the probe will use the MIB to find the string representation, and will set the variable to the value "up", "down", or "testing".

If the OID or MIB name isn't defined (because the corresponding MIB hasn't been imported or because of a typo), the probe will display the integer value.