OpenView's Extensible Agent (Essential SNMP)

11.3.1. Tables

Tables allow the agent to return multiple lines of output (or other sets of values) from the commands it executes. At its most elaborate, a table allows the agent to return something like a spreadsheet. We can retrieve this spreadsheet using snmpwalk -- a process that's significantly easier than issuing separate get operations to retrieve the data one value at a time. One table we've already seen is .iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable, which is defined in MIB-II and contains information about all of a device's interfaces.

Every table contains an integer index, which is a unique key that distinguishes the rows in the table. The index starts with 1, for the first row, and increases by one for each following row. The index is used as an instance identifier for the columns in the table; given any column, the index lets you select the data (i.e., the row) you want. Let's look at a small table, represented by the text file animal.db:

1       Tweety        Bird    Chirp   2
2       Madison       Dog     Bark    4
3       "Big Ben"     Bear    Grrr    5

Our goal is to make this table readable via SNMP, using OpenView's extensible agent. This file is already in the format required by the agent. Each column is delimited by whitespace; a newline marks the end of each row. Data that includes an internal space is surrounded by quotes. OpenView doesn't allow column headings in the table, but we will want to think about the names of the objects in each row. Logically, the column headings are nothing more than the names of the objects we will retrieve from the table. In other words, each row of our table consists of five objects:

animalIndex: An index that specifies the row in the table. The first row is 1, as you'd expect for SNMP tables. The SYNTAX for this object is therefore INTEGER.

animalName: The animal's name. This is a text string, so the SYNTAX of this object will be DisplayString.

animalSpecies: The animal's species (another text string, represented as a DisplayString).

animalNoise: The noise the animal makes (another DisplayString).

animalDanger: An indication of how dangerous the animal is. This is another INTEGER, whose value can be from 1 to 6. This is called an "enumerated integer"; we're allowed to assign textual mnemonics to the integer values.

At this point, we have just about everything we need to know to write the MIB that allows us to read the table. For example, we know that we want an object named animalNoise.2 to access the animalNoise object in the second row of the table; this object has the value Bark. It's easy to see how this notation can be used to locate any object in the table. Now let's write the MIB definition for the table.

TableExtExample DEFINITIONS ::= BEGIN

internet        OBJECT IDENTIFIER ::= { iso(1) org(3) dod(6) 1 }
enterprises     OBJECT IDENTIFIER ::= { internet(1) private(4) 1 }
mauro           OBJECT IDENTIFIER ::= { enterprises(1) 2789 }
other           OBJECT IDENTIFIER ::= { mauro 255 }

AnimalEntry ::=
    SEQUENCE {
    animalIndex INTEGER,
    animalName DisplayString,
    animalSpecies DisplayString,
    animalNoise DisplayString,
    animalDanger INTEGER
    }

animalTable OBJECT-TYPE
    SYNTAX SEQUENCE OF AnimalEntry
    ACCESS not-accessible
    STATUS mandatory
    DESCRIPTION
        "This is a table of animals that shows:
         Name
         Species
         Noise
         Danger Level
         FILE-NAME: /opt/local/animal.db"
    ::= { other 247 }

animalEntry OBJECT-TYPE
    SYNTAX AnimalEntry
    ACCESS not-accessible
    STATUS mandatory
    DESCRIPTION
        "List of animalNum"
    INDEX { animalIndex }
    ::= { animalTable 1 }

animalIndex OBJECT-TYPE
    SYNTAX INTEGER
    ACCESS read-only
    STATUS mandatory
    DESCRIPTION
        "The unique index number we will use for each row"
    ::= { animalEntry 1 }

animalName OBJECT-TYPE
    SYNTAX DisplayString
    ACCESS read-only
    STATUS mandatory
    DESCRIPTION
        "My pet name for each animal"
    ::= { animalEntry 2 }

animalSpecies OBJECT-TYPE
    SYNTAX DisplayString
    ACCESS read-only
    STATUS mandatory
    DESCRIPTION
        "The animal's species"
    ::= { animalEntry 3 }

animalNoise OBJECT-TYPE
    SYNTAX DisplayString
    ACCESS read-only
    STATUS mandatory
    DESCRIPTION
        "The noise or sound the animal makes"
    ::= { animalEntry 4 }

animalDanger OBJECT-TYPE
    SYNTAX INTEGER {
        no-Danger(1),
        can-Harm(2),
        some-Damage(3),
        will-Wound(4),
        severe-Pain(5),
        will-Kill(6)
    }
    ACCESS read-write
    STATUS mandatory
    DESCRIPTION
        "The level of danger that we may face with the particular animal"
    ::= { animalEntry 5 }

END

The table starts with a definition of the animalTable object, which gives us our DESCRIPTION and tells the agent where the animal.db file is located. The SYNTAX is SEQUENCE OF AnimalEntry. AnimalEntry (watch the case) gives us a quick view of all our columns. You can leave AnimalEntry out, but we recommend that you include it since it documents the structure of the table.

The table is actually built from animalEntry elements -- because object names are case sensitive, this object is different from AnimalEntry. animalEntry tells us what object we should use for our index or key; the object used as the key is in brackets after the INDEX keyword.

The definitions of the remaining objects are similar to the definitions we've already seen. The parent-subtree for all of these objects is animalEntry, which effectively builds a table row from each of these objects. The only object that's particularly interesting is animalDanger, which uses an extension of the INTEGER datatype. As we noted before, this object is an enumerated integer, which allows us to associate textual labels with integer values. The values you can use in an enumerated type should be a series of consecutive integers, starting with 1.[62] For example, the animalDanger object defines six values, ranging from 1 to 6, with strings like no-danger associated with the values.

[62]Some SNMPv1 SMI-compliant MIB compilers will not allow an enumerated type of 0 (zero).

You can save this table definition in a file and use the xnmloadmib command to load it into OpenView. Once you've done that and created the animal.db file with a text editor, you can walk the table:

$ snmpwalk sunserver1 .1.3.6.1.4.1.mauro.other.animalTable
animalEntry.animalIndex.1 : INTEGER: 1
animalEntry.animalIndex.2 : INTEGER: 2
animalEntry.animalIndex.3 : INTEGER: 3
animalEntry.animalName.1 : DISPLAY STRING-(ascii): Tweety
animalEntry.animalName.2 : DISPLAY STRING-(ascii): Madison
animalEntry.animalName.3 : DISPLAY STRING-(ascii): Big Ben
animalEntry.animalSpecies.1 : DISPLAY STRING-(ascii): Bird 
animalEntry.animalSpecies.2 : DISPLAY STRING-(ascii): Dog
animalEntry.animalSpecies.3 : DISPLAY STRING-(ascii): Bear
animalEntry.animalNoise.1 : DISPLAY STRING-(ascii): Chirp
animalEntry.animalNoise.2 : DISPLAY STRING-(ascii): Bark
animalEntry.animalNoise.3 : DISPLAY STRING-(ascii): Grrr
animalEntry.animalDanger.1 : INTEGER: can-Harm
animalEntry.animalDanger.2 : INTEGER: will-Wound
animalEntry.animalDanger.3 : INTEGER: severe-Pain

snmpwalk goes through the table a column at a time, reporting all the data in a column before proceeding to the next. This is confusing -- it would be easier if snmpwalk read the table a row at a time. As it is, you have to hop from line to line when you are trying to read a row; for example, to find out everything about Tweety, you need to look at every third line (all the .1 items) in the output.

Two more things are worth noticing in the snmpwalk output. The first set of values that snmpwalk reports are the index values (animalIndex). It then appends each index value to each OID to perform the rest of the walk. Second, the animalDanger output reports strings, such as can-Harm, rather than integers. The conversion from integers to strings takes place because we defined the animalDanger object as an enumerated integer, which associates a set of possible values with strings.

Of course, just reading a table doesn't do a whole lot of good. Let's say that we need to update this file periodically to reflect changes in the animals' behavior. The animalDanger object has an ACCESS of read-write, which allows us to set its value and update the database file using our SNMP tools. Imagine that the dog in row 2 turns very mean. We need to turn its danger level to 5 (severe-Pain). We could edit the file by hand, but it's easier to issue an snmpset:

$ snmpset -c private sunserver2 \
mauro.other.animalTable.animalEntry.animalDanger.2 integer "5"
mauro.other.animalTable.animalEntry.animalDanger.2 : INTEGER: severe-Pain

Now let's go back and verify that the variable has been updated:[63]

[63]We could already deduce that the set was successful when snmpset didn't give us an error. This example does, however, show how you can snmpget a single instance within a table.

$ snmpget sunserver2 \
mauro.other.animalTable.animalEntry.animalDanger.2
mauro.other.animalTable.animalEntry.animalDanger.2 : INTEGER: severe-Pain

Once the snmpset is complete, check the file to see how it has changed. In addition to changing the dog's danger level, it has enclosed all strings within quotes:

1 "Tweety" "Bird" "Chirp" 2
2 "Madison" "Dog" "Bark" 5
3 "Big Ben" "Bear" "Grrr" 5

There are even more possibilities for keeping the file up-to-date. For example, you could use a system program or application to edit this file. A cron job could kick off every hour or so and update the file. This strategy would let you generate the file using a SQL query to a database such as Oracle. You could then put the query's results in a file and poll the file with SNMP to read the results. One problem with this strategy is that you must ensure that your application and SNMP polling periods are in sync. Make sure you poll the file after Oracle has updated it, or you will be viewing old data.

An effective way to ensure that the file is up-to-date when you read it is to use FILE-COMMAND within the table's definition. This tells the agent to run a program that updates the table before returning any values. Let's assume that we've written a script named get_animal_status.pl that determines the status of the animals and updates the database accordingly. Here's how we'd integrate that script into our table definition:

animalTable OBJECT-TYPE
    SYNTAX   SEQUENCE OF AnimalEntry
    ACCESS   not-accessible
    STATUS   mandatory
    DESCRIPTION
        "This is a table of animals that shows:
         Name
         Species
         Noise
         Danger Level
         FILE-COMMAND: /opt/local/get_animal_status.pl
         FILE-NAME: /opt/local/animal.db"
    ::= { other 247 }

The command must finish within 10 seconds or the agent will kill the process and return the old values from the table. By default, the agent runs the program specified by FILE-COMMAND only if it has not gotten a request in the last 10 seconds. For example, let's say you issue two snmpget commands, two seconds apart. For the first snmpget, the agent runs the program and returns the data from the table with any changes. The second time, the agent won't run the program to update the data -- it will return the old data, assuming that nothing has changed. This is effectively a form of caching. You can increase the amount of time the agent keeps its cache by specifying a value, in seconds, after FILE-COMMAND-FREQUENCY. For example, if you want to update the file only every 20 minutes (at most), include the following commands in your table definition:

       FILE-COMMAND: /opt/local/get_animal_status.pl
       FILE-COMMAND-FREQUENCY: 1200
       FILE-NAME: /opt/local/animal.db"

This chapter has given you a brief introduction to three of the more popular extensible SNMP agents on the market. While a thorough treatment of every configurable option for each agent is beyond the scope of this chapter, it should help you to understand how to use extensible agents. With an extensible agent, the possibilities are almost endless.

11.3. OpenView's Extensible Agent

Figure 11-2. mauro subtree

11.3.1. Tables