[Top] [Prev] [Next] [Bottom]

13 - Testing and Integration

This chapter describes how to:

13.1 Building Your Program

When you compile your agent, you must include a Site/SunNet/Domain Manager header file in each of your source code files and link your object modules with a Site/SunNet/Domain Manager library.

13.1.1 Header Files

The header file you need to include in each source code file is netmgt.h. This file includes the other header files, located in the /usr/snm/include/netmgt directory for Solaris 1.x installations or /opt/SUNWconn/snm/include/netmgt for the Solaris 2.x version. These files declare Site/SunNet/Domain Manager functions and data structures. To simplify portability, include this file in your source code by adding the line:

 

#include <"netmgt/netmgt.h">
 

at the top of the file, and specifying the search path to this header file using the cpp(1) -I switch in your agent Makefile.

13.1.2 Static and Dynamic Linking

You can link your application with libnetmgt_db and libnetmgt either statically or dynamically. Dynamically is preferable and recommended for the following reasons:

13.1.2.1 Dynamic Linking

 Dynamic linking, as shown in the sample below, is the preferable and recommended linking method. When you dynamically link your program, you can include the following libnetmgt libraries:

If you have installed the Solaris 1.1.1 version of this product:

If you have installed the Solaris 2.4 version of this product:
NOTE - If you link with the libnetmgt_db.so library, the libnetmgt.so library must also be used, wit hlibnetmgt_db.so being listed before libnetmgt.so in the command line. The libnetmgt.so library may be used without the libnetmgt_db.so library.

13.1.2.2 Dynamic Linking for the Solaris 2.4 Environment

 To link with the libraries provided with the Solaris 2.4 version of this product, you must link with the network services library (libnsl) and the internationalization library (libintl ). To dynamically link your application, follow this format:

 

host% cc myprog.c -o myprog -R /opt/SUNWconn/snm/lib -L /opt/SUNWconn/snm/lib -lnetmgt_db

-lnetmgt -lnsl -lintl
  

Since the Solaris 2.x version of this product does not make links in /usr/lib, all Site/SunNet/Domain Manager applications should link with the -R option, as shown above. This avoids forcing the user to set the LD_LIBRARY_PATH variable at runtime.

13.1.2.3 Dynamic Linking for the Solaris 1.1 Environment

To dynamically link your application with the libraries provided with the Solaris 1.1.1 version of this product, follow this format:

 

host% cc myprog.c -o myprog -L /usr/snm/lib -lnetmgt_db -lnetmgt -lnsl
  

13.1.3 Static Linking

When you statically link your program, you can include the following libnetmgt libraries:

NOTE - If you link with the libnetmgt_db.a library, the libnetmgt.a library must also be used, wit hlibnetmgt_db.a being listed before libnetmgt.a in the command line. The libnetmgt.a library may be used without the libnetmgt_db.a library.

13.1.3.1 Static Linking for the Solaris 2.4 Environment

 To link with the libraries provided with the Solaris 2.4 version of this product, you must link with the network services library (libnsl) and the internationalization library (libintl ). To statically link your application, follow this format:

 

host% cc myprog.c -o myprog -L /opt/SUNWconn/snm/lib -Bstatic -lnetmgt_db -lnetmgt -lnsl

-lintl -Bdynamic -ldl
 

If you use the static method, you must specifically link in libdl.

13.1.3.2 Static Linking for the Solaris 1.1.1 Environment

To statically link your application with the libraries provided for the Solaris 1.1.1 version of this product, follow this format:

 

host% cc myprog.c -o myprog -L /usr/snm/lib -Bstatic -lnetmgt_db -lnetmgt -lnsl

-lintl -Bdynamic -ldl
 

If you use the static method, you must specifically link in libdl.

13.1.4 API Differences from the 2.0 Release

Two API functions in the SunNet Manager 2.1 and later releases differ from the SunNet Manager 2.0 release. Arguments to the reap and shutdown functions, specified as arguments to the netmgt_init_rpc_agent() function, have been simplified, as shown in the definitions below.

SunNet Manager 2.0 reap function:
Code  Example  5 
reaper(sig, code, scp, addr, child_pid, status, rusage)
   
int sig;		/* signal number caught */
   
 int code;		/* additional signal detail */
   
 struct sigcontext *scp;			/* saved process context */
   
 char *addr;		/* additional address info */
   
 int child_pid;		/* child's pid */
   
 union wait *status;		/* child's return status */
   
struct rusage *rusage;		/* child resource usage */
  

SunNet Manager 2.1, 2.2, 2.2.3, and 2.3 reap function:
Code  Example  6
reaper(sig, child_pid, status, rusage)

 

int sig; /* signal number caught */

 

int child_pid; /* child's pid */

 

int *status; /* child's return status */

 

struct rusage *rusage; /* child resource usage */

 


SunNet Manager 2.0 shutdown function:
Code  Example  7
shutdown(sig, code, scp, addr)

 

int sig; /* signal caught */

 

int code; /* additional signal info */

 

struct sigcontext; /* saved process context */

 

char *addr; /* additional address info */

 


SunNet Manager 2.1, 2.2, 2.2.3, and 2.3 shutdown function:
Code  Example  8
shutdown_agent (sig)

 

int sig; /* signal caught */

 


13.1.9 Assign an Agent Name

To communicate with an agent, Site/SunNet/Domain Manager services map the agent name to a unique RPC program number. Given the agent RPC program number and the name of the host where the agent resides, a Site/SunNet/Domain Manager application can send requests directly to the agent.

Each agent name must be unique within an NIS/NIS+ (or local host) namespace. Uniqueness is required to ensure each agent name is mapped to a unique RPC program number. This means that if the NIS/NIS+ is running, the agent name must be unique within the NIS domain's rpc.bynumber map. If NIS/NIS+ is not running, the agent name must be unique within the local /etc/rpc file.

When you pick a name for your agent you should verify the name is unique. If NIS is running, type the following from the command line: 


host% ypcat rpc.bynumber | grep <my-agent-name>
 

If NIS is not running, type the following:

 

host% grep <my-agent-name> /etc/rpc
 

If you don't see a match, your name is unique.

13.1.10 Register the Agent RPC Program Number

Once you have a name for your agent, assign your agent an RPC program number. While you are developing your agent, you can use a temporary RPC program number, which must be unique within your rpc.bynumber map (or the rpc file). You should assign a number from the range intended for debugging new programs, which extends from 0x20000000 to 0x3fffffff.

Before picking your temporary RPC number, verify its uniqueness: 


host% ypcat rpc.bynumber | grep <my-RPC-number>
 

or if you are not running NIS, enter the following: 


host% grep <my-RPC-number> /etc/rpc
  

Again, if you don't see a match, your number is unique.

The RPC version number is also required to uniquely identify an agent service. For this release, all agents should use the RPC version number NETMGT_VERS, as defined in the header file netmgt_rpc.h.

Once you have your agent RPC program name, number and version, ask your system administrator to add the information to the NIS rpc.bynumber map (or rpc file).

After you have completed your agent and want to share it with others, ask Sun Microsystems to assign you a permanent RPC number. Refer to Chapter 3 of the SunOS Remote Procedure Call Programming Guide for instructions.

13.2 Test the Agent

You need to start the logger na.logger from the command line before you start the generic manager snm_cmd. On a SunOS4.x machine, enter the following:

 

host% /usr/snm/agents/na.logger
 

If you've installed this product on a Solaris 2.x machine, the command would be the following:

 

host% /opt/SUNWconn/snm/agents/na.logger
 

The logger writes all reports to the log file specified by the "monitor-log" keyword in the snm.conf file. You can change the path name of the log file by editing the line associated with the keyword.

The logger registers with the local event dispatcher to receive event reports. When your agent sends an event report, it is sent to the event dispatcher. The event dispatcher logs a copy in the file specified by the "event-log" keyword in snm.conf. The event dispatcher then sends the report to the logger. The logger writes it in its own file.

The snm.conf file is located in the /etc directory if you've installed this product on a Solaris 1.1 machine; it is located in /etc/opt/SUNWconn/snm for Solaris 2.x installations.

13.2.1 snm_cmd

snm_cmd is a generic manager for Site/SunNet/Domain Manager agents. You can test agents without having to write a dedicated manager or running the Console.

When you test your agent using snm_cmd , your agent sends reports to the logger. The logger stores them in the log file on your local host. See snm.logfile(5) for the format of the file.

When testing and debugging your agent, start your agent from the command line and tell it to set the global debugging variable netmgt_debug to a value between one and three so you can see agent debugging messages on your screen. All the supplied Site/SunNet/Domain Manager agents allow netmgt_debug to be set via the -d command line switch. Your agent should do the same. 


host% myagent -d 3
  

When you start your agent without asking it to start debugging (when netmgt_debug is set to zero) from the command line or from inetd, you will not see debugging messages on your screen.

13.2.2 Verifying the Agent Schema

Once you have written your agent schema, use the -v option of snm_cmd to verify the group and attribute names and values defined in the agent schema match those in your agent: 


host% snm_cmd -v -f myagent.schema
  

13.2.3 Test the Agent

The verification check done by snm_cmd -v can give you a high degree of confidence that your agent and schema match, and that your agent is at least reporting information. However, there are several tests you should do yourself. Use snm_cmd to do your testing. These are recommended tests, and may be done in any order.

13.3 Console Integration

Once you are satisfied your agent is performing correctly, install it on the systems where you want it to run, then integrate it with the Console's Management Database (MDB).

13.3.1 Install the Agent

For each system where you want your agent to run,

This will set your agent security level on this host to zero (no security checking). Optionally, you can set your agent to any value between 1 and 5. See the Administration Guide for information on security.
For example, the entry for the iproutes agent (on a Solaris 2.x machine) is:

 

na.hostmem/10 tli rpc/udp wait root /opt/SUNWconn/snm/agents/na.iproutes na.iproutes
  

13.3.2 Update the MDB

On the management station (where the Console runs), For complete details on the operation of the Console and the MDB, see the Administration Guide.

13.4 Summary

You have completed the testing and integration of your agent. Make sure you document your agent so others know how to use it, or you know how to use it six months from now.

If you are going to distribute the agent outside your site, make sure you first change your agent's RPC number to a permanent one assigned by Sun Microsystems. Refer to Chapter 3 of the SunOS Remote Procedure Call Programming Guideto request a permanent RPC number.


[Top] [Prev] [Next] [Bottom]

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