12 - Procedure for Writing an Agent

• Agent Initialization and Startup
• Agent Shutdown
• Request Verification and Dispatching
• Handling Requests for Data Reports, Event Reports, and Setting Attributes
• Error Reporting
• Generating and Sending Asynchronous Reports (Traps)

12.1 Agent Initialization and Startup

After parsing any command-line parameters and executing agent-specific initialization, the agent calls netmgt_init_rpc_agent() to register with the RPC system and initialize the Agent Services library data structures. The parameters of this call are protocol-specific. They do not directly affect the agent application. They fall into several categories:

Agent Identification

identifies an agent by the RPC service name, agent-writer assigned serial number, RPC program number, and RPC version number parameters.

characterizes a transaction by the transport protocol to be used in manager/agent communication, the transaction time limit, and various flags such as whether agent requests run as subprocesses.

lists agent-supplied routines called by the Agent Services library to validate a request from a manager, dispatch the request, reap the agent child spawned by the request, and shutdown the agent's parent process.

12.2 Agent Shutdown

If a report cannot be delivered to the report rendezvous, the Agent Services library automatically retries at appropriate intervals. If the rendezvous is a program with a permanent RPC number (like the logger or event dispatcher), the library tries to send the report forever. If the rendezvous is a program with a transient RPC number (like the Console or snm_cmd), the library tries to send the report a small number of times before considering it undeliverable. If a report is considered undeliverable the Agent Services library will shut down the agent child process.

The Agent Services library uses the following signals in the parent: SIGINT, SIGQUIT, SIGTERM and SIGCHLD. If the parent wishes to have control passed to its own functions when one of these signals occurs, it should specify the functions in the shutdown (for SIGINT, SIGQUIT and SIGTERM ) and reap (for SIGCHLD) parameters in the call to netmgt_init_rpc_agent(). One signal is used in the child: SIGUSR1. Agents should avoid using this signal.

12.3 Request Verification and Dispatching

The agent verification routine has a limited time to verify a request as dictated by the <timeout> argument specified by the manager making the request. This timeout is typically between 10 and 30 seconds, so the agent's verification routine should not do an extended amount of processing. For instance, verifying that the group name is valid would be appropriate, but retrieving information from a distant network would not be appropriate.

---

NOTE - If the verification routine opens files or allocates memory, it must be able to close the files or free the memory after control has passed to the child process. Otherwise, memory and file descriptor leakage may occur. For this reason, you should avoid agent setup tasks in the verification routine.

---

Besides receiving requests from a manager, agents can also read requests from the request.log file on the agent system--this is the case when a request is restarted. For these requests, the verification routine is bypassed and the dispatch routine is called directly. Note that if any agent setup tasks are performed in the verification routine, the agent will not be set up correctly for restarted requests.

12.3.1 Verification and Dispatching Routine Parameters

The following parameters are passed to the agent-supplied verification and dispatching procedures:

<type>

unsigned integer containing the request type code. The type code is either NETMGT_DATA_REQUEST for requesting data reports or NETMGT_EVENT_REQUEST for requesting event reports. Agents don't need to know the request type, but the code is provided for agents who want to do additional processing based on the request type.

pointer to a null-terminated ASCII string containing the name of the system where the managed element is located. If the agent is a proxy agent, this name may be different from the name of the system where the agent is running.

pointer to a null-terminated ASCII string containing the name of the group whose attribute values are to be collected. Group and attribute relationships are specified in the agent schema. (See Chapter 2, "Registering for Data, Event, and Trap Reports ," for more information on the agent schema.)

optional pointer to a null-terminated ASCII string containing a key uniquely identifying an instance of the <group> on the managed <target>.

The interpretation of this string is left largely to the agent writer. Use white-space separated strings for key selectors, or a null string when all table entries are desired. The key is usually an attribute in the table. Managers have no knowledge of what agents will accept as keys; agent writers are encouraged to document their use of the key field.

unsigned integer containing the maximum reports to send. If <count> is zero, the agent should send reports until the request is asked to stop by a manager process.

<interval> structure containing the reporting interval. If <interval> is zero, the agent should use an agent-default value.

<interval> and <count> taken together determine the type of reporting to do. Table 12-1 lists the possible combinations and their interpretations (c and i are positive integers):

Table  12-1 Count/Interval Interpretations

Count	Interval	Interpretation
0	0	Send reports forever at an agent-specific interval
0	i	Send reports forever, every i seconds
1	0	Quick Dump--send one report
1	i	Quick Dump--send one report
c	0	Send c reports at an agent-specific interval
c	i	Send c reports every i seconds

Data gathering methods fall into two categories. Agents may be able to report data instantly or they may need to integrate it over time before reporting. For instant reporting, the agent reports the data then sleeps for the interval specified. For integrative reporting, the agent performs some set of actions over time before the data can be reported. For instance, the supplied ping agent sends many ICMP ECHO requests at one second intervals, then waits a small amount of time for the ECHO REPLY responses. It may take up to 20 seconds for a single report to be sent.

Agents who take a substantial amount of time to integrate and report should subtract their processing time from the manager-specified <interval>, so reports are sent as often as requested. Otherwise, an interval of 20 seconds and a processing time of 20 seconds would mean reports would be sent every 40 seconds--clearly not what the manager intended. Again, agent writers are encouraged to document any specific decisions they make along these lines, so users know what report intervals make sense for an agent.

unsigned integer bit string specifying request options. Currently no request options are defined for use by agents.

12.4 Sending Reports

When servicing a request, the child process should:

• Get any optional request argument by calling netmgt_fetch_argument() setting the parameter argname to NETMGT_OPTSTRING as defined in netmgt_define.h.
• Obtain the data.
• Build a reporting argument list with the current attribute data using netmgt_build_report() , once for each attribute. Check the return code for any errors. If you are interested in whether an event has occurred for the particular attribute (because you intend to do further processing), you can check the value of the second parameter passed to netmgt_build_report(). Most agents do not check this "event" flag because they do no special processing when events occur.
• If the group represents a row of a table, once netmgt_build_report() has been called for all attributes in a group, the agent must call netmgt_mark_end_of_row() to signal the end of the row. netmgt_mark_end_of_row() should always be called to mark the end of a row, even if only one row is being returned.
• Agents that return tables should also return a key by returning an attribute called netmgt_table_key . Returning a key is useful when setting attribute values with the Console's Set tool (snm_set) or when table attributes are graphed from the Results Browser tool.
• Once the report has been completely built and is ready to be delivered, the agent should send the report to the rendezvous process with netmgt_send_report(). If this is the last report the agent will send, set the NETMGT_LAST flag.
• After the final report, return; otherwise, call sleep(3V) to suspend the child process for the time specified by the interval. A specified reporting interval of zero instructs the agent to choose an appropriate interval. A specified reporting count of zero instructs the agent process to continue sending reports every interval until the agent is asked to stop by a manager process. Otherwise, a total of <count> reports should be sent.

12.5 Handling Set Requests

• In your request verification function, determine whether the request is well formed. If it isn't, send an error report to the requester and return an error.
• Assuming the request is well formed, your request dispatch function should set the requested attribute values.
• Send an status report to the requester indicating whether you succeeded in setting the attributes and return.

12.5.1 Verifying the Request

• the request <type> is NETMGT_SET_REQUEST.
• the reporting interval is zero.
• the reporting count is zero.
• the group and key arguments are NULL.

Check whether the values to set the attributes have the correct data types and are within acceptable ranges. (See Table 11-1 on page 11-3 for a list of valid data types.) If your agent can take optional arguments, fetch the arguments using netmgt_fetch_argument(3n).

---

NOTE - The Console snm and command-line manager snm_cmd set the optional argument name to NETMGT_OPTSTRING and the optional argument type to NETMGT_STRING.

---

12.5.2 Set Attribute Values

You should now set the requested attribute values. The way you do this is entirely up to your application.

12.5.3 Send a Status Report

12.5.4 Sample Code

/* agent error codes */ #define SET_FAILED 1 /* -------------------------------------------------------------- * dispatch_request - dispatch agent request * no return value * -------------------------------------------------------------- */ void dispatch_request (type, system, group, key, count, interval, flags)     u_int type, /* request type */     char *system, /* target system */     char *group, /* object group */     char *key, /* table key */     u_int count, /* report count */     struct timeval interval, /* report interval */     u_int flags; /* request flags */ {     NETMGT_DBG("dispatch_request\n");     /* dispatch request based on request type */     switch (type) {     case NETMGT_SET_REQUEST:         do_set_request(system);         return;     /* other cases */     }      return; } /* -------------------------------------------------------------- * do_set_request - perform the set request * no return value * -------------------------------------------------------------- */ void do_set_request(system)     char *system; /* target system name */ {     Netmgt_arg option; /* optional argument */     Netmgt_setval setval; /* set request argument

    Netmgt_error status;		/* status report argument */ 



    NETMGT_DBG("do_set_request\n"); 






    /* get any optional arguments */ 



    if (netmgt_fetch_argument (NETMGT_OPTSTRING, &option)) 






    /* handle request option */ 



    /* fetch request arguments and perform set operations */ 



    for (;;) 



        /* get next set argument 



        if (!netmgt_fetch_setval (&setval)) {



        (void) netmgt_fetch_error(&status); 



        if (!netmgt_send_error(&status)) 



            NETMGT_DBG("netmgt_fetch_setval failed: %s\n", 



                netmgt_sperror()); 



        return; 



    } 






            /* a sentinel string marks the end of arguments 



            if (strcmp (setval.name, NETMGT_ENDOFARGS) == 0) 



            return; 






    /* assume here the set operation failed - send 



     * an fatal error report to the requester 



     */ 



    if (!perform_set(system, setval)) {



        status.service_error = NETMGT_FATAL;	 



        status.agent_error = SET_FAILED; 



        status.message = "a description of why it failed"; 



        if (!netmgt_send_error(&status)) 



            NETMGT_DBG("netmgt_send_error failed: %s\n", 



                netmgt_sperror()); 



        return; 



    } 



} 






/* assume all the set operations succeeded - send a success status 



 * message to the requester 



 */ 



status.service_error = NETMGT_SUCCESS;	 



status.agent_error = (u_int)0; 



status.message = (char *)NULL; 


 


 

if (!netmgt_send_error(&status)) 



    NETMGT_DBG("netmgt_send_error failed: %s\n", netmgt_sperror()); 



    return; 



} 





 


 

12.6 Error Reporting

Generic errors are the fatal errors defined in the header file netmgt_errno.h. Generic errors may be generated by agents or the Agent Services library.

Agents may also report errors specific to the agent. Agent-specific errors are defined by a code/message pair in the agentErrors section of the agent's schema file. Agent-specific errors may also return supplementary text providing additional information about the error.

While all generic errors are fatal, an agent-specific error may be classified as either a warning or fatal. If the error is a warning, the manager assumes the agent will continue to return reports. If the error is fatal, the manager assumes the agent will stop servicing the request. The Console treats fatal errors as high-priority errors and warnings as low-priority errors.

netmgt_send_error() takes a single parameter, a pointer to a Netmgt_error structure with three fields:

service_error

an error code from the enumerated type Netmgt_stat as defined in netmgt_errno.h .

NETMGT_WARNING

signals an agent-specific non-fatal error. The agent_error field provides the agent error code.

NETMGT_FATAL

signals an agent-specific fatal error. The agent_error field provides the agent error code.

Any other error code signals a generic error, and agent_error should be set to zero.

specifies the agent-specific error code from the list defined in the agentErrors section of the agent schema.

message

optional null-terminated string containing instance information about an agent-specific error that cannot be given in the agentErrors section of the agent schema--for example "ie0" or "port 7."

12.7 Generating and Sending Asynchronous Reports (Traps)

The following shows the syntax of the netmgt_start_trap() function:

bool_t netmgt_start_trap(system, agent_prog, agent_vers, group, rendez_host, rendez_prog, rendez_vers, priority, timeout)      char*    system;      u_int    agent_prog;      u_int    agent_vers;      char*    group;      char*    rendez_host;      u_int    rendez_prog;      u_int    rendez_vers;      u_int    priority;      struct timeval timeout;

where

system

is the name of the element associated with the trap.

specifies the RPC program number of the agent that is sending the trap. Specify 0 if unknown.

specifies the RPC program version number of the agent that is sending the trap. Specify 0 if agent_prog is set to 0.

specifies the group within the agent schema to which the trap attributes belong. Specify "trap" if the attributes are not defined in any agent schema.

specifies the name of the system where the trap is to be sent.

rendezvous for the trap. This should be set to NETMGT_EVENT_PROG, the event dispatcher.

specifies the version number of the rendezvous for the trap. This should be NETMGT_EVENT_VERS , the event dispatcher's version number.

specifies the priority of the trap. Choices are NETMGT_LOW_PRIORITY, NETMGT_MEDIUM_PRIORITY, and NETMGT_HIGH_PRIORITY.

specifies the maximum time (in seconds) that the netmgt_start_trap() call is to wait for a reply from the rendezvous when sending a trap report.

A trap is sent to the rendezvous using netmgt_send_report(). Note that netmgt_send_report() may block for the timeout period if the trap cannot be sent to the rendezvous. If the trap cannot be sent, it will be retried the next time a trap or other report is generated.

A point to note is that netmgt_start_trap() does not need to be called again in order to send another trap. You only need to call netmgt_start_trap() if you want to change groups or the value of any argument you specified in the previous call to netmgt_start_trap() .

---

NOTE - Reporting data and issuing traps should occur in separate processes. If an agent collects and sends data in addition to issuing traps, then the agent should issue a trap by calling the fork() system routine to spawn a child process and the building and sending of the trap should be carried out by the child process. This procedure is necessary to ensure that the parent process is not interrupted from collecting and reporting data while the trap is being built and sent. This will prevent loss or delay of reports, especially if the reporting interval is very short.

---

char myname[MAXHOSTNAMELEN+1]; /* system name */ struct timeval timeout; /* timeout buffer */ timeout.tv_sec = 10; /* set timeout value */ timeout.tv_usec = 0; sysinfo (SI_HOSTNAME, MYNAME, 128); netmgt_start_trap(myname, /* system name */                   myprog_number, /* agent program number */      myver_number, /* agent version number */                   "trap", /* group */                   "localhost", /* event dispatcher host */ NETMGT_EVENT_PROG,                   NETMGT_EVENT_VERS, NETMGT_HIGH_PRIORITY,                 timeout)) ... /* Later on, build the report. Do this as many times as you like, once for each attribute in the report. */ Netmgt_data data; /* data buffer */ bool_t event; /* whether an event occurred */ Netmgt_error error; /* error buffer */ (void)strcpy(data.name, attr_name); /* set the attribute name */ data.type = NETMGT_STRING; /* set attribute data type */ data.length = strlen(attr_value); /* set attribute length */ data.value = attr_value; /* set attribute value */

/* build the report */ if (!netmgt_build_report(&data, &event))   fprintf(stderr, "Cannot build report: %s\n", netmgt_sperror()); /* Finally send the trap report to the rendezvous specified by netmgt_start_trap. */ struct timeval delta_time; delta_time.tv_sec = delta_time.tv_usec = 0; if (!netmgt_send_report(delta_time, 0, 0)) fprintf(stderr, "Cannot send report: %s\n", netmgt_sperror());

12.8 Summary

Copyright 1996 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA 94043-1100 USA. All Rights Reserved