🚀 go-pugleaf

|                     UNIVERSAL SNMP AGENT                     |
|                     Product  Description                     |
|                                                              |
|         Document SNMPA-PD, Version 2.5, Sept 12 1992         |
|          Copyright (c) 1992 Paul Freeman Associates          |
|               14 Pleasant Street, P.O.Box 2067               |
|               Westford  Massachusetts    01886               |
|         508-692-4436   E-mail: pwilson@world.std.com         |

1  INTRODUCTION

1.1   Product Description

This paper is the Product Description for the Universal SNMP 
Agent. The Product Description gives the background, 
justification, installation procedures, components, customer 
tasks and responsibilities, support commitments, and licensing 
arrangements for the Universal SNMP Agent. The information in 
this Product Description applies for every installation of the 
Universal SNMP Agent; additional information which might apply 
for a particular installation is given in the Design Description 
for that installation.  

The Universal SNMP Agent (Product Code SNMPA) is a software 
product which implements the portable fully-compliant agent part 
of the Simple Network Management Protocol and is designed to 
install and run under any operating system and in any 
comunications environment. The Agent can be installed in ROM.  
The deliverable components of the Agent include (1) complete, 
commented, portable, machine-readable source code, excluding 
certain initialization, data-access, trap-initiation, and 
transport-layer functions which the customer must provide; (2) 
preparation and compilation tools to help the customer build 
application-specific MIBs; and (3) the Agent documentation set, 
including the Agent Functional Specification and the Agent 
Design Description. The Functional Specification and the Design 
Description together serve as the porting guide for the Agent.  
One of the most important parts of the documentation set is the 
developer's guide to preparing the data-access and trap-
initiation functions mentioned above and example code for these 
functions.  

1.2   Operational Environment 

The Universal SNMP Agent is easily installed in any modern 
hardware and operating system environment and is particularly 
suited to installation in embedded controllers. The Agent 
conforms to the requirements of embedded systems -- lean, 
compliant, correct, and robust code running under a rather 
demanding and unforgiving operating system and with relatively 
meager communications resources. The Agent is also well suited 
to workstations and PC-based products.  

2  OVERVIEW 

2.1   SNMP Background 

The history of computing has been remarkable for its frequent 
technological revolutions, as is widely understood. Of these 
staggering changes, perhaps none has been as striking and 
pervasive as the recent wide availability and explosive growth 
of networked devices. Networking has fundamentally changed the 
way in which enterprises conduct their affairs.  As each network 
grows, the need to monitor, diagnose, and manage the devices 
interconnected on that net also grows (and much more rapidly and 
urgently). In the past, the result was generally a collection of 
ad hoc network management tools specific to the single net. The 
proliferation of incompatible tools led naturally to the demand 
for a standard for network-management tools. Two standards 
emerged in response to this need. The first was CMIP, for 
"Common Management Information Protocol," from the International 
Standards Organization (ISO). The second was SNMP, for "Simple 
Network Management Protocol," from the Internet community. CMIP 
has been largely ignored, mostly because the standard is 
incomplete. SNMP is presently in the ascendant and promises to 
remain so. The great majority of standards-based management 
schemes implement some subset of SNMP.  

The SNMP standard embodies the "client-server" paradigm and 
foresees two distinct entities: the "manager" or client part 
requests services of an "agent" or server part. The 
manager/client typically runs under user control in a management 
station, perhaps with some kind of convenient graphical user 
interface. The manager interacts over the net with one or more 
agents/servers, one agent running autonomously in each device 
under management.  

The SNMP manager-agent partnership operates in two concurrent 
modes. In the first mode, the manager initiates transactions: it 
either requests the agent to get and return the states of 
certain variables -- counters, threshold values, and the like -- 
or commands the agent to set the states of those variables. 
Several hundred variables may be read and written in this way. 
In the other mode of operation, the agent may initiate 
transactions: under certain predefined conditions -- an error 
counter exceeds a preset threshhold -- the agent sends 
unsolicited trap messages to the manager. The manager's ability, 
with the help of the responsive cooperating agent, to examine 
and modify conditions in any remote network-connected device is 
the key to effective and proactive network management.  

2.2   SNMP-Agent Development 

The SNMP mechanism has since 1990 proven itself a management 
protocol of great power, utility, generality, and elegance. It 
is installed on hundreds of device types; it will certainly be 
installed on several thousands more. SNMP is arguably the 
network-management scheme of choice for the next several years 
at the least. But the development from scratch of an SNMP agent 
is a frightening prospect for several reasons: 

First, SNMP-agent development, while straightforward in concept, 
is complex in execution: the correct design, coding, debugging, 
testing, and documentation of an SNMP agent is a formidable task 
which can easily engulf many hundreds of man-hours.  

Second, because SNMP is relatively new and narrowly-understood 
technology with its attendant learning curve, SNMP-agent 
development is difficult to schedule accurately and often 
requires an open-ended commitment of time and resources.  

Third, for reasons that are completely accidental and 
historical, SNMP remains closely associated with the TCP/IP 
protocol stack; the great majority of current available 
implementations of SNMP do, in fact, depend upon TCP/IP (or, 
more properly, UDP/IP). But the result is that we often 
mistakenly perceive TCP/IP as a prerequisite for SNMP.  

Fourth, because of the misperception that SNMP depends upon 
TCP/IP, we sometimes think that SNMP naturally requires all of 
the elaborate LAN hardware and software that TCP/IP seems to 
need.  

Finally, again principally because of misperceptions about 
transport-layer requirements, it's often thought that SNMP must 
be installed under some version of the Unix operating system.  
These five considerations must give us pause when we consider 
developing an SNMP agent.  

3  THE UNIVERSAL SNMP AGENT 

The Universal SNMP Agent was developed to meet the needs of 
customers who require SNMP capability in a variety of hardware 
platforms, operating systems, communications frameworks, and 
network arrangements; and all at a reasonable, predictable cost.  
The Agent helps ensure timely, correct, cost-effective 
implementation.  

3.1   Correct Implementation 

The Agent is delivered to the customer as a full, correct, RFC-
compliant, unit-tested body of source code. The code is 
orthogonal and highly modular.  

3.2   Transport-Layer Independence 

The SNMP Agent is completely independent of the rules of the 
transport layer the customer has in place. If there is no 
transport layer present, then the customer may choose to 
implement a transport layer or may ask us to implement that 
layer.  

3.3   Communications-Environment Independence 

The Agent imposes no requirements whatever as to the underlying 
communications medium. The Agent is designed to take advantage 
of whatever medium is chosen.  

3.4   Operating-System Independence 

The Agent makes no assumptions about the operating system under 
which it will run. The Agent is designed to be installed under a 
variety of operating systems. We expect that the Agent will run 
under a version of Unix; under some commercial real-time 
operating system like VRTX, pSOS+, or iRMX; under MS-DOS; under 
a real-time Unix variant like LYNXOS; or under an operating 
system of the customer's design.  

3.5   Predictable Installation Schedule 

The customer may elect to port and install the SNMP Agent 
himself or he may ask us to port the Agent to his platform. If 
we are asked to do so, we will port the Agent in a period no 
longer than three calendar weeks.  

4  DELIVERABLES   

4.1   Customer Responsibilities 

The customer takes responsibility for five of the items outlined 
in Section 4. If the customer wishes, we will implement any or 
all of these items at a rate separate from and in addition to 
the fixed Agent price. The customer-supplied modules are these: 

4.1.1  MIBs: The customer undertakes the preparation of as many 
MIBs as are needed in the application. The Agent will accomodate 
any number of MIBs.  We supply example MIB implementations for 
MIB-I and MIB-II. We also supply a MIB compiler to help with MIB 
preparation.  

4.1.2  Configuration module: The customer supplies code to perform 
certain configuration tasks and initialize the MIBs at Agent 
startup time. We supply example code for this function.  

4.1.3  Variable-access module: The customer supplies Agent-callable 
functions to read and write variables that correspond to object 
instances in the MIB.  

4.1.4  Trap module: The customer implements a code segment to notice 
when a trap is indicated and to call the SNMP Agent to send that 
trap.  

4.1.5  Transport layer: The customer supplies the transport layer.  

4.2   Example Source Code 

We supply several modules as examples or templates for the 
customer's guidance in preparing the modules for which he is 
responsible. The example and template modules are these: 

4.2.1  MIBs: We deliver several example MIB implementations, 
including MIB-I and MIB-II.  

4.2.2  Configuration module: Provides facilities for initial 
configuration, and possible on-the-fly reconfiguration, for the 
MIB interface, access verification, and authentication-trap 
modules. This module is provided as a template.  

4.2.3  Trap module: Provides network entity with the ability to send 
any SNMP traps. This module is provided as template.  

4.2.4. Working example: Finally, we also supply a complete, 
working example implementation of the Agent over the UDP/IP 
stack on Unix SVR4.  

4.3   Core Agent Source Code 

We deliver modular, portable Agent sources as about 3000 lines 
of C-language code in machine-readable form. The orthogonal 
Agent consists of several modules with minimal links and 
interdependencies among them. The customer need make no changes 
whatever in these modules. The core Agent modules are these: 

4.3.1  Agent module: Performs input-packet decomposition and 
analysis, processes packet variables using a service provided by 
the customer-supplied variable-interface module.  

4.3.2  Access verification module: Provides mapping of a community 
string and packet source onto one of an unlimited number of 
possible views.  

4.3.3  Authentication trap module: Constructs an authentication-
failed trap packet when the access verification module is unable 
to map an authentication datum; calls the customer-supplied 
transport layer to send the packet.  

4.3.4  Codec module: Provides the Agent with facilities for encoding 
and decoding ASN.1 SNMP packets.  

4.3.5  Miscellaneous-facilities module: Provides the Agent with 
miscellaneous basic services required. For example, this module 
holds the function to compare two object identifiers.  

4.3.6  Supplemental module: Provides basic C library services; 
intended for use in an environment lacking a standard C library.  

4.4   Tools 

As part of the Agent package, we supply a public-domain tool 
kit: a MIB compiler and a test subsystem.  

4.5   Documentation 

We supply two documents to support the Agent. The first is the 
Agent Functional Specification, which describes what the Agent 
does. The Functional Specification describes the interfaces to 
the customer-supplied functions. The second document is the 
Agent Design Description, which describes how and why the Agent 
does it. Any quirks or anomalies which make the installation 
different from other installations appear in an appendix to the 
Design Description.  

5  ORGANIZATION OF THE UNIVERSAL SNMP AGENT

The core code proper of the Universal SNMP Agent is furnished as 
a collection of functions designed to be called by the user's 
Transport-Layer code which, conceptually, resides within the 
user's main program. The Agent, in turn, calls user-supplied 
functions to read and write variables which correspond to MIB 
object instances in the several MIBs the user may implement. Any 
number of MIBs may be implemented. An overview of the inter-
action among the user's main program, the user's MIB-access 
code, and the Agent is shown below in Figure 1.  

+------------------+  +------------------+  +------------------+
|       USER       |  |      AGENT       |  |       USER       |
|  Main-line Code  |  |    Core Code     |  |  Access to MIBs  |
+------------------+  +------------------+  +------------------+
| main ()          |  |                  |  |                  |
| Initialization.  |  |                  |  |                  |
| Configuration.   |  |                  |  |                  |
| Transport-Layer  |  |                  |  |                  |
|  receive packet; |  |                  |  |                  |
|  if SNMP packet, |  |                  |  |                  |
|  then call Agent ---> Parse and decode |  |                  |
|                  |  | ASN.1-coded pkt, |  |                  |
|                  |  | check authori-   |  |                  |
|                  |  | zation; if auth  |  |                  |
|                  |  | OK, call User    |  |                  |
|                  |  | MIB-access func  ---> Check access     |
|                  |  |                  |  | rights to, then  |
|                  |  |                  |  | read/write, MIB  |
|                  |  |                  |  | object instances |
|                  |  |                  |  | and return vals  |
|                  |  | Code and build   <--- to Agent core.   |
|                  |  | ASN.1 auth-trap  |  |                  |
|                  |  | or response pkt, |  |                  |
|                  |  | return the pkt   |  |                  |
| Transport-Layer  <--- to User.         |  |                  |
|  send returned   |  |                  |  |                  |
|  auth-trap or    |  |                  |  |                  |
|  response pkt.   |  |                  |  |                  |
+------------------+  +------------------+  +------------------+

     Figure 1   Data and Control Flow in User and Agent Code


6  INSTALLATION PROCESS 

Installation of the Agent consists of several well-defined 
steps. These are described below as if the customer were 
performing the entire installation himself. The order in which 
the steps are treated is of no particular significance. All the 
steps but the last can be taken in parallel.  

6.1   Compile and Test Agent Sources 

First, the Agent sources proper, as we deliver them, are 
compiled and unit-tested. Compilation is straightforward using 
our supplied makefiles.  

6.2   Prepare MIBs 

Second, the MIBs that the application requires are prepared. We 
supply MIB templates to help with this.  

6.3  Implement Variable-Access Functions 

Since the Agent as delivered cannot know how to access the 
variables which will become SNMP object instances, we ask the 
customer to implement functions to read and write these 
variables. We supply example code to guide the implementor.  

6.4   Implement Trap-Initiation Functions 

The Agent likewise cannot know when traps are to be sent, so we 
ask the customer to implement functions that notice when a trap 
message should be delivered and then call the function in the 
Agent which actually issues the trap. Again, we supply example 
code to guide the implementor.  

6.5   Implement Initialization and Configuration Functions 

When the Agent is started, some function needs to set up the 
initial configuration and to initialize the MIBs. We supply 
example code for this function to guide the implementor.  

6.6   Implement Transport-Layer Interface 

As the final implementation step, the interface to the transport 
layer needs to be prepared. We supply example code for this, as 
well.  

6.7   Compile, Link, and Load 

When the implementation steps above are done, the now-complete 
ported Agent is ready for test.  


7  SUPPORT 

If, within a period of 30 days of purchase, the functionality of 
the Agent proves unsatisfactory we will either fix the Agent or, 
at the customer's option, remove it and refund the purchase 
price. We offer E-mail support for the Agent, at no charge, 
for a year from the date of purchase.  

8  SOFTWARE LICENSING 

We ask the customer to observe certain licensing conditions. 
These are formally set out in a separate agreement but are 
summarized here.  

1. No Royalties: There are never any royalties due Paul Freeman 
Associates on account of the Agent having been incorporated as a 
part of the customer product in binary form.  

2. Agent Port: The customer is allowed to compile Agent sources 
and link the resulting Agent object files with his operating 
system and to load the result on his platform. The customer then 
is allowed to distribute the Agent binaries as a part of his 
product without restriction.  

3. Licensed Source Distribution: The customer is not allowed to 
distribute Agent source code in any form except as provided in 
the separate licensing agreement.  

9  REFERENCES 

We drew from the following publications in preparing the Agent. 
They may be of interest to the reader.  

1. Marshall T. Rose and Keith McCloghrie, "Structure and 
Identification of Management Information for TCP/IP based 
Internets," RFC 1155, May 1990. The SMI description.  

2. Keith McCloghrie and Marshall T. Rose, "Management Information 
Base Network Management of TCP/IP based Internets," RFC 1156, May 
1990. The MIB-I description.  

3. Jeffrey D. Case, Mark S. Fedor, Martin L. Schoffstall, and 
James R. Davin, "A Simple Network Management Protocol (SNMP)," RFC 
1157, May 1990. The rules of the SNMP scheme.  

4. Marshall T. Rose, editor, "Management Information Base Network 
Management of TCP/IP based internets: MIB-II," RFC 1158, May 
1990. The first MIB-II description.  

5. Marshall T. Rose and Keith McCloghrie, editors, "Concise MIB 
Definitions," RFC 1212, March 1991.  

6. Keith McCloghrie and Marshall T. Rose, "Management Information 
Base Network Management of TCP/IP based Internets: MIB-II," RFC 
1213, March 1991. The memorandum defines the second version of 
the Management Information Base (MIB-II) and supersedes RFC 
1158.  

7. James M. Galvin, Keith McCloghrie, and James R. Davin, "SNMP 
Security Protocols," RFC 1352, July 1992.  

8. Marshall T. Rose, "The Simple Book: An Introduction to 
Management of TCP/IP-based internets," Prentice-Hall, 1991. The 
commentary on the RFCs and the best introduction to SNMP. Rose 
has strong opinions and doesn't mind sharing them, so the book 
can be entertaining, as well.  

9. Douglas E. Comer and David L. Stevens, "Internetworking with 
TCP/IP," 2 volumes, Prentice-Hall, 1991.