SystemEDGE (Essential SNMP)

11.2.1. Extensibility for Unix and Windows NT

The SystemEDGE agent has a private MIB that defines a table called the extensionGroup. Its full OID is 1.3.6.1.4.1.546.14 (iso.org.dod.internet.private.enterprises.empire.extensionGroup). This is where you define your own objects. The first object you define has the OID extensionGroup.1.0 (1.3.6.1.4.1.546.14.1.0), where the .0 indicates that the object is scalar; the next has the OID extensionGroup.2.0, and so on. Note that all the objects defined this way must be scalar. For advanced users, Concord has developed a plug-in architecture for SystemEDGE that allows you to develop complex extended objects (including tables) and full-blown MIBs.

To extend the agent, start by editing the sysedge.cf file. This file tells the agent to which extended OIDs it must respond. The format of a command in this file is:

extension LeafNumber Type Access 'Command'

The keyword extension tells the agent that this configuration entry is an extension that belongs to the extensionGroup. LeafNumber is the extension object number -- i.e., the number you assign to the object in the extensionGroup table. Type is the SNMP type for the OID. Valid types are Integer, Counter, Gauge, Octetstring, TimeTicks, Objectid, and IPAddress. Access is either Read-Only or Read-Write. And finally, Command is the script or program the agent will execute when this particular OID is queried by an NMS. We'll talk more about this shortly. Here are some examples of extension objects:

extension 1 Integer Read-Only '/usr/local/bin/Script.sh'
extension 2 Gauge Read-Only '/usr/local/bin/Script.pl'
extension 33 Counter Read-Write '/usr/local/bin/Program'

The first item defines a read-only OID of type Integer. The OID is 1.3.6.1.4.1.546.14.1.0. The agent will execute the command /usr/local/bin/exampleScript.sh when this OID is queried. The second entry is similar, except its type is Gauge and its numeric OID is 1.3.6.1.4.1.546.14.2.0. The third example simply shows that LeafNumber doesn't have to be sequential; you can use any number you want, provided that it is unique.

Extending the agent allows you to write your own scripts that do whatever you want: you can get information about devices or programs that are not SNMP-capable, as long as you can write a script that queries them for their status. In the example above, /usr/local/bin/Script.sh, /usr/local/bin/Script.pl, and /usr/local/bin/Program are all examples of scripts the agent will execute when the OID assigned to each script is queried. Two requirements must be met by any script or program:

All set, get, and getnext requests must generate output. For get and getnext, the output from the script should be the actual value of the object requested. This means that the script or program that fetches the required information must return a single value. For a set request, the script should return the object's new value. The request will fail if there is no output. (Note that for a set request, a script may succeed in changing the state of the device even if it produces no output and the agent considers the script to have failed.)
The script or program should print whatever information it needs to return (based on the type of request), followed by a newline character. The agent parses only up to this character. If a newline is the first character the agent encounters, the agent generates an error and returns this to the NMS or SNMP application.

The agent sends three arguments to the script or program it executes: the LeafNumber, the request type (GET, GETNEXT, or SET, in capital letters), and a string that represents some value to be set (the third argument is used only for SET requests). The following skeletal Perl script, called skel.pl, shows how you can use all three arguments:

#!/usr/local/bin/perl

if ($ARGV[0] == 1) {
   # OID queried is 1.3.6.1.4.1.546.14.1.0
   if ($ARGV[1] eq "SET") {
          # use $ARGV[2] to set the value of something and return the set value, 
          # followed by a newline character, to the agent
   } elsif (($ARGV[1] eq "GET") || ($ARGV[1] eq "GETNEXT")) {
          # get the information to which this OID pertains, then return it,
          # followed by a newline character, to the agent
   }
} else {
   return 0;
   # return 0, since I don't know what to do with this OID
}

All you have to do is add the logic that takes some action to retrieve (or set) the appropriate value and return the correct value to the agent. The corresponding entry in sysedge.cf might look something like this:

extension 1 Integer Read-Write '/usr/local/bin/skel.pl'

What we've done so far gives the agent the ability to respond to requests for a new kind of data. We still need to solve the other part of the puzzle: telling the management station that some new kind of data is available for it to retrieve. This requires creating an entry in a MIB file.[56] After adding this entry to the file, you must recompile the MIB into your NMS system so that the NMS will know the access and type of each of the extended objects in the MIB for which it is to perform queries. Here is a MIB entry that corresponds to the previous agent extension:

[56]Concord recommends that you keep all your extended MIB objects in a separate file, away from the SystemEDGE MIB file. This makes it easier for you to recompile it into your NMS.

skeletonVariable OBJECT-TYPE
    SYNTAX Integer
    ACCESS Read-Write
    DESCRIPTION
        "This is an example object."
::= { extensionGroup 1 }

Once this is compiled into the NMS, you can query the object by specifying its full name (iso.org.dod.internet.private.enterprises.empire.extensionGroup.skeletonVariable.0). Alternatively, you can use the numeric OID; for example:

$ snmpget server.ora.com public .1.3.6.1.4.1.546.14.1.0

Security can be a concern when writing your own extension scripts. On Unix systems, it's a good idea to create a separate user and group to execute your extensions, rather than allowing the root user to run your scripts.

11.2. SystemEDGE

11.2.1. Extensibility for Unix and Windows NT

11.2.2. Added Extensibility for Windows NT