4 - Requesting Data and Event Reports

4.1 Formulating a Request

The <group> name is the logical collection of attributes the agent provides to the manager. When a manager application specifies the <group> name, all attributes in the group are returned. If a <key> is specified, it is also agent-specific. Each agent's documentation will describe what attributes inside a table it uses for keys, and the method for selecting them. Again, keys mean nothing to the manager, so anything is fair game here.

---

NOTE - If your application will be using the netmgt_kill_request2(3n) function, you need to call netmgt_set_manager_id (3n) right after calling netmgt_set_instance(3n). See Section 4.7, "Stopping Requests," on page 4-8 , for more information about netmgt_kill_request2(3n).

---

4.2 Optional Arguments

You can also use the option string for SNMP requests. You can specify certain options that you want the SNMP proxy agent to use when sending an SNMP request to a target device. The optional arguments are:

• na.snmp-read-community -- community string for data and event requests
• na.snmp-write-community --community string for set requests
• na.snmp-schema --the name of the schema to be used for performing the request
• na.snmp-proxy-device --name of a vendor's proxy system with which the SNMP proxy agent will communicate. (If this option is used, the SNMP request is not sent to the target device, but will be sent instead to the specified proxy system. This argument should only be used only when a vendor has supplied an SNMP proxy agent to manage a particular device or set of devices. In this situation, the vendor's SNMP proxy agent communicates with theSite/ SunNe/Domain Manager SNMP proxy agent via SNMP, but communicates with the target device using either SNMP or a different protocol.)
• na.snmp-get-list (used only for data reports)--list of object identifiers in standard dot notation. Separate each object ID with a space. For each object ID in the list, the SNMP proxy agent will get the value of the instance specified by the object ID.
• na.snmp-get-next-list (used only for data reports)--list of object identifiers in standard dot notation. Separate each object ID with a space. For each object ID in the list, the SNMP proxy agent will get the value of the lexicographic next instance specified by the object ID. Note that a group or key value should not be specified, rather, specify empty strings for those file IDs.
• na.snmp-timeout (number of seconds the SNMP proxy agent waits for a response from the target device)

The following code fragment shows how to specify an SNMP read community, timeout, and get-list as optional arguments in a request. The complete program example from which this fragment is taken is included in the product structure in the file request.c in the API_examples directory.

bool_t set_snmp_args() { /* argument for setting options */ Netmgt_arg option; /* read community string */ char *community= "community string"; /* SNMP retry interval (in seconds) */ int retry = 10; /* OID list for instances (sysObjectID and sysUpTime) */ char *get_list = "1.3.6.1.2.1.1.2.0 1.3.6.1.2.1.1.3.0"; NETMGT_DBG("setting snmp arguments \n"); /* send SNMP read community */ /* not needed if read access is free strcpy(option.name, "na.snmp-read-community"); option.type = NETMGT_STRING; option.length = strlen(community) + 1; option.value = community; if (!netmgt_set_argument(&option)) { NETMGT_DBG ("netmgt_set_argument failed: %s \n", netmgt_sperror()); return (FALSE); } */ /* send SNMP retry interval */ strcpy(option.name, "na.snmp.retry"); option.type = NETMGT_INT; option.length = sizeof (int); option.value = (char *) &retry; if (!netmgt_set_argument(&option)) { NETMGT_DBG ("netmgt_set_argument failed: %s \n", netmgt_sperror()); return (FALSE); }

/* send OID list to request data only for certain attributes */ strcpy(option.name, "na.snmp-get-list"); option.type = NETMGT_STRING; option.length = strlen(get_list) + 1; option.value = get_list; if (!netmgt_set_argument(&option)) { NETMGT_DBG ("netmgt_set_argument failed: %s \n", netmgt_sperror()); return (FALSE); } }

4.3 Count and Interval

For data reporting, agents report, sleep for <interval> and then report again, <count> times (or forever if <count> is zero). For event reporting, agents act the same way, but the Agent Services library prevents the report from getting back to the manager application if an event was not detected during the <interval> . Thus, it is possible for an agent to "send" <count> reports and exit without the manager application ever seeing an event report, because no events have occurred. (However, the manager application will get a special event report with the NETMGT_NO_EVENTS flag set when the agent finishes processing the request.)

4.4 Request Flags

NETMGT_RESTART

restarts the request if the agent abnormally terminates and is restarted. Otherwise this request is forgotten when the agent restarts.

This flag is advisory; request restart is not guaranteed. The restart is not attempted until the agent parent is started (asked to start another request, or asked what requests it is working on) when all requests marked for restart will be restarted if possible.

have the agent collect the report information but don't send it just yet.

Often an agent collects useful information for debugging problems, but the information isn't useful under normal conditions. If the manager started the request only after the error condition started, it would have been started after the fact and valuable data would have been lost. On the other hand, if the request was started and the reports were continually streaming back to the manager before the error condition occurred, an unnecessary traffic and CPU load would be caused from many uninteresting reports coming back.

With this flag, reports can be held on the agent's system until the manager is ready (if ever) to ask for them. When the manager asks via a call to netmgt_request_deferred(3n) for the collected reports, the "old" reports will be sent.

This option (as well as netmgt_request_deferred (3n), described in its man page) is handled for the agent by the Agent Services library. The library keeps only the last 32 reports the agent "sent", memory permitting.

This option does not defer error reports.

have the agent terminate after one event report has been sent. If this flag is not set, the agent continues to conditionally send event reports until otherwise directed.

4.5 Setting Thresholds

Agents cannot compute inter-attribute relationships; they are only capable of reporting the attributes defined in their agent schema. While some of these attributes are derived values, the formulas for deriving them are hard-coded into the agent.

4.6 Sending the Request

---

NOTE - Requests are identified by the agent host's IP address and the timestamp of the request.

---

4.7 Stopping Requests

• calling netmgt_kill_request (3n) tells an agent to terminate a single request. This function is supported by all versions of Site/SunNet/Domain Manager agents. To stop a single request, you call netmgt_kill_request(3n), specifying the host name, program and version number where the request is running, the request identification (the name of the <manager> who started the request and the request <timestamp>) and a <timeout> value.

If you don't specify <manager> , requests started by any manager will be terminated. If you specify {0,0} for the <timestamp>, requests started at any time will be terminated.

• calling netmgt_kill_request2 (3n) tells an agent to terminate all requests started by a specified manager from a given IP address. This function is only supported by Site/SunNet/domain Manager version 2.x agents or agents created with the Site/SunNet/Domain Manager 2.x agent services libraries.

To stop requests, you call netmgt_kill_request2(3n), specifying the host name, program and version number where the request is running, and a timeout value. Additionally, you must specify a manager identification that uniquely identifies the manager application running on a particular host. (The manager identification is set by calling netmgt_set_manager_id(3n) right after calling netmgt_set_instance(3n), and before calling netmgt_request_data (3n) or netmgt_request_events(3n).)

4.8 Summary

1. Call netmgt_set_instance (3n).

2. Call netmgt_set_manager_id (3n) if you will be using netmgt_kill_request2(3n) to terminate requests.

3. Call netmgt_set_argument (3n) if you have optional arguments.

4. Call netmgt_set_threshold(3n) if you are requesting event reports.

5. Call netmgt_request_data (3n) or netmgt_request_events(3n) to start the request.

6. Call netmgt_kill_request(3n) or netmgt_kill_request2 (3n) to terminate the request.

4.9 Sample Code

/* * request_event - send event report request to agent * returns request timestamp if successful; otherwise NULL */ struct timeval * request_event(count, interval, timeout, threshold, group, optstring, key, flags) u_int count; /* report count */ struct timeval interval; /* reporting interval */ struct timeval timeout; /* rpc timeout */ Netmgt_thresh *threshold; /* event threshold */ char *group; /* group of statistics */ char *optstring; /* optstring to the agent */ char *key; /* key for table group */ u_int flags; /* restart */ { Netmgt_arg arg; struct rpcent *agent_rpc; /* rpc entry for the agent */ struct timeval *timestamp; /* request timestamp */ u_long agent_prog; /* agent's RPC program number */ u_long rendez_prog; /* rendez vous RPC program number */ NETMGT_DBG("requesting events \n"); /* declare managed object instance */ if (!netmgt_set_instance(target, group, key)) { NETMGT_DBG("set_instance failed for %s: %s\n", target, netmgt_sperror()); return (struct timeval *) NULL; } #ifndef SNMP_AGENT /* get the agent's RPC info */ agent_rpc = getrpcbyname(agentname); if (!agent_rpc) { NETMGT_DBG("can't get RPC program number for %s\n", agentname); return (struct timeval *) NULL; } agent_prog = agent_rpc->r_number;

#else



        agent_prog = SNMP_RPC_NUM;



        /* set SNMP arguments */



        set_snmp_args();



#endif



 



 



        /* pass optional arguments */



        if (optstring) {



                (void) strcpy(arg.name, NETMGT_OPTSTRING);



                arg.type = NETMGT_STRING;



                arg.length = strlen(optstring) + 1;



                arg.value = optstring;



                if (!netmgt_set_argument(&arg)) {



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



                            netmgt_sperror());



                        return (struct timeval *) NULL;



                }



        }



 



        /* set threshold */



        if (!netmgt_set_threshold(threshold)) {



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



                    netmgt_sperror());



                return (struct timeval *) NULL;



        }



 



        /* send the event report to the event dispatcher */



        rendez_prog = NETMGT_EVENT_PROG;



 



        /* start the event report request */



        timestamp = netmgt_request_events(agent_host, agent_prog,



            NETMGT_VERS, event_host, rendez_prog, NETMGT_VERS,



            count, interval, timeout, flags);



 



        if (!timestamp)



                NETMGT_DBG("Can't request event report: %s\n",netmgt_sperror()); 



        return timestamp;



 



}



 


 


 

/*



 *  request_data - send data report request to agent



 *      returns request timestamp if successful; otherwise NULL



 */



struct timeval *



request_data(count, interval, timeout, group, optstring, key, flags)



    u_int count;                /* report count */



    struct timeval interval;    /* reporting interval */



    struct timeval timeout;     /* rpc timeout */



    char *group;                /* group of statistics */



    char *optstring;            /* optstring to the  agent */



    char *key;                  /* key for table group */



    u_int flags;                /* restart */



{



 



        Netmgt_arg      arg;



        struct rpcent   *agent_rpc;     /* rpc entry for the agent */



        struct timeval  *timestamp;     /* request timestamp */



 



        u_long          agent_prog;     /* agent's RPC program number */



        u_long          rendez_prog;    /* rendez vous RPC program number */



 



        NETMGT_DBG("requesting data \n");



 



 



        /* declare managed object instance */



        if (!netmgt_set_instance(target, group, key)) {



                NETMGT_DBG("set_instance failed for %s: %s\n",



                    target, netmgt_sperror());



                return (struct timeval *) NULL;



        }



 



#ifndef SNMP_AGENT



        /* get the agent's RPC info */



        agent_rpc = getrpcbyname(agentname);



        if (!agent_rpc) {



                NETMGT_DBG("can't get RPC program number for %s\n", agentname);



                return (struct timeval *) NULL;



        }



        agent_prog = agent_rpc->r_number;





 


 

#else



        agent_prog = SNMP_RPC_NUM;



        /* set SNMP arguments */



        set_snmp_args();



#endif



 



        /* pass optional arguments */



        if (optstring) {



                (void) strcpy(arg.name, NETMGT_OPTSTRING);



                arg.type = NETMGT_STRING;



                arg.length = strlen(optstring) + 1;



                arg.value = optstring;



                if (!netmgt_set_argument(&arg)) {



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



                            netmgt_sperror());



                        return (struct timeval *) NULL;



                }



        }



 



 



        /* send the data report to the logger */



        rendez_prog = NETMGT_LOGGER_PROG;



 



        /* start the event report request */



        timestamp = netmgt_request_data(agent_host, agent_prog,



            NETMGT_VERS, event_host, rendez_prog, NETMGT_VERS,



            count, interval, timeout, flags);



 



        if (!timestamp)



                NETMGT_DBG("Can't request event report: %s\n",netmgt_sperror()); 



        return timestamp;



 



}





 


 

 

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