The Net-SNMP Programming Guide - Cuddletech

1 The Net-SNMP Programming GuideBen RockwoodUpdated: Nov 17th, 2004 Contents1 Introduction to General Overview .. Three Flavors of snmp .. What we won t discuss .. 42 MIBs & OIDs .. MIBs .. OID DataTypes .. MIB-II .. Adding MIBs to Net-SNMP .. 103 The Net-SNMP Probing a device: snmp WALKs .. Polling Individual OIDs: snmp GETs .. Net-SNMP CLI Tool Options .. 134 Polling Simple Polling with PERL .. The Net-SNMP PERL Module .. 165 Trap The Trap Daemon Configuration .. A Simple Trap Handler .. Starting the Trap Daemon .. 216 The Net-SNMP C snmp Internals .. Watching snmp on the wire .. A simple example .. Closing Thoughts .. 291 Chapter 1 Introduction to General OverviewSimple Network Management Protocol is asimplemethod of interacting withnetworked devices. The standard was defined by IETF RFC 1157 in May of1990. snmp can often seem quite confusing and overly complicated, its availableAPIs tend to put alot of wrapping around what should be very simple.

2 Theavailable books on the topic tend to only complicate the subject, not is extremely easy for any programmer to understand. A gross oversimplification can explain the system simply. A network device runs an snmp agentas a daemon process which answers requests from the network. The agentprovides a large number ofObject Identifiers(OIDs). An OID is a unique key-value pair. The agent populates these values and makes them available. AnSNMP manager(client) can then query the agents key-value pairs for specificinformation. From a Programming standpoint it s not much different than im-porting a ton of global variables. snmp OIDs can be read or written. Whilewriting information to an snmp device is fairly rare, it is a method used byseveral management applications to control devices (such as an administrativeGUI for your switches). A basic authentication scheme exists in snmp , allowingthe manager to send acommunity name(think cleartext password) to autho-rize reading or writing of OIDs.

3 Most devices use the insecure community name public . snmp communication is preformed via UDP on ports 161 and that I didn t mention MIBs yet! The importance of MIBs aregreatlyoverrated. MIBs look complicated at first, but they are extremely simple. OIDsare numerical and global. An OID looks similar to an IPv6 address and differentvendors have different prefixes and so forth. The OIDs are long enough thatit s complicated for a human to remember or make sense of them, so a methodwas devised for translating a numeric OID into a human readable form. Thistranslation mapping is kept in a portable flat text file called aManagementInformation BaseorMIB. You donotneed a MIB to use snmp or query2 CHAPTER 1. INTRODUCTION TO SNMP3 snmp devices, however without a MIB you ll have to simply guess what thedata your looking at means. In some cases this is easy, such as seeing hostnames, disk usage numbers, or port status information. Other times it can bemore difficult and a MIB is more useful.

4 It is not unusual for some applicationsto be written using strictly numeric IODs allowing the end user to avoid thehassles of properly installing a MIB. The action of installing a MIB is reallyjust putting it in a place where your snmp client application can find it toperform the can be used in 2 ways: polling and means thatyou write an application that sets an snmp GET request to an agent lookingsome value. This method is useful because if the device responds you get theinformation you want and if the device does not respond you know there is aproblem. Polling is an active form of monitoring. On the other hand, snmp trapscan be used for passive monitoring by configuring an agent to contactanother snmp agent when some action at traps deeper, a network device such as a router can be configuredto send snmp traps for certain events. For instance, you can configure CiscoIOS to send traps either when an individual event occurs such as a linkDown(IOS: snmp -server enable traps snmp linkdown) or when any defined trap eventhappens (IOS: snmp -server enable traps snmp ).

5 When a trap event occurs, theagent on the device will send the trap to a pre-configured destination commonlycalled atrap host. The trap host will have it s own agent running which willaccept and process the traps as they come in. The processing of these trapsare done bytrap handlers. Trap Handlers can be written in any language andare provided with information from the sent trap via STDIN. The handler canthen do whatever is appropriate to respond to the trap, such as sending emailor doing anything else you could is most commonly used in conjunction with aNetwork ManagementSystem(NMS). Popular NMS s include BMC Patrol, CA Unicenter, Sun Man-agement Console (formerly SyMon), IBM Tivoli NetView, and the world famousHP OpenView. Even an Open Source NMS is now available, the aptly namedOpenNMS. The goal of a NMS is to provide a single point of monitoring andadministration of all your snmp enabled devices. By configuring your deviceagents to allow write access you can even manipulate your environment from asingle application.

6 When an environment is architected around a NMS solutionyou can be given unparalleled levels of control and visibility over your entire en-vironment at a glance. While Net-SNMP provides all the tools you would needto build your own NMS we won t discuss the subject any further here. However,bear in mind that if you think the vendor of your snmp enabled device isn t asforthcoming about details of their agent implementation as you d like, it s mostlikely because they would like you to simply buy their NMS or a plug-in to usetheir device with one of the other popular NMS 1. INTRODUCTION TO Three Flavors of SNMPT hree different version of snmp exist: SNMPv1 (RFC s 1155, 1157, and 1212),SNMPv2c (RFC s 1901 through 1908), and SNMPv3 (RFC s 3411 though 3418).The co-existence of all three versions are detailed in RFC is the original standard for community based management. SN-MPv2 was derived from the SNMPv1 framework but had no message definition,which was later revamped aa SNMPv2c, a community based version of SN-MPv2 with a message format similar to SNMPv1.

7 SNMPv2 added several newdatatypes (Counter32, Counter64, Gauge32, UInteger32, NsapAdress, and BITSTRING), as well as enhancements to OID tables and the setting of OID is an extensable SNMPv2 framework with a new message format, ACLand security abilities, and remote configuration of snmp is based on several other standards including theAbstract SyntaxNotation 1 Basic Encoding Rules( BER) which defines the snmp usedDatatypes and theStructure of Management Information(SMI) which detailsthe grammar used by snmp MIBs. SMI comes in two varieties: SMIv1 (RFC1155) and SMIv2 (RFC 2578). SMIv1 is now obsolete and should not be you choose to modify MIBs at some point you ll need to learn SMIv2 syntax, but otherwise they are interesting but unnecessary to this day, SNMPv1 and SNMPv2c are the most commonly used, howeverdue to the insecurity inherent to these protocols read-only access is typical. Ingeneral, don t bother with SNMPv3 unless you really need the added What we won t discussThere are several subject we will not be discussing in this paper.

8 These topicsinclude writing agents or sub-agents, writing MIB modules, trap generation andtrap sending, synchronous vs asynchronous snmp coding, and MIB that scares new or inexperienced coders away from the Net-SNMP documentation is the seemingly constant reference to synchronous and asyn-chronous applications. Don t be afraid, thats referring to applications that can tafford to sit and wait for a response. If your application needs a non-blockingmethod of handling snmp traffic, use the asynchronous interface (eg: GUIs,Threads, Forking, etc). Otherwise, just stick with the synchronous interfacesfor typical , this document addresses the use of Net-SNMP on UNIX systems refer to the Net-SNMP website for information regarding developmenton 2 MIBs & OIDsOIDs, orObject Identifiers, uniquely identify key values offered by an snmp agent. MIBs, orManagement Information Bases, provide a map between nu-meric OIDs and a textual human readable OIDsSNMP OIDs are laid out in a hierarchy forming unique addresses into a treesimilar to the DNS hierarchy.

9 Like many other forms of addressing, OIDs canbe used in 2 forms: fully qualified and relative (sometimes called relevant ).The fully qualified form starts from the root and moves outward to theindividual value on a device. An example of a fully qualified address is:. OID could be rewritten in human readable form as:. fully qualified OIDs will begin numerically Almost all OIDs will then be followed byenterprises(.1) and a unique number for the vendor as assigned by theInter-net Assigned Numbers Authority(IANA). In the example OID 789 representsthe vendor ID for the Network Appliance Corporation (NetApp). Everythingbeyond the vendor ID is based on the vendors implementation and may varybetween implementations. Please note the prefixing dot beforeiso. Similar tothe trailing dot in DNS, properly qualified IODs begin with a dot representingthe complete list of enterprise assignments can be found at the IANA web-site: relative form of an OID, on the other hand, begins from the enterprisesvalue and leaves all the implied addressing off.

10 So we can use the relative form of5 CHAPTER 2. MIBS & OIDS6the above OID numerically common form of writing OIDs is by the name of the MIB and a uniquekey defined within the MIB. For instance, we could rewrite the above OIDinto the condensed formNETWORK-APPLIANCE- condensed form follows the convention of keys, while unique, can be represented by multiple instances of that key,and thus all OIDs end with an instance value. This is why you ll notice thatmost OIDs end with MIBsThe structure of a MIBs internals are a little strange and foreign at first, butit s structured well enough that you can poke through it pretty intelligentlywithout really knowing what your doing. The structure of a MIB comes fromtheStructure of Management Information(SMI) standard detailed in IETFRFC 1155 and 2578. If you choose to modify or write your own MIBs you llbenefit from understanding SMI before hacking much on look at the header of a MIB to get a better idea of how they work:-- PowerNet-MIB { iso org(3) dod(6) internet(1) private(4)-- enterprises(1) apc(318) }PowerNet-MIB DEFINITIONS ::= BEGINIMPORTS enterprises, IpAddress, Gauge, TimeTicks FROM RFC1155-SMID isplayString FROM RFC1213-MIBOBJECT-TYPE FROM RFC-1212 TRAP-TYPE FROM RFC-1215;apc OBJECT IDENTIFIER ::= { enterprises 318 }products OBJECT IDENTIFIER ::= { apc 1 }apcmgmt OBJECT IDENTIFIER ::= { apc 2 }Comments can be inserted into a MIB by prepending them with two the header the declaration BEGIN starts off the MIB.