home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Book HomeEssential SNMPSearch this book

11.2. SystemEDGE

The SystemEDGE agent is also extensible. No other system processes need to be run in order to extend this agent. It comes with three predefined extended objects: Domain Name System (DNS) for Unix, Network Information System (NIS) for Unix, and Remote Pinger for Unix and Windows NT. The first object returns the domain name of the underlying operating system, the second returns the NIS domain name of the underlying operating system, and the third sends ICMP requests to a remote host from the system on which the agent is running. While these are nice scripts to have, what we want to focus on is how to add your own OIDs to the agent.

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:

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.2. Added Extensibility for Windows NT

While the extensionGroup is supported on all platforms, the Windows NT version of SystemEDGE allows you to extend SystemEDGE with objects taken from the registry and performance registry. You can gain access to configuration data and performance data, which are normally viewed using regedit and perfmon. The Windows NT extension group is defined as iso.org.dod.internet.private.enterprises.empire.nt.ntRegPerf (1.3.6.1.4.1.546.5.7 ). As with the Unix extensions, the NT extensions are defined in the sysedge.cf file.

To configure a registry extension, add a line with the following syntax to sysedge.cf:

ntregperf LeafNumber Type Registry 'Key' 'Value'
The keyword ntregperf defines this as an NT registry or performance extension object. LeafNumber and Type are the same as for Unix extensions. The keyword Registry identifies this entry as a registry extension. Registry extensions are read-only. Key is a quoted string that specifies the registry key to be accessed. Value is the value you want to read from the key. Here is an example:

ntregperf 1 OctetString Registry 
'SYSTEM\CurrentControlSet\Control\CrashControl' 'DumpFile'
This creates a registry extension object that returns the path to the crash-control dump file. The OID is 1.3.6.1.4.1.546.5.7.1.0 (iso.org.dod.internet.private.enterprises.empire.nt.ntRegPerf.1.0).

To configure a performance extension, use the following syntax:

ntregperf LeafNumber Type Performance 'Object' 'Counter' 'PerfInstance'
Here again, ntregperf is the keyword that indicates this is an NT registry/performance extension object. LeafNumber and Type should be familiar to you. The keyword Performance indicates that we're reading a value from the performance registry; performance extensions are read-only. Object specifies the performance object to be accessed. Counter specifies the object's performance counter value to be accessed. Finally, PerfInstance specifies the performance counter instance to be accessed. This should be identical to what's listed with perfmon. Here's a typical performance extension:

ntregperf 2 Counter Performance 'TCP' 'Segments Sent/sec' '1'
You can use this extension to watch the total number of TCP segments transmitted by the system. Its OID is 1.3.6.1.4.1.546.5.7.2.0 (iso.org.dod.internet.private.enterprises.empire.nt.ntRegPerf.2.0). Keep in mind that you should create a MIB entry (in a MIB file) for any NT extensions you create, similar to the entry we defined above for skeletonVariable.

The examples in this section should be enough to get you up and running with an extended SystemEDGE agent. Be sure to read the SystemEDGE manual for a complete treatment of this topic.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.