SNMP Subagent Programmer s Guide

Transcription

1 Networking and Data Communications Library SNMP Subagent Programmer s Guide Abstract This manual explains how to use the NonStop SNMP (Simple Network Management Protocol) Subagent Toolkit. The Toolkit helps C programmers generate subagents that make NonStop resources manageable by SNMP managers, which are remote SNMPcompliant workstation-based applications. Product Version Subagent Toolkit D21 Supported Releases This manual supports D20.05 and D30.02 and all subsequent releases until otherwise indicated in a new edition. Part Number Edition Published Release ID Second September 1995 D20.06

2 Document History Edition Part Number Product Version Earliest Supported Release Published First Subagent Toolkit D20 D20.05 May 1995 Second Subagent Toolkit D21 D20.05/D30.02 September 1995 New editions incorporate any updates since the previous edition. A plus sign (+) after a release ID indicates that this manual describes function added to the base release, either by an interim product modification (IPM) or by a new product version on a.99 site update tape (SUT). Ordering Information For manual ordering information: domestic U.S. customers, call ; international customers, contact your local sales representative. Document Disclaimer Information contained in a manual is subject to change without notice. Please check with your authorized Tandem representative to make sure you have the most recent information. Export Statement Export of the information contained in this manual may require authorization from the U.S. Department of Commerce. Examples Examples and sample programs are for illustration only and may not be suited for your particular purpose. Tandem does not warrant, guarantee, or make any representations regarding the use or the results of the use of any examples or sample programs in any documentation. You should verify the applicability of any example or sample program before placing the software into productive use. U.S. Government Customers FOR U.S. GOVERNMENT CUSTOMERS REGARDING THIS DOCUMENTATION AND THE ASSOCIATED SOFTWARE: These notices shall be marked on any reproduction of this data, in whole or in part. NOTICE: Notwithstanding any other lease or license that may pertain to, or accompany the delivery of, this computer software, the rights of the Government regarding its use, reproduction and disclosure are as set forth in Section of the FARS Computer Software Restricted Rights clause. RESTRICTED RIGHTS NOTICE: Use, duplication, or disclosure by the Government is subject to the restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS RESTRICTED RIGHTS LEGEND: Use, duplication or disclosure by the Government is subject to restrictions as set forth in paragraphþ(b)(3)(b) of the rights in Technical Data and Computer Software clause in DAR (a). This computer software is submitted with restricted rights. Use, duplication or disclosure is subject to the restrictions as set forth in NASA FARþSUP 18-52þ (Aprilþ1985) Commercial Computer Software Restricted Rights (Aprilþ1985). If the contract contains the Clause at 18-52þ Rights in Data General then the Alternate III clause applies. U.S. Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract. Unpublished All rights reserved under the Copyright Laws of the United States.

3 New and Changed Information Most of the new information in this second edition of the SNMP Subagent Programmer s Guide describes Subagent Toolkit implementation of the following features, supported by the D21 (July 24, 1995) and later versions of the Toolkit and the D22 NonStop agent IPM AAD (July 18, 1995) and later versions of the NonStop agent: Enhanced subagent security. Subagents can use the management function mgmt_security() to control the type of operation and the Management Information Base (MIB) objects that can be operated on. This function lets subagents use manager station community strings and IP addresses as authentication criteria. Enhanced Set operation error checking. Subagents can encode Set access functions that return failure information. Change bars are used within sections to highlight the following information, new in this edition: About This Manual Section 1 Section 2 Section 4 Recommendations for additional related reading are added. A discussion of the roles of the NonStop agent and subagents in authenticating SNMP requests is added. The System Time Manager sample subagent is revised to demonstrate Set access function error handling. A new sample subagent, Security Checker, is added to demonstrate the use of mgmt_security(). Minor changes are made to clarify how the following functions work: mgmt_new_instance(), mgmt_del_instance(), mgmt_poll(), mgmt_term_env(), mgmt_trap(), and access functions. A description of the new management function, mgmt_security(), is added. SNMP Subagent Programmer s Guide iii

4 New and Changed Information iv SNMP Subagent Programmer s Guide

5 Contents New and Changed Information About This Manual xi Notation Conventions 1. Introduction to Subagent Programming NonStop SNMP Support 1-1 Toolkit Components 1-2 Division of Responsibility 1-2 Manager Communication 1-2 Object Management 1-2 Security 1-3 Subagent Development Cycle 1-4 Identifying Why You Need SNMP 1-4 Defining Objects 1-5 Writing the MIB Definition 1-5 Designing the Subagent 1-5 Coding Subagent Logic 1-6 Refining the MIB 1-8 Building the Subagent 1-9 Installing Subagents 1-11 PEER Subagent Portability 1-11 Agent/Subagent Compatibility 1-12 Installing the Toolkit Programming Tutorials Sample Files 2-1 File Names 2-2 Using the Sample Files 2-2 Hello World Program 2-3 Functions 2-4 MIB 2-4 Logic 2-9 Nowaited Hello World Program 2-17 Functions 2-17 MIB 2-17 Logic 2-17 xv iii SNMP Subagent Programmer s Guide v

6 3. Writing and Compiling MIBs Contents Fault-Tolerant Hello World Program 2-25 Functions 2-25 MIB 2-26 Logic 2-26 Static Directory Program 2-32 Functions 2-32 MIB 2-32 Logic 2-34 Dynamic Directory Program 2-43 Functions 2-43 MIB 2-44 Logic 2-45 Indexed Trap Generator 2-55 Functions 2-55 MIB 2-56 Logic 2-59 System Time Manager 2-68 Functions 2-68 MIB 2-69 Logic 2-70 Security Checker 2-78 Functions 2-79 MIB 2-79 Logic Writing and Compiling MIBs Encoding MIBs 3-1 GDMOC Comments and Preprocessor Directives 3-2 SNMP Type Definitions 3-3 Object Name Definitions 3-4 Scalar Object Definitions 3-6 Table Definitions 3-11 Trap Definitions 3-16 Isolating Standard Definitions 3-17 Compiling MIBs 3-18 vi SNMP Subagent Programmer s Guide

7 Contents Examples 4. Writing Subagent Logic Header Files 4-1 Toolkit Header Files 4-1 GDMOC Output File 4-2 MIB Variable Declarations 4-2 Management Functions 4-5 mgmt_del_instance() 4-7 mgmt_init_env() 4-9 mgmt_new_instance() 4-11 mgmt_poll() 4-14 mgmt_read_nowait() 4-17 mgmt_security() 4-19 mgmt_term_env() 4-22 mgmt_trap() 4-23 Callback Functions 4-25 When to Use Callback Functions 4-25 MIB Extensions 4-26 Index Argument 4-28 Access Functions 4-29 Locator Functions 4-32 Next Functions Creating Executable Subagents MIB Compilation 5-1 Subagent Compilation 5-1 Binding 5-2 Acceleration 5-5 Using TACL 5-5 Index Index-1 Examples Example 2-1. Hello World MIB Definition 2-5 Example 2-2. Hello World Source Code 2-15 Example 2-3. Nowaited Hello World Source Code 2-22 Example 2-4. Fault-Tolerant Hello World Program 2-29 Example 2-5. Static Directory MIB Definition 2-33 Example 2-6. Static Directory Main Program 2-36 Example 2-7. Static Directory Include File dirh 2-39 Example 2-8. Static Directory Include File dirc 2-40 SNMP Subagent Programmer s Guide vii

8 Figures Contents Examples (continued) Example 2-9. Dynamic Directory MIB Definition 2-44 Example Dynamic Directory Main Program and Next and Locator Functions 2-48 Example Dynamic Directory Include File dirc 2-52 Example Indexed Trap Generator MIB Definition 2-56 Example Indexed Trap Generator Main Program and Next and Locator Functions 2-63 Example System Time Manager MIB Definition 2-69 Example System Time Manager Main Program 2-74 Example System Time Manager Access Functions 2-76 Example Security Checker MIB Definition 2-80 Example Security Checker Main Program 2-85 Example Security Checker Authentication Function 2-90 Example Security Checker Access Functions 2-91 Example 5-1. Example of Run-Time Library Trace Records 5-4 Example 5-2. TACL Routine for Static Directory 5-6 Figures Figure 1-1. NonStop SNMP Components 1-1 Figure 1-2. Division of Responsibility 1-3 Figure 1-3. Subagent Development Cycle 1-4 Figure 1-4. Subagent Styles 1-6 Figure 1-5. Components of Subagent Logic 1-7 Figure 1-6. Building a Subagent 1-10 Figure 2-1. Logic Flow for Hello World 2-11 Figure 2-2. Logic Flow for Nowaited Hello World 2-18 Figure 2-3. Logic Flow for Fault-Tolerant Hello World 2-27 Figure 2-4. Logic Flow for Static Directory 2-35 Figure 2-5. Logic Flow for Dynamic Directory 2-46 Figure 2-6. Logic Flow for Indexed Trap Generator 2-60 Figure 2-7. Logic Flow for System Time Manager 2-71 Figure 2-8. Logic Flow for Security Checker 2-82 Figure 4-1. Relationships Among Management Functions 4-6 viii SNMP Subagent Programmer s Guide

9 Contents Tables Table 2-1. Sample Program Files 2-2 Table 3-1. Relationship Between MIB Extensions and GDMOC Behavior 3-19 Table 4-1. Mapping SNMP Data Types to C Data Types 4-3 Table 4-2. Management Functions 4-5 Table 4-3. Callback Functions 4-25 Table 4-4. When to Use Callback Functions 4-26 SNMP Subagent Programmer s Guide ix

10 Contents x SNMP Subagent Programmer s Guide

11 About This Manual The NonStop Simple Network Management Protocol (SNMP) agent supports subagents that make hardware and software resources on NonStop systems manageable by SNMP managers. SNMP managers are SNMP-compliant applications used to manage resources on systems supplied by various vendors. This manual describes how to use the NonStop SNMP Subagent Toolkit to create subagents. The subagents run on NonStop systems and handle manager requests forwarded by the NonStop agent for NonStop resources for which the subagent is responsible. Audience This manual is for C programmers who want to instrument applications that run on NonStop systems for SNMP management. Programmers who have used the PEER Networks, Inc., Object Development Environment (ODE) will find most of the information in this manual very familiar. The Toolkit was developed by porting components of the ODE to the NonStop environment, with minimal impact on the application programming interface used by subagents. Prerequisites Effective use of this manual and the Toolkit requires: A working knowledge of the C programming language General familiarity with the NonStop agent, especially its startup and configuration options Good familiarity with basic SNMP terminology and concepts, especially the information in three RFCs: RFC 1157, A Simple Network Management Protocol (SNMP) RFC 1212, Concise MIB Definitions RFC 1215, A Convention for Defining Traps for Use with the SNMP See Related Reading, later in this section, for information on obtaining these RFCs. Understanding of how to configure a management station and its resident managers to communicate with the NonStop agent and subagents it supports. Purpose This manual provides information that helps subagent programmers perform the following tasks: SNMP Subagent Programmer s Guide xi

12 Organization About This Manual Write Management Information Base (MIB) definitions describing resources to be managed. Compile MIB definitions using GDMOC, the MIB compiler provided with the Toolkit, to create a subagent header file containing run-time access logic. Write C program modules that use Toolkit header files and run-time library functions for handling SNMP operations. Compile header files and subagent logic, then bind the compiler output with the Toolkit s run-time library to create executable subagents. Organization This manual is organized into five sections: Section 1, Introduction to Subagent Programming, describes how the Toolkit components fit into the subagent development and usage cycles. Section 2, Programming Tutorials, describes the eight sample subagents provided with the Toolkit. Section 3, Writing and Compiling MIBs, presents the syntax conventions for encoding MIBs and running GDMOC, the MIB compiler. Section 4, Writing Subagent Logic, describes the elements to encode in C program logic to implement SNMP instrumentation. Section 5, Creating Executable Subagents, provides instructions for compiling, binding, and accelerating subagents. Related Reading This manual has two companion manuals: SNMP Configuration and Management Manual, which describes how to install and configure the NonStop agent and interpret information generated by subagents Tandem provides. This manual also contains a glossary that provides definitions to orient those new to either SNMP or NonStop systems. SCF Reference Manual for the SNMP Agent, which describes how to use the Subsystem Control Facility (SCF) to configure the NonStop agent The following additional Tandem manuals may be useful while you are writing and building subagents from C language modules: C Programmer s Guide and Guardian C Library Calls Reference Manual, which document the NonStop C language, compiler, and run-time library Binder Manual, which documents the Binder utility, used to link object files into executable files Accelerator Manual, which documents the Accelerator utility available for optimizing applications that run on TNS/R systems xii SNMP Subagent Programmer s Guide

13 About This Manual Your Comments Invited TACL Reference Manual and TACL Programming Guide, which document how to use the commands, built-in functions, and built-in variables provided by the Tandem Advanced Command Language (TACL) Guardian Procedure Calls Reference Manual and Guardian Programmer s Guide, which describe Tandem NonStop Kernel procedure calls and how to make them from a C language program. You can obtain information about the general topic of SNMP at libraries and book stores; many excellent and up-to-date books are available. The Internet is also a good resource for current SNMP information. RFCs are public-domain documents that you can obtain from InfoWay or from one of the following sources: DDN Network Information Center Park Meadow Drive, Suite 200 Chantilly, VA USA phone: nic@nic.ddn.mil The Internet. If your site has IP-connectivity to the Internet community, you can use anonymous FTP to the host nic.ddn.mil (residing at ) and retrieve files from the directory rfc/. Electronic mail. Send an message to: mail-server@nisc.sri.com and in the subject field indicate the RFC number: Subject: SEND rfcs/rfc1130.txt For information about manager stations and managers, refer to the documentation provided by their vendors. Your Comments Invited After using this manual, please take a moment to send us your comments. You can do this by returning a Reader Comment Card or by sending an Internet mail message. A Reader Comment Card is located at the back of printed manuals and as a separate file on the Tandem CD Read disc. You can either FAX or mail the card to us. The FAX number and mailing address are provided on the card. Also provided on the Reader Comment Card is an Internet mail address. When you send an Internet mail message to us, we immediately acknowledge receipt of your message. A detailed response to your message is sent as soon as possible. Be sure to include your name, company name, address, and phone number in your message. If your comments are specific to a particular manual, also include the part number and title of the manual. Many of the improvements you see in Tandem manuals are a result of suggestions from our customers. Please take this opportunity to help us improve future manuals. SNMP Subagent Programmer s Guide xiii

14 Your Comments Invited About This Manual xiv SNMP Subagent Programmer s Guide

15 Notation Conventions General Syntax Notation The following list summarizes the notation conventions for syntax presentation in this manual. Nonitalic Letters. Nonitalic letters indicate keywords and reserved words. For example, GDMOC, the MIB compiler, requires that some constructs be encoded in uppercase and some constructs in lowercase or mixed case: INTEGER is uppercase, but Counter is mixed case. Management and callback functions are also case-sensitive. For example: rc = mgmt_del_instance (mgmt-env, instance-handle); lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: instance-handle [ ] Brackets. Brackets enclose optional syntax items. For example: [trap-definitions] Braces. A group of items enclosed in braces is a list from which you are required to choose one item. For example: ACCESS read-only read-write write-only not-accessible Vertical Line. A vertical line separates alternatives in a list. For example: (SIZE range) empty Ellipsis. An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item. For example: [, MIB-object-name...] An ellipsis within a source code example indicates that some information has been omitted. For example: int main(int argc, char **argv)... SNMP Subagent Programmer s Guide xv

16 Change Bar Notation Notation Conventions <--n. In a source code example, an arrow accompanied by a number identifies code that is discussed in text, immediately preceding the example, that is accompanied by the same number. For example, the following code identifier, 5, indicates that an explanation for the code it accompanies appears earlier, as shown: if ((mgmt_env = mgmt_init_env(argv[1], <-- 5 (ObjId_t *) &GI_hello, "Hello World Example with security", (Octets_t *) NULL, (void_function) NULL)) == NULL) 5. The management environment is initialized. Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be entered as shown. For example: MIB-name DEFINITIONS ::= BEGIN Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must enter as shown. For example: object-descriptor OBJECT IDENTIFIER ::= "object-name"" Item Spacing. Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis, comma, or brace. For example: [VARIABLES "" MIB-object-name [, MIB-object-name...] "" Change Bar Notation Change bars are used to indicate substantive changes in this edition to material in the preceding edition. Change bars are vertical rules placed in the right margin of changed portions of text, figures, tables, and so on. They highlight new or revised information. For example: SNMP Configuration and Management Manual, which describes how to install and configure the NonStop agent and interpret information generated by subagents Tandem provides. This manual also contains a glossary that provides definitions to orient those new to either SNMP or NonStop systems. xvi SNMP Subagent Programmer s Guide

17 1 Introduction to Subagent Programming Simple Network Management Protocol (SNMP) lets workstation-based applications manage resources that reside on remote devices supplied by different vendors. These SNMP-compliant applications, known as managers, communicate with SNMP agents on the remote devices. An agent is an SNMP-compliant software product that accepts queries and change requests from managers about resources to which the agent has access. NonStop SNMP Support Tandem provides an SNMP agent for its NonStop systems. As Figure 1-1 illustrates, the NonStop agent interacts with subagents that reside on the same or remote NonStop systems. Each subagent handles manager requests forwarded by the NonStop agent for hardware or software resources the subagent is responsible for. A manager can send requests to retrieve or change information about a subagent s resources when the Management Information Base (MIB) describing those resources has been compiled and installed on the manager station. Figure 1-1. NonStop SNMP Components One NonStop System Another NonStop System Subagent-1 Subagent-2 NonStop Agent Expand Subagent-3 TCP/IP Manager Station Subagent MIB Definitions 101 SNMP Subagent Programmer s Guide

18 Toolkit Components Introduction to Subagent Programming Tandem offers several subagents, such as the EMS Trap Subagent and the NonStop NET/MASTER Trap Subagent. To facilitate the creation of subagents by customers who want to instrument their own SNMP management capabilities, Tandem provides the NonStop SNMP Subagent Toolkit. The Toolkit expedites the development of subagents written in the C programming language that execute on and manage resources of a Tandem NonStop system. Toolkit Components The Subagent Toolkit includes these components: A MIB compiler, which compiles the subagent MIB definition into a C header file containing definitions needed at run time. Header files, which define data structures and logic needed at run time. Two run-time libraries: one that generates trace messages for use during debugging and one for production use. The MIB compiler output and header files contain definitions that let subagents access the run-time library. Sample subagent files, which illustrate how to encode MIBs and subagent logic to handle certain SNMP operations. How these components fit into the subagent development and usage cycles is the topic of the remainder of this section. Division of Responsibility Figure 1-2 illustrates the division of responsibility between subagents developed using the Toolkit and other SNMP components. Manager Communication The NonStop agent and the run-time library handle all the details of manager-subagent message transfer. Therefore subagents developed using the Toolkit do not have to encode manager communication logic. The subagent makes a simple call to the runtime library provided with the Toolkit whenever it needs to invoke communication with managers. The NonStop agent handles interactions with managers, and the run-time library handles subagent-agent communications. Object Management The subagent is responsible for manipulating the objects that it makes visible to managers. The subagent returns values for objects when Get requests arrive from managers. The subagent changes object values when Set requests arrive. When events that impact object management occur, the subagent can send an unsolicited message, known as a trap, to the manager. Every subagent has a corresponding MIB. Objects the subagent grants manager access to are defined in the MIB. The Toolkit s MIB compiler uses the MIB definition to generate code that both the subagent and the run-time library use. The manager uses the MIB definition to identify objects to which it has access SNMP Subagent Programmer s Guide

19 Introduction to Subagent Programming Division of Responsibility Figure 1-2. Division of Responsibility Managed Resources Object Management MIB Definition Subagent Run-Time Library Manager Communications Security NonStop Agent Manager Station 102 Security Access to subagent MIB objects is controlled by both the NonStop agent and the subagent: The NonStop agent passes requests to subagents when the request is from a manager station configured in the agent s authentication table. The subagent logic and MIB object attributes determine whether managers can access specific MIB objects and the operations they can perform on them. More information about security can be found later in this section, under Installing Subagents. SNMP Subagent Programmer s Guide

20 Subagent Development Cycle Introduction to Subagent Programming Subagent Development Cycle The main steps in subagent development, summarized in Figure 1-3, are described next. Figure 1-3. Subagent Development Cycle Identify Why You Need SNMP Deliberation Define Object Attributes MIB Definition Refine MIB Definition Write MIB Definition Design Subagent Subagent Logic Definition Code Subagent Build Subagent Creating Executable Subagent 103 Identifying Why You Need SNMP Before you decide to build a subagent, ask yourself such questions as: Which objects would be desirable for a manager to manage? Why? Which objects do I want a manager to manage? How? Is an existing application already instrumented to handle the objects? Would it be an advantage if the application could use SNMP? Is it feasible to manage the objects? How hard are they to model in a subagent? Would somebody pay me to know this information? SNMP Subagent Programmer s Guide

21 Introduction to Subagent Programming Subagent Development Cycle Defining Objects If you believe that it is feasible, possible, and practical to build a subagent, you need to make some decisions about each object you want to make accessible to a manager. Determine the objects to make accessible and identify how each object is to be viewed from a manager s perspective: Which objects need to be modeled as tables? As scalar variables? Should I let managers retrieve object values? Change them? Which ones? Do I need to generate traps? What should they look like? How should the objects be formatted? Writing the MIB Definition The next step is to encode your object decisions in a formal MIB definition. The Toolkit supports the standard concise MIB encoding conventions for this purpose. For example, the following MIB definition is for a MIB object used by one of the sample subagents discussed in Section 2, Programming Tutorials : helloprintcnt OBJECT-TYPE SYNTAX Counter ACCESS read-only STATUS mandatory DESCRIPTION "A running count of the number of times the hellooutputtext message has been printed to the console." ::= hello 3 This object, named helloprintcnt, is a counter that a manager can only perform SNMP Get operations for, because it has read-only access. The last line of the definition identifies where in the name hierarchy this object resides. Refer to Section 3, Writing and Compiling MIBs, for information about the meaning of and encoding conventions for MIBs and their objects. Section 3, Writing and Compiling MIBs, also describes how to register your MIB definition with the Internet Assigned Numbers Authority (IANA). Designing the Subagent Some subagents are implemented as stand-alone processes, and others are integrated into new or existing applications. Figure 1-4 illustrates some of the major alternatives. Which style to adopt for a particular subagent is influenced by many factors, including ease of implementation, scope of control, and packaging. SNMP Subagent Programmer s Guide

22 Subagent Development Cycle Introduction to Subagent Programming Figure 1-4. Subagent Styles Application Application Subagent Subagent Application Subagent Stand-Alone Subagent Collaborative Subagent Integrated Subagent 104 Stand-alone subagents Collaborative subagents Integrated subagents For more information about the subagents that Tandem provides, refer to the SNMP Configuration and Management Manual. Coding Subagent Logic These subagents rely entirely on their own resources for accessing and managing MIB object values. Most of the example subagents described in Section 2, Programming Tutorials, are stand-alone subagents. These subagents use the services of other applications to access and maintain data. For example, the MIB-II Subagent that Tandem offers uses the Subsystem Programmatic Interface (SPI) to retrieve information from processes managing TCP/IP resources. Some of the sample subagents described in Section 2 use Guardian procedure calls to retrieve or alter MIB values. These subagents reside within an application. The EMS Trap Subagent that Tandem offers is an example of such a subagent. The EMS Trap Subagent is implemented within EMS (Event Management Service) as a special kind of printing distributor. The subagent logic works together with the run-time library to handle SNMP requests and to send traps. Figure 1-5 illustrates where in the subagent C source code you embed declarations and functions used by the run-time library SNMP Subagent Programmer s Guide

23 Introduction to Subagent Programming Subagent Development Cycle Figure 1-5. Components of Subagent Logic #include toolkit-header-files... global-mib-variable-declarations... #include MIB-compiler-output-file... main() management-function-calls [ callback-function-definitions ] 105 Toolkit header files MIB variable declarations MIB compiler output file Management function calls Callback functions Several header files contain declarations, definitions, and other logic needed by the run-time library. Some variables for passing MIB object values between your subagent and the run-time library need to be declared globally. The file containing the MIB compiler output is included after MIB variables are declared because it contains references to those variables. A subagent uses management function calls to initiate communication with the NonStop agent, to process manager requests, and to send traps. When you want to provide your own logic for the runtime library to use, you write what are known as callback functions. These optional functions are used when you want to optimize certain aspects of MIB value handling or when you need to write your own logic for Get and Set operations instead of relying on the logic generated by the Toolkit. SNMP Subagent Programmer s Guide

24 Subagent Development Cycle Introduction to Subagent Programming This collection of functions offers a range of development strategies. Using only management function calls to implement a subagent is the easiest and fastest approach, because all the routines for MIB object handling are generated for you. When optimizing your subagent warrants additional development time, you can write some callback functions. And when more complete control over access logic is warranted, you can write additional callback functions. Refer to Section 4, Writing Subagent Logic, for more information on writing subagent logic. Refining the MIB After you have decided how you want to represent MIB object values in your subagent and whether you want to use callback functions, you add extensions to your MIB definition. Extensions, constructs that are not part of the concise MIB constructs, identify where in your subagent logic the values for MIB objects are maintained. For example, the following MIB definition for an object named hellooutputtext contains an extension, highlighted in bold type, that indicates to the run-time library that the value for the object is maintained in a global variable named hellotext: hellooutputtext OBJECT-TYPE SYNTAX DisplayString (SIZE (0..255)) ACCESS read-write STATUS mandatory DESCRIPTION "The textual message that is displayed to stdout by the Hello World program" ::= hello 1 EXTEND OBJECT-TYPE hellooutputtext WITH C_VARIABLE hellotext IN C SNMP Subagent Programmer s Guide

25 Introduction to Subagent Programming Subagent Development Cycle Building the Subagent Figure 1-6 illustrates the steps and products used to convert MIB definitions and subagent logic into an executable subagent: MIB compilation Subagent compilation Binding The MIB definition is compiled by GDMOC, the Toolkit s MIB compiler. The output file is a header file containing data structure definitions and access logic that the run-time library needs. The subagent source code, including the compiled MIB definition file and any other required header files, is compiled by the C compiler. Run-time library logic is bound into the subagent object code. Two run-time libraries are available: PEERLBTO and PEERLIBO. PEERLBTO is for use during subagent development; it provides tracing that describes subagent and agent actions during subagent execution. PEERLBTO is not for use with production code; for production code, use PEERLIBO. Refer to Section 3, Writing and Compiling MIBs, for how to use GDMOC. Refer to Section 5, Creating Executable Subagents, for guidelines on compilation and binding. SNMP Subagent Programmer s Guide

26 Subagent Development Cycle Introduction to Subagent Programming Figure 1-6. Building a Subagent Start #include Toolkit Header Files MIB Definition GDMOC MIB Compilation Toolkit Header Files Compiled MIB Definition #include Compiled MIB Definition #include Toolkit C Library Header Files Header Files #include Header Files C Subagent Source Code C Compiler Subagent Compilation Subagent Object File Toolkit Library Files Binder Binding Executable Subagent SNMP Subagent Programmer s Guide

27 Introduction to Subagent Programming PEER Subagent Portability Installing Subagents After a subagent has been debugged and bound with PEERLIBO, it is ready for production use. Simply install the executable subagent file on the production NonStop system and compile and install the MIB definition on manager stations that will be using your subagent. Before a manager station can access objects in your subagent s MIB, it needs to be configured to meet security criteria imposed by the NonStop agent and your subagent: The community name and IP address associated with the manager station must appear in one of the NonStop agent s authentication table entries. The NonStop agent passes manager requests to your subagent only if the manager station from which they arrive has an entry in the authentication table. Refer to the SNMP Configuration and Management Manual for information on how to configure authentication table entries. By default, manager requests forwarded to subagents from the NonStop agent are processed in accordance with the access attributes of individual MIB objects. Managers can perform Get and GetNext operations on read-only MIB objects and Get, GetNext, and Set operations on read-write objects. However, you can encode your subagent to respond to a request to access a MIB object, independently of its access attributes, only if it contains a particular password and originates from a specific IP address. This option, known as subagent request authentication, requires that the password appear as follows in the manager station community string: agent-community-string::subagent-password The agent community string must appear in one of the NonStop agent s authentication table entries. The agent community string, a double colon, and the subagent password must appear in the manager station s configuration. The agent community string can contain from 0 to 50 printable bytes, and cannot contain successive colons. The total manager station community string can contain 0 to 255 bytes. Also, configure the manager stations so that their timeouts and retries accommodate times when the NonStop agent is handling multiple requests simultaneously. Try setting the timeout value to 5 to 9 seconds and the retry value to 0 or 1. PEER Subagent Portability The developers of the Subagent Toolkit implemented it by porting components of the PEER Network, Inc., Object Development Environment (ODE). You can convert subagents developed using the ODE to run in the NonStop environment by making some changes to the subagent source code: Any operating system differences, such as procedure calls and file system operations, need to be addressed. The management function mgmt_select_mask() is not supported. Instead, you use mgmt_read_nowait() to perform nowaited operations. SNMP Subagent Programmer s Guide

28 Agent/Subagent Compatibility Introduction to Subagent Programming Management function mgmt_poll() for NonStop subagents contains three, not two, arguments. The third argument, used during nowaited operations, indicates the size of the message from the NonStop agent; the value of this argument is returned by Guardian procedure AWAITIO[X]. The management function mgmt_init_env() passes a NonStop agent process name instead of an agent socket address. The header file named tdmporth must be included globally before any other Toolkit header files. C compiler pragmas may need to change. Agent/Subagent Compatibility Subagents developed with the first release (D20 version) of the Toolkit interoperate with D22 or later versions of the NonStop agent. Subagents developed with the second release (D21 version, July 24, 1995) of the Toolkit interoperate with D22 NonStop agent IPM AAD (July 28, 1995) or later versions of the NonStop agent. Installing the Toolkit When you use the Install utility, the Subagent Toolkit files are installed to two subvolumes: $<dsv>.zsnmpsdk $<dsv>.zsnmpdkx MIB compiler (GDMOC) Run-time libraries (PEERLBTO and PEERLIBO) Run-time header files Sample subagent files The sample files include a TACL routine for each of the sample subagents. These routines automate the creation of executable subagents from sample source code. The TACL routines refer to file names as follows: Names of sample files are unqualified. Sample files are expected to be in your current subvolume. GDMOC, the run-time libraries, and the header files are expected to be in subvolume ZSNMPSDK on the same volume as the sample files. If your files are in different locations, change the file names in the TACL routines before invoking them SNMP Subagent Programmer s Guide

29 2 Programming Tutorials This section discusses the eight sample subagents that are packaged with the NonStop SNMP Subagent Toolkit: Hello World sample program. This simple subagent displays a message whenever it receives a request from an SNMP manager. It also generates a trap when an SNMP manager alters the value of one of its MIB objects. Nowaited Hello World program. This subagent enhances the Hello World program to perform other activities while it awaits input from an SNMP manager. Fault-Tolerant Hello World program. This subagent enhances the Nowaited Hello World program to interact with several NonStop agents. Static Directory program. This subagent illustrates how to manage a tabular MIB object whose entries never change. Dynamic Directory program. This subagent enhances the Static Directory program to manage tables whose entries change over time. Indexed Trap Generator program. This subagent demonstrates how to use indexed MIB objects in traps and manage tables with multivalued indexes. System Time Manager. This subagent uses its own access functions to perform Get and Set operations on the system time. Security Checker. This subagent enhances the Nowaited Hello World program to authenticate manager requests before processing them. Sample Files For each sample subagent, the following files can be found in the Install subvolume: C source code MIB definition TACL routine The subagent source code. Source code file names end in c. Refer to Section 4, Writing Subagent Logic, for reference information about encoding subagent logic in C language programs. The input file for GDMOC, the MIB compiler. MIB definitions file names end in smi. Refer to Section 3, Writing and Compiling MIBs, for reference information about encoding and compiling MIBs. A routine that creates an executable subagent from the subagent source code and MIB definition. TACL routine names end in m. Refer to Section 5, Creating Executable Subagents, for a description of the operations the routines perform. SNMP Subagent Programmer s Guide

30 Sample Files Programming Tutorials File Names Table 2-1 identifies the files associated with each sample program. Table 2-1. Sample Program Files Sample Program File Description File Name Hello World C source code MIB definition TACL routine helloc hellosmi hellom Nowaited Hello World Fault-Tolerant Hello World Static Directory Dynamic Directory Indexed Trap Generator System Time Manager Security Checker Using the Sample Files C source code MIB definition TACL routine C source code MIB definition TACL routine C source code MIB definition TACL routine C source code MIB definition TACL routine C source code MIB definition TACL routine C source code MIB definition TACL routine C source code MIB definition TACL routine hellonnwc hellosmi hellonwm helloftc hellosmi helloftm fixedlsc dirc dirh fxdlssmi fixedlsm dynamlsc dirc dirh dynamsmi dynamlsm tbltrapc tbltrsmi tbltrapm systimec accessfc systmsmi systimem helloscc authentc securitc hloscsmi helloscm The easiest way to get started with the Subagent Toolkit is to create executable subagents from the sample files and interact with them from an SNMP manager. The steps in this process are simple: 1. Log onto the NonStop system on which the sample files are installed: LOGON SNMP.USER SNMP Subagent Programmer s Guide

31 Programming Tutorials Hello World Program 2. Make the subvolume containing the sample files your current subvolume: VOLUME [$volume-name.]zsnmpdkx The TACL routines expect the sample files to reside in the current subvolume and other Toolkit components to reside in ZSNMPSDK on the same volume. 3. Start the TACL routine for the sample subagent you want to build. The TACL routines convert the source files into executable subagents by invoking the MIB compiler, the C compiler, and the Binder utility. To make the Hello World program executable, enter: RUN HELLOM 4. Install the subagent s MIB on a manager station, editing the MIB definition file as required by the manager you are using. 5. Have somebody who is a member of the super user group start the NonStop agent if it is not already running: RUN SNMPAGT /NAME $ZSNMP, NOWAIT/ WARM For complete information on invocation conditions and options for the NonStop agent, refer to the SNMP Configuration and Management Manual. 6. Configure the NonStop agent authentication table and the manager station community name as described in Section 1, under Installing Subagents. 7. Start the subagent, naming the executable subagent file and the agent process in the invocation line. The TACL routine that builds the executable subagent for the Hello World program names the executable subagent HELLO. The agent process name is usually $ZSNMP: RUN HELLO /NAME $HELLO/ $ZSNMP The descriptions for each sample subagent include instructions for starting the subagent. 8. Communicate with the subagent from the manager station on which the MIB definition for the sample subagent has been compiled. Refer to subsections later in this section to determine the functions provided by each sample subagent. 9. To stop the executing subagent, use the TACL STOP command, identifying the name of the subagent process: STOP $HELLO After familiarizing yourself with the behavior of the sample subagents, try modifying their MIB definitions and logic to change how they work. Hello World Program This subagent displays a message whenever it receives a Get or Set request from an SNMP manager. SNMP Subagent Programmer s Guide

32 Hello World Program Programming Tutorials These files are related to Hello World: Functions MIB helloc hellosmi hellom C source code MIB definition TACL routine Invoke Hello World by specifying the executable subagent name and the NonStop agent process name: RUN HELLO /NAME $HELLO/ $ZSNMP The Hello World subagent is idle until it receives a request from an SNMP manager. When it receives any request, it displays a message, initially Hello World. The subagent supports the following manager requests: Get and Set operations on the message displayed. Initially Hello World, the message is represented by a MIB object named hellooutputtext. The manager can change the message with a Set request. Get and Set operations on a MIB object named helloprintfreq. When a manager changes the value of helloprintfreq, the subagent sends a trap to the manager. The trap, defined by a MIB object named hellofreqchange, contains the new value of helloprintfreq. Although the manager can change the value of helloprintfreq with a Set request, this action has no effect on the frequency with which the value of hellooutputtext is printed. The next sample subagent, Nowaited Hello World, fixes this defect. Get operations on a MIB object named helloprintcnt. This object is a count of the number of times the subagent has displayed any message. The first step in making a program manageable by an SNMP manager is to identify MIB objects: the information to be accessed by a manager and any trap messages to send to the manager. Each object is encoded in a MIB definition, using an extended version of the standard concise MIB conventions. Refer to Section 3, Writing and Compiling MIBs, for complete information on MIB definition. The MIB definition shown in Example 2-1 describes the information and the trap that Hello World makes visible to SNMP managers: hellooutputtext The message displayed SNMP Subagent Programmer s Guide

33 Programming Tutorials Hello World Program helloprintfreq helloprintcnt hellofreqchange A value that can be retrieved and changed but has no effect in this subagent on the frequency with which hellooutputtext is displayed The number of times the message has been displayed The trap that announces a new value for helloprintfreq SNMP Subagent Programmer s Guide

34 Hello World Program Programming Tutorials Example 2-1. Hello World MIB Definition (page 1 of 2) #include "typessmi" HELLO-WORLD DEFINITIONS ::= BEGIN IMPORTS Counter FROM RFC1155-SMI OBJECT-TYPE FROM RFC-1212 DisplayString FROM RFC1213-MIB TRAP-TYPE FROM RFC1215; private OBJECT IDENTIFIER ::= iso(1) org(3) dod(6) internet(1) 4 enterprises OBJECT IDENTIFIER ::= private 1 peer OBJECT IDENTIFIER ::= enterprises Within the 'peer' arc, entire subtrees are dedicated to the following peer-products OBJECT IDENTIFIER ::= peer 1 peer-demos OBJECT IDENTIFIER ::= peer 2 hello OBJECT IDENTIFIER ::= peer-demos 1 hellooutputtext OBJECT-TYPE SYNTAX DisplayString (SIZE (0..255)) ACCESS read-write STATUS mandatory DESCRIPTION "The textual message that is displayed to stdout by the Hello World program." ::= hello 1 helloprintfreq OBJECT-TYPE SYNTAX INTEGER (1..120) ACCESS read-write STATUS mandatory DESCRIPTION "The number of seconds between each printing of the text described in the hellooutputtext variable." ::= hello 2 helloprintcnt OBJECT-TYPE SYNTAX Counter ACCESS read-only STATUS mandatory DESCRIPTION "A running count of the number of times the hellooutputtext message has been printed to the console." ::= hello SNMP Subagent Programmer s Guide

35 Programming Tutorials Hello World Program Example 2-1. Hello World MIB Definition (page 2 of 2) END hellofreqchange TRAP-TYPE ENTERPRISE hello VARIABLES helloprintfreq DESCRIPTION "A hellofreqchange trap signifies that the sending hello world entity has had its 'helloprintfreq' variable modified." ::= 0 EXTEND OBJECT-TYPE hellooutputtext WITH C_VARIABLE hellotext IN C EXTEND OBJECT-TYPE helloprintfreq WITH C_VARIABLE helloprintfreq IN C EXTEND OBJECT-TYPE helloprintcnt WITH C_VARIABLE helloprintcnt IN C Include Statements The include statement at the beginning of the MIB definition identifies a header file that the MIB compiler, GDMOC, needs to resolve data types. The header file, named typessmi, contains definitions of all the standard SNMP data types. Note that this MIB also contains an IMPORT statement defining standard data types for objects in the MIB. Although GDMOC ignores this statement, obtaining instead the information it needs on types from typessmi, some managers need type definitions such as these before a MIB can be compiled on the manager station. Refer to Installing the MIB, later in this subsection, for more information on MIB definition changes for manager stations. SNMP Subagent Programmer s Guide

36 Hello World Program Programming Tutorials Object Identifiers Object identifiers define the SNMP hierarchy in which the MIB resides. They also identify objects in the MIB. In the case of the Hello World MIB, named hello, the hierarchy looks like this: iso (1) org (3) dod (6) internet (1) private (4) enterprises (1) peer (442) peer-demos (2) hello (1) hellooutputtext (1) helloprintfreq (2) helloprintcnt (3) SNMP conventions require that every MIB and object within it have a unique object identifier whose components start with iso and terminate with the object itself. Each MIB object definition finishes with an identification of the subtree in which the object resides and a unique number. For example, the third object in the hello subtree, helloprintcnt, is identified like this: ::= hello 3 Object Access Another important aspect of MIB object definitions is the ACCESS clause. This clause determines how an SNMP manager can interact with an object. In this example, two of the objects (hellooutputtext and helloprintfreq) can be both retrieved and changed; therefore, they are assigned the read-write attribute value. The object named helloprintcnt can be read but not changed by the manager; so it is assigned the readonly attribute value. Traps A trap definition in a MIB identifies the type of trap and MIB objects to include in a trap message. In the case of this MIB, only one MIB object, helloprintfreq, is included in the trap: hellofreqchange TRAP-TYPE ENTERPRISE hello VARIABLES helloprintfreq DESCRIPTION "A hellofreqchange trap signifies that the sending hello world entity has had its 'helloprintfreq' variable modified." ::= SNMP Subagent Programmer s Guide

37 Programming Tutorials Hello World Program MIB objects included in traps must have been defined earlier in the MIB definition. Note that helloprintfreq is defined before the trap, hellofreqchange, in the Hello World MIB. Mapping Objects to Variables The EXTEND OBJECT-TYPE statements at the end of the MIB definition tell the runtime library where in the subagent source code the value for MIB objects is maintained. These statements are examples of MIB constructs known as extensions. Extensions are embedded in your MIB definition to map MIB objects to structures in your subagent that contain the values of the MIB objects. For example, the value of hellooutputtext is maintained in a global C variable named hellotext: EXTEND OBJECT-TYPE hellooutputtext WITH C_VARIABLE hellotext IN C You need to declare variables for MIB object values globally unless you have provided access functions in your subagent. Refer to Section 4, Writing Subagent Logic, for complete information on variable declarations and access functions. As Section 3, Writing and Compiling MIBs, describes, you can segregate extensions from MIB object definitions, as in the Hello World MIB, or you can embed extensions within a MIB object definition. In the latter case, the definition for hellooutputtext would look like this: hellooutputtext OBJECT-TYPE SYNTAX DisplayString (SIZE (0..255)) ACCESS read-write C_VARIABLE hellotext STATUS mandatory DESCRIPTION "The textual message that is displayed to stdout by the Hello World program." ::= hello 1 Isolating the extensions is the recommended approach, because this practice makes installing your MIB on manager stations easier. Installing the MIB Before using a manager to interact with an executing subagent, you compile its MIB definition on any manager station to be used to interact with the subagent. Different managers have different requirements for MIB installation. You have to modify your MIB definition slightly to accommodate a manager s requirements. SNMP Subagent Programmer s Guide