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.
Document History Edition Part Number Product Version Earliest Supported Release Published First 112989 Subagent Toolkit D20 D20.05 May 1995 Second 119728 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).
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.
New and Changed Information iv 119728 —SNMP Subagent Programmer’s Guide
Contents New and Changed Information iii About This Manual xi Notation Conventions xv 1.
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 2-81 3.
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 4-35 5.
Figures Contents Examples (continued) Example 2-9. Example 2-10. Example 2-11. Example 2-12. Example 2-13. Example 2-14. Example 2-15. Example 2-16. Example 2-17. Example 2-18. Example 2-19. Example 2-20. Example 5-1. Example 5-2.
Contents Tables Table 2-1. Table 3-1. Table 4-1. Table 4-2. Table 4-3. Table 4-4.
Contents x 119728 —SNMP Subagent Programmer’s Guide
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.
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.
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.
Your Comments Invited xiv About This Manual 119728 —SNMP Subagent Programmer’s Guide
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.
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.
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.
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.
Introduction to Subagent Programming Division of Responsibility Figure 1-2. Division of Responsibility Managed Resources Object Management Subagent MIB Definition 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.
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.
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.
Subagent Development Cycle Introduction to Subagent Programming Figure 1-4. Subagent Styles Application Application Subagent Subagent Stand-Alone Subagent Subagent Application Collaborative Subagent Integrated Subagent 104 Stand-alone subagents 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.
Introduction to Subagent Programming Subagent Development Cycle Figure 1-5. Components of Subagent Logic #include toolkit-header-files . . . global-MIB-variable-declarations . . . MIB-compiler-output-file #include . . . main() { . . . management-function-calls . . . } [ callback-function-definitions ] 105 Toolkit header files Several header files contain declarations, definitions, and other logic needed by the run-time library.
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.
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 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.
Subagent Development Cycle Introduction to Subagent Programming Figure 1-6.
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.
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.
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.
Sample Files Programming Tutorials File Names Table 2-1 identifies the files associated with each sample program. Table 2-1.
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.
Hello World Program Programming Tutorials These files are related to Hello World: helloc C source code hellosmi MIB definition hellom TACL routine Functions 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.
Programming Tutorials Hello World Program helloPrintFreq A value that can be retrieved and changed but has no effect in this subagent on the frequency with which helloOutputText is displayed helloPrintCnt The number of times the message has been displayed helloFreqChange The trap that announces a new value for helloPrintFreq SNMP Subagent Programmer’s Guide—119728 2- 5
Hello World Program Programming Tutorials Example 2-1.
Programming Tutorials Hello World Program Example 2-1. Hello World MIB Definition (page 2 of 2) helloFreqChange TRAP-TYPE ENTERPRISE hello VARIABLES { helloPrintFreq } DESCRIPTION "A helloFreqChange trap signifies that the sending hello world entity has had its 'helloPrintFreq' variable modified.
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.
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.
Hello World Program Programming Tutorials For example, you need to delete the extensions that map MIB objects to subagent structures.
Programming Tutorials Hello World Program Logic Flow As Figure 2-1 illustrates, Hello World uses several management functions. All but one of these library functions are needed by all subagents: 1. The mgmt_init_env() function establishes communication between the NonStop agent and the subagent. 2. The mgmt_new_instance() function identifies the MIB objects managed by the subagent that can be manipulated by an SNMP manager.
Hello World Program Programming Tutorials Figure 2-1.
Programming Tutorials Hello World Program The variables are assigned data types that correspond to the SYNTAX attribute of the MIB definition for the object. For example, since helloOutputText has a MIB definition with a SYNTAX specification of DisplayString, the helloText variable is assigned the type DisplayString. The header file named smitypeh contains typedef declarations that map these data types to C data types.
Hello World Program Programming Tutorials 9. The mgmt_init_env() function initiates communication with the NonStop agent. If this function fails, the subagent terminates after printing a message. The mgmt_init_env() function expects five arguments, in the following order: • • • • The NonStop agent process name (stored in argv[1]). The object identifier of the subagent, stored in GI_hello. GI_hello is a structure generated by GDMOC. GDMOC names the structure by adding the prefix GI_ to the MIB name.
Programming Tutorials Hello World Program When the NonStop agent receives requests for a subagent from multiple managers, it processes them in turn when mgmt_poll() is called, in the order in which they were received. If mgmt_poll() returns a value of less than 0, connection with the NonStop agent was lost. In this case, the while loop terminates; otherwise, trap processing proceeds. 13.
Hello World Program Programming Tutorials Example 2-2. Hello World Source Code (page 1 of 2) /************************************************************************* * hello.c - demo hello world program to illustrate how an application * which uses global data may be made manageable.
Programming Tutorials Hello World Program Example 2-2. Hello World Source Code (page 2 of 2) if ((mgmt_env = mgmt_init_env(argv[1], <-- 9 (ObjId_t *) &GI_hello, "Hello World Example", (Octets_t *) NULL, (void_function) NULL)) == NULL) { (void) fputs(argv[0], stderr); (void) fputs(": mgmt_init_env failure\n", stderr); return(1); } /* * Let the agent know information what we're responsible for.
Nowaited Hello World Program Programming Tutorials Nowaited Hello World Program This program enhances the Hello World program in two ways: • • Hello World lets you change the value of the MIB object named helloPrintFreq. However, the value of this object has no effect on the frequency at which Hello World prints the message defined by helloOutputText; Hello World prints the message only after processing a request from an SNMP manager.
Programming Tutorials Nowaited Hello World Program Logic Flow Figure 2-2 illustrates how Nowaited Hello World uses management functions and Guardian procedure calls. Figure 2-2.
Nowaited Hello World Program Programming Tutorials The mgmt_read_nowait() management function is used in conjunction with other function and procedure calls as follows: 1. The mgmt_init_env() function establishes communication with the NonStop agent. 2. The mgmt_new_instance() function initiates management of MIB objects. 3. The mgmt_read_nowait() function sets up a nowaited read from the NonStop agent. 4. The AWAITIOX procedure determines whether any external message or file is ready to process. 5.
Programming Tutorials Nowaited Hello World Program Main Control Block This code manages the MIB objects and calls the management functions and Guardian procedures: 3.
Nowaited Hello World Program Programming Tutorials 8. If the AWAITIOX completion code is not set to CCE, an I/O operation was not completed and FILE_GETINFO_ is called to determine what happened. Processing continues based on the value returned in the error parameter: • • If a timeout occurred, the subagent prints the current contents of helloText and starts the wait block again. If any other error condition occurred, the subagent prints a message identifying the error and its associated file number.
Programming Tutorials Nowaited Hello World Program Example 2-3. Nowaited Hello World Source Code (page 1 of 3) #include #include #include #include #include "tdmporth" "machtyph" "syspubh" "smitypeh" "mgmtpubh" #include "mgmtenvh" <-- 1 #include "snmpvblh" nolist nolist nolist nolist nolist nolist /* needed for mgmt_env buffer manipulations */ nolist /* to get SNMP_MSG_MAX (also sourced by hello.
Nowaited Hello World Program Programming Tutorials Example 2-3. Nowaited Hello World Source Code (page 2 of 3) /* * Set up the management environment. We'll talk to the local * agent, registering ourselves as 1.3.6.1.4.1.442.2.1 * with no password.
Programming Tutorials Nowaited Hello World Program Example 2-3. Nowaited Hello World Source Code (page 3 of 3) /* If the print frequency has been modified output the * helloFreqChange trap. */ if (last_freq != helloPrintFreq) { last_freq = helloPrintFreq; (void) mgmt_trap(mgmt_env, &TRAP_helloFreqChange); } /* * print whatever the message currently is, * keeping a count, of course. */ helloText.val[helloText.len] = '\0'; (void) fputs((char *) helloText.
Fault-Tolerant Hello World Program Programming Tutorials Fault-Tolerant Hello World Program The NonStop agent provides fault tolerance on a particular host, because it runs as a NonStop process pair. If the primary agent process fails, a backup agent process having the same name takes over. In addition, you can configure the NonStop agent to receive requests simultaneously from multiple controllers.
Programming Tutorials Fault-Tolerant Hello World Program Fault-Tolerant Hello World behaves like Nowaited Hello World once connection with a particular NonStop agent has been established: • • • • • • It prints the value of helloOutputText at the frequency associated with helloPrintFreq. It also prints the value of helloOutputText when it receives any request. It supports Get and Set operations on helloOutputText. It supports Get and Set operations on helloPrintFreq.
Fault-Tolerant Hello World Program Programming Tutorials Figure 2-3.
Programming Tutorials Fault-Tolerant Hello World Program Source Code The Fault-Tolerant Hello World source code appears in Example 2-4. Numbers in the example correspond to comments in the discussions located between here and the example. Global Declarations Declarations are set up to handle simultaneous communication with multiple NonStop agents: 1. A structure is declared to hold three values for each NonStop agent connection. 2.
Fault-Tolerant Hello World Program Programming Tutorials Example 2-4.
Programming Tutorials Fault-Tolerant Hello World Program Example 2-4. Fault-Tolerant Hello World Program (page 2 of 3) /* Set up each agent environment */ living_agent_count = 0; for (i=1; i
Fault-Tolerant Hello World Program Programming Tutorials Example 2-4. Fault-Tolerant Hello World Program (page 3 of 3) } /* end if */ } /* end for */ goto wait; } /* end if timeout */ } /* end if status != CCE */ /* figure out which mgmt_env is associated with this file number */ for (i=1; i
Programming Tutorials Static Directory Program Static Directory Program This subagent illustrates how to make a tabular MIB object manageable. In this case the table is static: that is, its entries do not change while the subagent is executing. Dealing with static tables is simple for a subagent. All the subagent has to do is build the table and register each of its rows using mgmt_new_instance(). Thereafter, the run-time library can find entries whenever mgmt_poll() is called.
Static Directory Program Programming Tutorials Example 2-5.
Programming Tutorials Static Directory Program Logic Static Directory is implemented by using three source code files: fixedlsc The main program dirH The definition of structures directory and file_entry dirC The definition of three functions used by the subagent: build_files(), insert_new_file(), and comp_files() Logic Flow As Figure 2-4 illustrates, Static Directory calls these functions in fixedlsc: mgmt_init_env() mgmt_new_instance() for the MIB build_files() mgmt_new_instance() for each table ent
Static Directory Program Programming Tutorials Figure 2-4. Logic Flow for Static Directory mgmt_init_env() (Initialize management environment) Start mgmt_new_instance() (Register MIB) build_files() (Build table) mgmt_new_instance() (Register each entry) mgmt_poll() (Process SNMP request) YES Still connected to agent ? NO Stop 209 3. The structure that holds the subvolume name is initialized. 4. The value zsnmpsdk is assigned to the dir_name field of the directory structure. 5.
Programming Tutorials Static Directory Program Note that several C library header files (12) are included to support the system calls in build_files(). The build_files() function uses two defines (16) generated by GDMOC. 8. Each entry (file name) is made available for management. The third parameter of this mgmt_new_instance() call points to the filled-in structure holding file names.
Static Directory Program Programming Tutorials Example 2-6. Static Directory Main Program (page 2 of 3) { struct directory *dir; <-- 2 struct file_entry *file; Void *mgmt_env; Void *group_handle; Void *row_handle; short dummy = 0; /* Check command line invocation: expect 1 parameter */ if (argc != 2) { (void) fprintf(stderr, "Usage: run %s $\n", argv[0]); exit(2); } /* * initialize context structure. Start with the default * directory name of "/tmp" ("zsnmpsdk" on Tandem).
Programming Tutorials Static Directory Program Example 2-6. Static Directory Main Program (page 3 of 3) if (group_handle == NULL) { (void) fprintf(stderr, "%s: group instantiation failure\n", argv[0]); exit(2); } /* Build the cache of file names. */ build_files(dir); <-- 7 ... /* Register each file name as a row of the fileEntry table. for (file = dir->files; file; file = file->next) { /* the row_handle is not saved since each * row of the table is never deleted.
Static Directory Program Programming Tutorials Example 2-7. Static Directory Include File dirH #ifndef DIRH #define DIRH #include "smitypeH" #include "syspubH" ...
Programming Tutorials Static Directory Program Example 2-8. Static Directory Include File dirC (page 1 of 3) #include #include #include #include "tdmporth" "machtypH" "syspubH" "dirH" #include 12 #include /*Local prototypes */ static int cmp(char *x, char *y, int l); static struct file_entry *insert_new_file(struct file_entry *file_list, struct file_entry *file); ...
Static Directory Program Programming Tutorials Example 2-8. Static Directory Include File dirC (page 2 of 3) /***************************************************************************** * insert_new_file Add a new entry to the list of file names. 14 * This entry is put in the list in increasing * lexical order.
Programming Tutorials Static Directory Program Example 2-8. Static Directory Include File dirC (page 3 of 3) /***************************************************************************** * build_files Build the list of file names.
Dynamic Directory Program Programming Tutorials Dynamic Directory Program This subagent enhances Static Directory to manage a dynamic table. The static table managed by Static Directory does not reflect changes to the file content of the subvolume during the time the subagent is executing. If a file is added or deleted or renamed after the subagent is started, the table does not reflect these changes.
Programming Tutorials Dynamic Directory Program MIB Example 2-9 shows the MIB definition used by Dynamic Directory. The MIB defines the same number and type of objects used by Static Directory, but names them differently. It also identifies the next and locator functions used by the subagent and assigns read-write access to the MIB object named dirName. Items in bold type indicate differences from the Static Directory MIB. Example 2-9.
Dynamic Directory Program Programming Tutorials Logic Dynamic Directory is implemented by using three source code files: dynamlsc The main program as well as the next and locator function definitions dirH The definition of structures directory and file_entry dirC The definition of other functions used by the subagent: build_files(), insert_new_file(), comp_files(), and free_files() Logic Flow As Figure 2-5 illustrates, Dynamic Directory processes SNMP requests until connection with the NonStop agent i
Programming Tutorials Dynamic Directory Program Figure 2-5.
Dynamic Directory Program Programming Tutorials Global Declarations 1. This subagent includes a file named errnoH, needed by the function named next_file(). Main Control Block The main block controls the logic flow as indicated earlier in Figure 2-5: 2. The subvolume name is initialized to zsnmpsdk. This value can be changed by Set operations from a manager. 3. The management environment is initialized. 4. The MIB is registered. 5. The table is registered.
Programming Tutorials SNMP Subagent Programmer’s Guide—119728 Dynamic Directory Program 2- 49
Dynamic Directory Program Programming Tutorials Example 2-10. Dynamic Directory Main Program and Next and Locator Functions (page 1 of 4) #include "tdmporth" #include "machtypH" #include "syspubH" #include "errnoH" <-- 1 #include "mgmtpubH" #include "dirH" /* * The SMI compiler output must be included after all * the attribute data structures have been defined since * this output will make reference to these structures.
Programming Tutorials Dynamic Directory Program Example 2-10. Dynamic Directory Main Program and Next and Locator Functions (page 2 of 4) if (mgmt_env == NULL) { (void) fprintf(stderr, "%s: failed to connect to agent\n", argv[0]); return(2); } /* * Instantiate the group that contains the table.
Dynamic Directory Program Programming Tutorials Example 2-10. Dynamic Directory Main Program and Next and Locator Functions (page 3 of 4) /***************************************************************************** * next_file The job of this <-- 8 * function is to return the indices of the * "next" row of this table. ****************************************************************************/ int next_file(Void *ctxt, Void **indices) ...
Programming Tutorials Dynamic Directory Program Example 2-10. Dynamic Directory Main Program and Next and Locator Functions (page 4 of 4) /***************************************************************************** * locate_file This routine returns the context 14 * pointer for a row specified in the indices * parameter. ****************************************************************************/ Void * locate_file(Void *ctxt, Void **indices, int op) ...
Dynamic Directory Program Programming Tutorials Example 2-11. Dynamic Directory Include File dirC (page 1 of 3) #include #include #include #include "tdmporth" "machtypH" "syspubH" "dirH" #include #include /*Local prototypes */ static int cmp(char *x, char *y, int l); static struct file_entry *insert_new_file(struct file_entry *file_list, struct file_entry *file); ...
Programming Tutorials Dynamic Directory Program Example 2-11. Dynamic Directory Include File dirC (page 2 of 3) } /***************************************************************************** * insert_new_file Add a new entry to the list of file names. 18 * This entry is put in the list in increasing * lexical order.
Dynamic Directory Program Programming Tutorials Example 2-11. Dynamic Directory Include File dirC (page 3 of 3) /***************************************************************************** * build_files Build the list of file names.
Programming Tutorials Indexed Trap Generator Indexed Trap Generator This subagent illustrates how to generate a trap containing three variable bindings: a card number, a port number, and a computed ratio of the two numbers. These three variables constitute one entry in a static table that the subagent builds upon startup. The index to each entry is a combination of its associated card number and port number.
Indexed Trap Generator Programming Tutorials MIB Example 2-12 shows the MIB definition used by Indexed Trap Generator. The MIB defines these objects: tblTrapCards The number of cards for which entries exist in the table. The value for this object is maintained in a field named card_count of a structure named “master.” A manager has read-only access to the value of this object. tblTrapPorts The maximum number of ports associated with any card having an entry in the table.
Programming Tutorials Indexed Trap Generator Example 2-12. Indexed Trap Generator MIB Definition (page 2 of 3) tblTrap OBJECT IDENTIFIER ::= { peer-demos 9 } tblTrapCards SYNTAX ACCESS OBJECT-TYPE Gauge read-only C_STRUCT master, FIELD card_count STATUS mandatory DESCRIPTION "The tblTrapCards variable reports the number of cards in the tblTrapTable.
Indexed Trap Generator Programming Tutorials Example 2-12. Indexed Trap Generator MIB Definition (page 3 of 3) TableEntry ::= SEQUENCE { cardNumber INTEGER, portNumber INTEGER, ratio DisplayString } cardNumber OBJECT-TYPE SYNTAX INTEGER (1..1000) ACCESS read-only C_STRUCT mytable, FIELD card C_LOCATOR_FUNC locate_entry STATUS mandatory DESCRIPTION "The card number index of the table" ::= { tblTrapTableEntry 1 } portNumber OBJECT-TYPE SYNTAX INTEGER (1..
Programming Tutorials Indexed Trap Generator Logic The source code for the main block and the locator and next functions is in the file named tbltrapc. Logic Flow As Figure 2-6 illustrates, Indexed Trap Generator adds entries to the table before initializing the management environment. After completing one mgmt_poll() call, the subagent registers the MIB and the table, then prompts for an index value.
Indexed Trap Generator Programming Tutorials Figure 2-6.
Programming Tutorials Indexed Trap Generator Main Control Block The main block processes SNMP requests and generates traps: 7. The timeval structure is used to set up the timeout parameter for the second mgmt_poll() call. 8. The entries in the table are initialized. An entry is created for four cards and their three corresponding ports. 9. The management environment is initialized. 10. The MIB, named tblTrap, is registered. 11.
Indexed Trap Generator Programming Tutorials 22. If the index values are good, they are adjusted for 0-based indexing. 23. The entry in the table is located. Next Function The function named next_entry is called by the run-time library when a GetNext operation is being performed: 24. The function is defined. The function uses two parameters: t The context from the second mgmt_new_instance() call i The addresses of index values 25. The value of the card index is determined. 26.
Programming Tutorials Indexed Trap Generator Example 2-13.
Indexed Trap Generator Programming Tutorials Example 2-13. Indexed Trap Generator Main Program and Next and Locator Functions (page 2 of 5) /************************************************************************* * main - simple example of sending traps containing indexed variables ************************************************************************/ int main(int argc, char **argv) ...
Programming Tutorials Indexed Trap Generator Example 2-13.
Indexed Trap Generator Programming Tutorials Example 2-13.
Programming Tutorials Indexed Trap Generator Example 2-13. Indexed Trap Generator Main Program and Next and Locator Functions (page 5 of 5) /************************************************************************* * next_entry - determine what the next entry in the table would be ************************************************************************/ int next_entry(Void *t, 24 Void **i) ...
System Time Manager Programming Tutorials System Time Manager This subagent illustrates how to encode Get, Test, and Set operations in what are known as “access functions,” which contain logic for retrieving or changing MIB object values. In some cases, you can rely on the access functions GDMOC generates to retrieve and change MIB object values. In other cases, however, you need more control over the logic that is executed when MIB values are manipulated.
Programming Tutorials System Time Manager MIB Example 2-14 shows the MIB definition used by System Time Manager. The MIB defines only one object: systemTimeString. This scalar object is a read-write object formatted as a string of 19 characters: YYYY/MM/DD HH:MM:SS Example 2-14.
System Time Manager Programming Tutorials GDMOC expects the access functions to be named as follows, using the name in the extension: GET_systemTimeString The Get function TEST_systemTimeString The Test function SET_systemTimeString The Set function Logic The source code for this subagent is contained in two files: systimec The main block accessfc The access functions Logic Flow Figure 2-7 illustrates the logic flow of System Time Manager.
Programming Tutorials System Time Manager ¬ Figure 2-7.
System Time Manager Programming Tutorials Global Declarations The global declarations include definitions for several variables and a statement that includes the file containing the access functions: 1. The MIB object (systemTimeString) and a variable (juliantime) passed by the Test function to the Set function are declared. 2. The file containing the access functions, accessfc, is included. Main Control Block This logic calls the necessary management functions: 3.
Programming Tutorials System Time Manager 10.
System Time Manager Programming Tutorials Example 2-15. System Time Manager Main Program (page 1 of 2) #include "tdmporth" nolist #include "machtyph" nolist #include "syspubh" nolist #include "smitypeh" nolist #include "mgmtpubh" nolist /* global attributes that will be referenced by SMI * compiler generated code.
Programming Tutorials System Time Manager Example 2-15. System Time Manager Main Program (page 2 of 2) /* Let the agent know information what we're responsible for.
System Time Manager Programming Tutorials Example 2-16. System Time Manager Access Functions (page 1 of 2) #include "tdmporth" #include "snmperrH" #include "smitypeH" nolist nolist nolist /* these three include files are here so */ /* accessf.c could be compiled separately */ /* from systime.c.
Programming Tutorials System Time Manager Example 2-16.
Security Checker Programming Tutorials Security Checker This subagent illustrates subagent authentication, which a subagent can use to determine whether to process a request based on information about the manager station that sent it. The Security Checker subagent is a modified version of the Nowaited Hello World subagent.
Programming Tutorials Security Checker 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.
Security Checker Programming Tutorials Checker’s MIB extensions, highlighted in bold type, identify access functions provided for each MIB object. Example 2-17.
Programming Tutorials Security Checker Example 2-17. Security Checker MIB Definition (page 2 of 2) helloFreqChange TRAP-TYPE ENTERPRISE hello VARIABLES { helloPrintFreq } DESCRIPTION "A helloFreqChange trap signifies that the sending hello world entity has had its `helloPrintFreq` variable modified.
Security Checker Programming Tutorials Figure 2-8.
Programming Tutorials Security Checker Source Code The Security Checker source code appears in Examples 2-18 through 2-20: Example 2-18 shows the main control block, contained in helloscc. Example 2-19 shows the authentication function, contained in authentc. Example 2-20 shows the access functions, contained in securitc. Numbers in the examples correspond to comments in the discussions located between here and the examples.
Security Checker Programming Tutorials 13. If connection with the NonStop agent is lost, the subagent calls mgmt_del_instance() and mgmt_term_env() to release memory before terminating. Authentication Function The file named authentc contains the authentication function, authenticate(): 14. A variable used to identify the pair of colons used to separate the agent’s community string from the subagent password is declared. 15.
Programming Tutorials Security Checker Although Security Checker uses only this simple authentication test, more sophisticated tests could appear in this location. You might, for example, want to process the request only if one of several possible passwords is associated with the request. Example 2-18. Security Checker Main Program (page 1 of 5) /*********************************************************************************** * * hellosc.
Security Checker Programming Tutorials Example 2-18. Security Checker Main Program (page 2 of 5) /************************************************************************* * * main - hello-world security demo main program.
Programming Tutorials Security Checker Example 2-18. Security Checker Main Program (page 3 of 5) /* * * * */ Set up the management environment. We'll talk to the local agent, registering ourselves as 1.3.6.1.4.1.442.2.1 with no password.
Security Checker Programming Tutorials Example 2-18. Security Checker Main Program (page 4 of 5) wait: event_fileno = -1; status = AWAITIOX(&event_fileno,,&count_xferd,,100*helloPrintFreq); if (status != CCE) { FILE_GETINFO_(event_fileno, &error); if (error == 40) { (void) fputs((char *) helloText.
Programming Tutorials Security Checker Example 2-18. Security Checker Main Program (page 5 of 5) /* * print whatever the message currently is, * keeping a count, of course. */ helloText.val[helloText.len] = '\0'; (void) fputs((char *) helloText.val, stderr); (void) fputs("\n", stderr); helloPrintCnt++; } /* end if agent filenumber */ else { /* handle AWAITIO completion on other files... */ (void) fprintf(stderr, "%s:AWAITIO completed on file number %i\n", argv[0], event_fileno); } /* end if .. else ..
Security Checker Programming Tutorials Example 2-19. Security Checker Authentication Function /* authent.c - authentication function for hello-security subagent example */ static short #ifdef USE_PROTOTYPES authenticate(void) #else authenticate() #endif { /* authenticate() returns 1 if (global) password exactly matches , 0 otherwise. the agent sends us exactly the community string it received. however, it only validates the portion before the double-colons; the rest is up to us.
Programming Tutorials Security Checker Example 2-20. Security Checker Access Functions (page 1 of 3) /* securit.
Security Checker Programming Tutorials Example 2-20. Security Checker Access Functions (page 2 of 3) static int #ifdef USE_PROTOTYPES SET_helloOutputText(void *ctxt, void **indices, void *attr_ref) #else SET_helloOutputText(ctxt, indices, attr_ref) void *ctxt; void **indices; void *attr_ref; #endif { OCTETSTRING *attr; if (!authenticated) {return(SNMP_ERR_GEN_ERR);} <- -19 attr = (OCTETSTRING *) attr_ref; helloText.len = attr->len; (void) memcpy((char *) helloText.
Programming Tutorials Security Checker Example 2-20.
3 Writing and Compiling MIBs This section describes how to encode Management Information Bases (MIBs) and how to compile them using the MIB compiler, GDMOC (Guideline for Definition of Managed Objects Compiler). Encoding MIBs When you use SNMP, you define a MIB to model the information your subagent makes available for management. The manager views managed information as modeled in the MIB. To create a MIB, you write a MIB definition.
Encoding MIBs Writing and Compiling MIBs MIB-object-definitions describe the characteristics of each object in your MIB. scalar-object-definitions | table-definitions scalar-object-definitions describe scalar MIB objects. Encode scalar object definitions as described later in this section, under “Scalar Object Definitions.” table-definitions describe tabular MIB objects. Encode table definitions as described later in this section, under “Table Definitions.
Writing and Compiling MIBs Encoding MIBs A construct defined in a #define directive can be used only with other directives, not within MIB definition constructs. For example, GDMOC supports this use of the #define directive: #define MAX 255 #if MAX DisplayString (0..255) But GDMOC does not accept this use: #define MAX 255 DisplayString (0..MAX) GDMOC evaluates #if directives that contain string defines, but not numeric defines.
Encoding MIBs Writing and Compiling MIBs The first elements in your MIB definition, SNMP type definitions, map the SNMP data types to C data types. GDMOC requires that these definitions appear at the beginning of your MIB definition because later definitions refer to them. The Toolkit header file named typessmi contains SNMP type definitions for all the SNMP data types.
Writing and Compiling MIBs Encoding MIBs object-name-sequence consists of a list of subtrees, a space, and a number identifying the object. The subtrees are listed from highest to lowest in the SNMP name hierarchy, ending with the subtree in which the object resides.
Encoding MIBs Writing and Compiling MIBs While you are evaluating the Toolkit, you can put your MIB in the subtree named snmptestarc, defined by Tandem. The object identifier for this subtree is 1.3.6.1.4.1.169.3.155.2: iso (1) org (3) dod (6) internet (1) private (4) enterprises (1) tandem (169) nonstopsystems (3) snmp (155) snmptestarc (2) You can obtain MIBs defined by other vendors from the Internet. The directory mib/ on host venera.isi.edu serves as a public repository of enterprise-specific MIBs.
Writing and Compiling MIBs Encoding MIBs encoding is kept separate from the extensions are discussed later in this section, under “Isolating Standard Definitions.” scalar-object-name OBJECT-TYPE SYNTAX abstract-syntax ACCESS object-access extensions STATUS support-type [DESCRIPTION "object-description"] [REFERENCE "cross-reference"] [DEFVAL "{"default-value"}"] ::= "{"object-name"}" scalar-object-name is a logical name for the MIB object.
Encoding MIBs Writing and Compiling MIBs ACCESS object-access assigns a standard SNMP access type to the MIB object. The value of object-access can be one of these. read-only | read-write | write-only | not-accessible read-only lets managers perform only Get or GetNext operations on the object’s value. read-write lets managers perform Get, GetNext, and Set operations on the object’s value. write-only lets managers perform only Set operations on the object’s value.
Writing and Compiling MIBs Encoding MIBs C_ACCESS_FUNC access-function-name specifies that the subagent supplies its own code for Get, Set, and Test operations on the object. Although you can often rely on the access functions GDMOC generates, in some cases your subagent needs more control over the processing associated with Get, Set, and Test operations. Refer to Section 4, “Writing Subagent Logic,” for more information about how and when to encode access functions.
Encoding MIBs Writing and Compiling MIBs STATUS support-type assigns a standard SNMP support type to the MIB object. Although the value of support-type can be one of these four, objects in your MIBs should be assigned the value mandatory; the other values are of use only in standard MIBs. mandatory | optional | obsolete | deprecated DESCRIPTION "object-description" documents the semantics of the MIB object. Although this clause is optional, you should always provide one.
Writing and Compiling MIBs Encoding MIBs This MIB object is a DisplayString (meaning a printable string of ASCII characters) that is defined to be between 1 and 255 characters long. The C_VARIABLE clause indicates that a global variable holds the value of this MIB object. The subagent may need to perform some processing before the run-time library accesses the global variable.
Encoding MIBs Writing and Compiling MIBs encoding is kept separate from the extensions are discussed later in this section, under “Isolating Standard Definitions.
Writing and Compiling MIBs Encoding MIBs entry-name is the logical name for the object type describing Entry-Name. Like other OBJECTTYPE names, the convention is to encode this name using an initial lower-case letter: tableEntry OBJECT-TYPE INDEX index-list [C_NEXT_FUNC next-function-name] defines how each entry is indexed. An index-list is one or more objects in a table entry whose values distinguish the entry.
Encoding MIBs Writing and Compiling MIBs scalar-object-syntax is the SNMP data type for the entry object. It must match the value you encode in the SYNTAX clause of the scalar-object-definition for the entry object. scalar-object-definition describes each object in an entry. Encode this definition as described earlier in this section, under “Scalar Object Definitions.
Writing and Compiling MIBs Encoding MIBs and the C_LOCATOR_FUNC clause in the entry object definitions identifies the locator function (locate_entry). Values for the entry objects are maintained in three fields of a structure named “mytable”: tblTrapTable OBJECT-TYPE SYNTAX SEQUENCE OF TableEntry ACCESS not-accessible STATUS mandatory DESCRIPTION "The tblTrapTable table consists of entries, one for each port of each card.
Encoding MIBs Writing and Compiling MIBs The trap, tableTrap, contains three variable bindings, one for each of the table entry objects; refer to the following subsection, “Trap Definitions,” for information on defining traps: tableTrap TRAP-TYPE ENTERPRISE tblTrap VARIABLES { cardNumber, portNumber, ratio } DESCRIPTION "This trap is generated whenever a legal card and port combination is provided to the program." ::= 0 Trap Definitions Trap definitions are encoded as specified in RFC 1215.
Writing and Compiling MIBs Encoding MIBs REFERENCE "reference-text" is an optional clause for documenting the relationship between this trap definition and a trap definition appearing elsewhere. trap-number is an integer that uniquely identifies the trap within the management enterprise named in the ENTERPRISE clause.
Compiling MIBs Writing and Compiling MIBs installing your MIB definition on a manager station. In the following syntax notation, the concise MIB constructs are in a file named MYMIB. #include "MYMIB" EXTEND OBJECT-TYPE MIB-object-name WITH extensions IN C Compiling MIBs You use GDMOC, the MIB compiler, to compile your MIB definition into a header file that you include in your subagent source code: #include "GDMOC-output-file" Invoke GDMOC like this. RUN ZSNMPSDK.
Writing and Compiling MIBs Compiling MIBs The information in the GDMOC output file depends on the extensions you encode in your MIB definition. Table 3-1 summarizes the dependencies between your extensions and GDMOC behavior. Table 3-1. Relationship Between MIB Extensions and GDMOC Behavior Extensions GDMOC Behavior None Assumes that all C variables in your subagent logic are global variables that have the same name in C as the name you provide in your MIB definitions.
Compiling MIBs 3- 20 Writing and Compiling MIBs 119728 —SNMP Subagent Programmer’s Guide
4 Writing Subagent Logic This section describes how to handle the following elements in your C source code: • • • • Header files needed to use the run-time library. MIB variable declarations that allocate storage for MIB object values. Management functions, which your subagent calls to initiate SNMP message handling operations. Callback functions, which you optionally encode for the run-time library to call.
MIB Variable Declarations Writing Subagent Logic Depending on the functions your subagent uses, you may also need to include one or more of these header files: Functions Header Files Access functions smitypeh snmperrh Locator function locatorh Management function mgmt_del_instance() errnoh Management function mgmt_read_nowait() mgmtenvh snmpvblh Management function mgmt_trap() errnoh Next function erronoh stdtypeh GDMOC Output File Include the GDMOC output file globally after the declaration
Writing Subagent Logic MIB Variable Declarations Table 4-1.
MIB Variable Declarations Writing Subagent Logic Variable-length data is modeled as struct octet_string data that looks like this: length value data €€€ 401 The subagent must allocate memory for the data portion of this structure. Ensure that enough data space is allocated to hold the maximum length of data. For example, the Hello World program uses a variable-length MIB object, helloOutputText, defined as follows in the MIB definition: helloOutputText OBJECT-TYPE SYNTAX DisplayString (SIZE (0..
Writing Subagent Logic Management Functions Management Functions The management functions are used to initiate and terminate communications with the NonStop agent and managers and to process SNMP messages a subagent receives and sends. Management functions are summarized in Table 4-2 and then described individually in more detail afterward. Encode function names and the types of their arguments using the uppercase and lowercase conventions used in the syntax boxes. Table 4-2.
Management Functions Writing Subagent Logic Figure 4-1.
Writing Subagent Logic Management Functions mgmt_del_instance() The mgmt_del_instance() function de-registers MIB objects with the run-time library, releasing memory used for management of the objects. Use this function when you are finished managing any MIB object collections for which you previously used mgmt_new_instance().
Management Functions Writing Subagent Logic terminates the management of objects registered in an earlier mgmt_new_instance() call. Before Hello World terminates, it calls mgmt_term_env(). if ((mgmt_hello_handle = mgmt_new_instance(mgmt_env, &SMI_GROUP_hello, (void *)NULL)) == NULL); ...
Writing Subagent Logic Management Functions mgmt_init_env() The mgmt_init_env() function initializes the management environment. No other management functions can succeed until mgmt_init_env() completes successfully.
Management Functions Writing Subagent Logic Errors If an error occurs, this function returns NULL. Possible errors include inability to communicate with the NonStop agent or a memory allocation failure. Example The following example is taken from the Hello World sample program. The argument &GI_hello refers to the object identifier structure for the subagent generated by GDMOC. The name of the agent process is passed as the first parameter in the subagent invocation line.
Writing Subagent Logic Management Functions mgmt_new_instance() The mgmt_new_instance() function makes a collection of MIB objects manageable. This function performs a process called “registration,” which lets the NonStop agent know which MIB objects you are making available for management. You register the entire MIB, then any group, table, or table entry within it that you want to make accessible to managers. When registering tables, you have two options: • • Register every entry in the table.
Management Functions Writing Subagent Logic the prefix SMI_GROUP_ to the name in your MIB definition for the MIB, a group within the MIB, or a table entry.
Writing Subagent Logic Management Functions ordering and locating operations required when processing SNMP requests, so the subagent provides no next and locator functions: for (file = dir->files; file; file = file->next) { row_handle = mgmt_new_instance(mgmt_env, &SMI_GROUP_fileEntry, (Void *) file); Contrast this approach with the table-level registration performed by Dynamic Directory, which manages a dynamic table.
Management Functions Writing Subagent Logic mgmt_poll() The mgmt_poll() function accepts an SNMP request from the NonStop agent, then processes it and sends a response back to the agent. If you call mgmt_read_nowait() before calling mgmt_poll(), mgmt_poll() reads the request from a buffer you allocate before the call to mgmt_read_nowait(). Otherwise, mgmt_poll() initiates a waited read to the NonStop agent, blocking further processing until an SNMP message is received.
Writing Subagent Logic Management Functions #include "mgmtpubh" rc = mgmt_poll(mgmt-env, timeout, count-xferd); int mgmt_poll(mgmt-env, void struct timeval short timeout, count-xferd); *mgmt-env; *timeout; *count-xferd; rc is an integer describing the outcome of the call. Any value other than the following indicates that an error occurred: 0 The NonStop agent processed a registration request, a timeout occurred, or the run-time library could not allocate a buffer. 1 A Set operation was processed.
Management Functions Writing Subagent Logic Examples The following example is from the Hello World sample program. Because it uses a blocking mgmt_poll() call, this program is idle until a request arrives from the NonStop agent.
Writing Subagent Logic Management Functions mgmt_read_nowait() The mgmt_read_nowait() function posts a nowaited read to the NonStop agent. Because the function does not initiate a blocking operation, the subagent can perform other activities while waiting for a message from the NonStop agent. When using this function, perform the following activities in sequence: 1. Call mgmt_init_env() and mgmt_new_instance() to initialize object management structures. 2.
Management Functions Writing Subagent Logic Message Buffer Allocation When you allocate a buffer for the message from the agent, use this form. mgmt_env->sess->agent_msg_buffer = (char *) malloc(SNMP_MSG_MAX) mgmt_env identifies the same pointer you use in the call to mgmt_read_nowait(). Example The following example is from the Fault-Tolerant Hello World sample subagent. This subagent handles requests from as many as five NonStop agents.
Writing Subagent Logic Management Functions mgmt_security() The mgmt_security() function makes the community string and IP address of a manager station from which a request is received available to subagents. Based on the values of these objects, a subagent can determine whether to process the request.
Management Functions Writing Subagent Logic successive colons. The total manager station community string can contain 0 through 255 bytes. address is a pointer to a 4-byte buffer in which the NonStop agent stores the IP address of the manager station from which the request has been received. If an error occurs, the IP address is set to 0.0.0.0. Entry Condition The value of mgmt-env must be valid. Errors If an error occurs, the NonStop agent sets the IP address to 0.0.0.
Writing Subagent Logic Management Functions When a request is received from the NonStop agent, Security Checker initializes the value of the flag named “authenticated” to 0. The subagent then calls mgmt_security().
Management Functions Writing Subagent Logic mgmt_term_env() The mgmt_term_env() function terminates communication with the NonStop agent, releasing resources and deregistering objects still registered. Another subagent communicating with the agent can now register the objects. #include "mgmtpubh" mgmt_term_env(mgmt-env); void mgmt_term_env (mgmt-env); void *mgmt-env; mgmt-env is a void pointer returned from an earlier call to mgmt_init_env().
Writing Subagent Logic Management Functions mgmt_trap() The mgmt_trap() function generates a trap. When executing this function, the run-time library calls the Get access function associated with each MIB object for which a value is included in the trap. The library acts as described earlier, under “mgmt_poll(),” for a Get operation, using either access functions generated by GDMOC or access functions you provide in your subagent.
Management Functions Writing Subagent Logic If a subagent sends a trap at exactly the same time the NonStop agent receives a request to process, the NonStop agent rejects the request with a noSuchName error. Example The following example is taken from the Hello World sample program. This program generates a trap whenever a manager changes the value of one of its MIB objects.
Writing Subagent Logic Callback Functions Callback Functions You can write functions for the run-time library to use when performing SNMP operations. Known as “callback functions,” they are encoded in your subagent and referred to by name in your MIB definition. The run-time library invokes callback functions when the associated MIB object is the target of an SNMP operation.
Callback Functions Writing Subagent Logic Table 4-4. When to Use Callback Functions Condition Functions Description Request preprocessing Locator function The subagent needs to perform some operation before a Get or Set operation on a particular MIB object. Dynamic table handling Next function Locator function A tabular MIB object contains entries that are added or deleted during subagent execution or a cache must be checked and sometimes refreshed before a variable is accessed.
Writing Subagent Logic Callback Functions Define the locator function following the C_VARIABLE, C_ACCESS_FUNC, C_STRUCT, or C_TYPE extension. Next Functions Next functions are identified in the INDEX clause associated with a table entry. In the following example, from the Indexed Trap Generator MIB, the next function is named next_entry. The run-time library calls next_entry to process GetNext operations. This next function returns a pointer to the index of the lexically next entry in the table.
Callback Functions Writing Subagent Logic Index Argument Each callback function accepts an index_list argument. This argument is a pointer to an ordered array of pointers.
Writing Subagent Logic Callback Functions Access Functions Access functions are used to provide logic for the run-time library to use for a MIB object when a manager wants to perform Get or Set operations on it. When the run-time library calls an access function, it passes it the value for a MIB object; the function returns an indication of success or failure. Write your own access functions when the access functions generated by GDMOC are not able to handle the request processing required.
Callback Functions Writing Subagent Logic access-function-name is the name that appears in the MIB definition for the MIB object: MIB-object-name OBJECT-TYPE ... ACCESS {READ-ONLY|READ-WRITE|WRITE-ONLY} C_ACCESS_FUNC access-function-name [ C_LOCATOR_FUNC locator-function-name ] ... context is an input value returned from a call to a locator function, if one is associated with the MIB object.
Writing Subagent Logic Callback Functions The Get access function for this subagent uses three C library functions (time, localtime, and strftime) to determine and format the current system time: static int GET_systemTimeString(void *ctxt, void **indices, void *attr_ref) { OCTETSTRING *attr; time_t now; struct tm *curtime; now = time(NULL); curtime = localtime(&now); systemTimeString.len = (Len_t) strftime (systemTimeString.
Callback Functions Writing Subagent Logic Locator Functions Locator functions are used to locate a particular table entry or to perform some operation in your subagent before the run-time library processes an SNMP Get or Set request for a particular object. The function accepts arguments that identify the MIB object, and returns a pointer to its associated context. Always provide a locator function and a next function when you do not register each entry in tables you make available for manager access.
Writing Subagent Logic Callback Functions 0 (LOCATE_SET) 1 (LOCATE_GET) 2 (LOCATE_NEXT) 3 (LOCATE_TEST) 4 (LOCATE_TRAP) To support the creation of new table entries, a subagent should create and initialize the new entry, then return the context pointer of the row when op is set to LOCATE_SET. The run-time library updates the entry with the values contained in the SNMP Set request. Example The following example is taken from the Dynamic Directory sample program.
Callback Functions Writing Subagent Logic To process a Get or Set request, the run-time library uses locate_file(), the locate function. This function builds the table, creating an entry for each file currently associated with the most recently defined subvolume name. To build the table, the locate function calls build_files(), and to identify whether an input file name matches a name in the table, the locate function calls comp_files(). Void * locate_file(Void *ctxt, Void **indices, int op) ...
Writing Subagent Logic Callback Functions Next Functions Next functions are used to return the lexically next set of indexes for an entry in a dynamic table. When the run-time library calls this function, it supplies index values. The function overwrites the current index pointers with pointers to the values of the indexes of the next table entry. Always provide a locator function and a next function when you do not register each entry in tables you make available for manager access.
Callback Functions Writing Subagent Logic Example The following example is taken from the Dynamic Directory sample program. This program provides a next function named next_file, which is identified in the INDEX clause of the MIB definition for the associated table entry: dirFiles OBJECT-TYPE SYNTAX SEQUENCE OF FileEntry ...
Writing Subagent Logic Callback Functions if (*indices == NULL) { file = dir->files; } /* get first one */ else { DisplayString *name = (DisplayString *)indices[0]; for (file = dir->files; file; file = file->next) { if (comp_files(name, &file->file_name) < 0) { break; } } } if (file) { /* Overwrite the array of pointers that * was passed in with pointers to the "next" * set of indices.
Callback Functions 4- 38 Writing Subagent Logic 119728 —SNMP Subagent Programmer’s Guide
5 Creating Executable Subagents To convert subagent MIB definitions and source code into an executable file, follow these steps: 1. Compile the MIB using the Toolkit’s MIB compiler, GDMOC. 2. Compile the subagent source code using the C compiler. 3. Bind the subagent object code with the run-time library using the Binder utility. 4. If the subagent will execute on a TNS/R system, optionally optimize the subagent using the Accelerator.
Binding Creating Executable Subagents Then invoke the C compiler. The following invocation line compiles the Hello World source code in helloc into a file named helloo: c /in helloc, out $s.#cc.hello/ helloo; & ssv0 "$system.system", & ssv1 "zsnmpsdk", & ssv2 "[#defaults/current/]", & wide The OUT option names a spooler destination for the compiler listing. The SSV pragmas provide a list of search subvolumes for files specified in include directives.
Creating Executable Subagents Binding The SET command specifies attribute values for Binder to associate with the file it creates. In this example, three SET options are specified: SYMBOLS This option is set to ON so that Inspect symbol tables are retained in the output file. INSPECT This option is set to ON to identify Inspect as the debugger of choice. SAVEABEND This option is set to OFF so that the subagent output file is not saved if Binder terminates abnormally.
Binding Creating Executable Subagents 5. The subagent receives a Get request from a manager. 6. The subagent replies to the Get request. 7. The subagent prints its message again. Use tracing only for subagents still in development. Tracing should not be used for subagents in production use, because subagents run more slowly when tracing is in use. The increased response time between manager and subagent may exceed the timeout window of a manager station. Example 5-1.
Creating Executable Subagents Using TACL Acceleration When the target system for subagent execution is a RISC system, you have the option of accelerating the executable subagent using the Accelerator. The following command creates an accelerated object file named hellonwa from the Binder output file named hellonw: AXCEL hellonw, hellonwa The accelerated object file contains both the original TNS code and the logically equivalent optimized RISC instructions.
Using TACL Creating Executable Subagents Example 5-2. TACL Routine for Static Directory ?tacl routine == make fixedls example == assumes 1) macro run from source subvol == 2) ISVs are on same disk as current subvol [#def checkstep macro |body| [#if [:_completion:completioncode]<>0 |then| #output %*% failed ~; #return]] == First, create fixedls.h run zsnmpsdk.gdmoc -g fxdlssmi -I zsnmpsdk -c fixedlsh checkstep GDMOC compilation <-- 1 <-- 2 <-- 3 <-- 4 == second, compile fixedls.c and dir.
Index A Acceleration 5-5 Access functions header files 4-2 in Security Checker program 2-78, 2-81 in System Time Manager program 2-68, 2-72 MIB extensions 3-9, 4-27 syntax 4-29 when to use 4-25 Access type 3-8 Authentication 1-3, 2-78, 4-19 AWAITIOX and mgmt_read_nowait() 4-17 in Fault-Tolerant Hello World program 2-28 in Nowaited Hello World program 2-20 in Security Checker program 2-83 B Binding 5-2 Building subagents 1-9, 5-1 C C_ACCESS_FUNC extension 3-9 C compilation 5-1 Callback functions access fun
F Examples (continued) next function 2-43, 2-55 Nowaited Hello World program 2-17 sample subagent files 2-1 sample subagent summary 2-1 scalar object definitions 3-10 Security Checker program 2-78 Static Directory program 2-32 System Time Manager program 2-68 table definition 3-14 TACL routines for building subagents 5-5 tracing 5-3 trap definition 3-17 using sample subagents 2-2 Extensions to concise MIB 1-8, 3-1, 3-8, 3-19, 4-26 F Fault-Tolerant Hello World program AWAITIOX 2-28 FILE_GETINFO_ 2-28 funct
Index L Linking files 5-2 Locator functions header files 4-2 in Dynamic Directory program 2-47 in Indexed Trap Generator program 2-61 MIB definition for 3-8, 3-9 MIB extensions 4-26 syntax 4-32 when to use 4-25 M machtyph header file 4-1 Management functions 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 relationships among 4-5 Manager station configuration 1-11, 2-8, 3-17 mgmtenvh hea
N mgmt_term_env() in Hello World program 2-14 syntax 4-22 mgmt_trap() in Hello World program 2-14 in Indexed Trap Generator program 2-61 in Security Checker program 2-83 syntax 4-23 MIB compiler See GDMOC MIB definition comments 3-2 compiling 3-18 components 3-1 encoding 3-1 extensions 3-8, 3-19 GDMOC preprocessor directives 3-2 installing 2-8 isolating extensions 3-17 name 3-1 object names 3-4 scalar objects 3-6 SNMP types 3-3 subtree registration 3-5 tables 3-11 traps 3-16 MIB information resources 3-4,
Index R Registering tables 2-32, 2-43, 2-55, 4-11 Run-time libraries PEERLBTO 1-9, 5-3 PEERLIBO 1-9, 5-2 Run-time library actions 4-14 S Sample subagents See Examples Scalar objects in tables 3-11 MIB definition of 3-6 Security 1-3, 2-78, 4-19 Security Checker program functions 2-79 logic 2-81 MIB definition 2-79 Set access function 4-29 smitypeh header file 4-1 snmperrh header file 4-2 snmpvblh header file 4-2 Static Directory program functions 2-32 logic 2-34 MIB definition 2-32 stdtypeh header file 4-2
W Index- 6 Index 119728 —SNMP Subagent Programmer’s Guide
