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 preferrable and recommended for the following reasons:

• Dynamically linked programs save disk space and main memory because they share library code at runtime.
• Shared library code can be enhanced without having to relink the applications that use it.
• Dynamically linked applications provide better compatibility. In order to ensure that your applications are compatible with future releases of the Site/SunNet/Domain Manager product, dynamic linking must be used.

13.1.2.1 Dynamic Linking

Dynamic linking, as shown in the sample below, is the preferrable 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:

• /usr/snm/lib/libnetmgt_db.so
• /usr/snm/lib/libnetmgt.so

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

• /opt/SUNWconn/snm/lib/libnetmgt_db.so
• /opt/SUNWconn/snm/lib/libnetmgt.so

---

Note - If you link with the libnetmgt_db.so library, the libnetmgt.so library must also be used, with libnetmgt_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:

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

· /usr/snm/lib/libnetmgt_db.a
· /usr/snm/lib/libnetmgt.a

• If you have installed the Solaris 2.4 version of this product:

· /opt/SUNWconn/snm/lib/libnetmgt_db.a
· /opt/SUNWconn/snm/lib/libnetmgt.a

---

Note - If you link with the libnetmgt_db.a library, the libnetmgt.a library must also be used, with libnetmgt_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.2Test 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.

• Look at the values in the logger file, and compare them against the values that should be returned. In other words, make sure the agent is reporting correct values.
• Test the behavior of the agent with various count and interval values (use the -c and -i options). Recommended values:

Table 13-1

Count	Interval	Interpretation
0	0	Forever. Agent picks the interval.
1	0	Once. Interval doesn't matter.
5	0	Five times. Agent picks the interval.
0	1	Forever, one second apart.
0	10	Forever, ten seconds apart.
5	10	Five times, ten seconds apart.

• Ask for group names (use the -g option) the agent doesn't know about.
• Ask for an event report (use the -n, -r, and -e options) for attributes the agent doesn't know about.

• Test the agent with both bad and good keys (use the -k option) and with no key. Make sure the agent can return the first row and the last row of the table (in different reports).
• If the agent reports tables, see what is returned when only one row of the table has an event occur in it. What is returned when more than one row has an event occur? Test event reports for the first and last rows.
• Test the agent with various options (use the -o option).
• Try various target names (use the -t option) that are the same and different as the name of the host where the agent is running.
• Try to get the agent to return each possible error code defined in the agentErrors record in the agent schema.
• If the agent does extra processing when an event occurs, you should test it.

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,

• Copy your agent to the directory where the other Site/SunNet/Domain Manager agents are installed. If no Site/SunNet/Domain Manager agents have been installed on the system, first run the utility getagents.
• Add the following entry to snm.conf:

na.<my-agent-name>0

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.

• Add an entry for your agent to /etc/inetd.conf to allow inetd to automatically start your agent when a manager sends a request to your agent. Here's a summary of the inetd.conf(5) file format.

na.<agent-name>/10 tli rpc/udp wait root <agent program absolute pathname> <agent-name> <arguments>

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

• Force inetd to reread its configuration file by sending it a SIGHUP signal:

host% kill -HUP <inetd's process ID>

13.3.2 Update the MDB

On the management station (where the Console runs),

• Copy your agent schema to where the agents and schema files have been installed. This directory is defined by the schema keyword in snm.conf. By default, agent schema files are in the agents directory.
• Add the agent or proxy sub-record to the MDB element cluster record. See the Administration Guide for more information.
• Start the Console with the -i option described in snm(1). Your agent name will appear in the glyph menus for each element where your agent is defined. It will also appear in the Properties sheet for every element, where you can optionally specify what systems can be managed by your agent.

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 Guide to request a permanent RPC number.