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.
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]
$ 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.
