Sun Cluster 3.1 10/03 Data Services Developer's Guide


This section describes the output that Agent Builder generates.

Source and Binary Files

The Resource Group Manager (RGM)—which manages resource groups and ultimately, resources on a cluster—works on a callback model. When specific events happen, such as a node failure, the RGM calls the resource type's methods for each of the resources running on the affected node. For example, the RGM calls the Stop method to stop a resource running on the affected node and then calls the resource's Start method to start the resource on a different node. (See RGM Model, Callback Methods and the rt_callbacks(1HA) man page for more information on this model).

To support this model, Agent Builder generates (in the install_directory/rt_name/bin directory) eight executable programs (C) or scripts (ksh) that serve as callback methods.

Note –

Strictly speaking, the rt_name_probe program, which implements a fault monitor, is not a callback program. The RGM does not directly call rt_name_probe but rather calls rt_name_monitor_start and rt_name_monitor_stop, which start and stop the fault monitor by calling rt_name_probe.

The eight methods that Agent Builder generates are:

Refer to the rt_callbacks(1HA) man page for specific information on each of these methods.

In the install_directory/rt_name/src directory (C output), Agent Builder generates the following files:

Agent Builder links the rt_name.o file to each of the method .o files to create the executables in the install_directory/rt_name/bin directory.

For ksh output, the install_directory/rt_name/bin and install_directory/rt_name/src directories are identical—each contains the eight executable scripts corresponding to the seven callback methods and the PROBE method.

Note –

The ksh output includes two compiled utility programs (gettime and gethostnames) that certain of the callback methods require for getting the time and probing.

You can edit the source code, run the make command to recompile the code, and when you are finished, run the make pkg command to generate a new package. To support making changes to the source code, Agent Builder embeds comments in the source code at appropriate locations to add code. See Editing the Generated Source Code.

Utility Scripts and man Pages

Once you have generated a resource type and installed its package on a cluster, you must still get an instance (resource) of the resource type running on a cluster, generally by using administrative commands or SunPlex Manager. However, as a convenience, Agent Builder generates a customized utility script for this purpose (the start script) as well as scripts for stopping and removing a resource of the target resource type. These three scripts, located in the install_directory/rt_name/util directory, do the following:

Note –

You can only use the remove script with a resource started by the corresponding start script because these scripts use internal conventions to name resources and resource groups.

Agent Builder names these scripts by appending the application name to the script names. For example, if the application name is ftp, the scripts are called startftp, stopftp, and removeftp.

Agent Builder provides man pages in the install_directory/rt_name/man/man1m directory for each of the utility scripts. You should read these man pages before you launch these scripts because they document the parameters you need to pass to the script.

To view these man pages, specify the path to this man directory using the -M option with the man command. For example, if SUNW is the vendor and ftp is the application name, use the following command to view the startftp(1M) man page:

man -M install_directory/SUNWftp/man startftp

The man page utility scripts are also available to the cluster administrator. When an Agent Builder-generated package is installed on a cluster, the man pages for the utility scripts are placed in the /opt/rt_name/man directory. For example, use the following command to view the startftp(1M) man page:

man -M /opt/SUNWftp/man startftp

Support Files

Agent Builder places support files, such as pkginfo, postinstall, postremove, and preremove, in the install_directory/rt_name/etc directory. This directory also contains the resource type registration (RTR) file, which declares resource and resource type properties available for the target resource type and initializes property values at the time a resource is registered with a cluster (see Setting Resource and Resource Type Properties for more information). The RTR file is named as vendor_name.resource_type_name—for example, SUNW.ftp.

You can edit this file with a standard text editor and make changes without recompiling your source code. However, you must rebuild the package with the make pkg command.

Package Directory

The install_directory/rt_name/pkg directory contains a Solaris package. The name of the package is a concatenation of the vendor name and the application name, for example, SUNWftp. The Makefile in the install_directory/rt_name/src directory supports creation of a new package. For example, if you make changes to the source files and recompile the code, or make changes to the package utility scripts, use the make pkg command to create a new package.

When you remove a package from a cluster, the pkgrm command can fail if you attempt to run the command from more than one node simultaneously. You can solve this problem in one of two ways:

If pkgrm fails because you attempt to run it simultaneously from multiple nodes, run it again from one node then run it from the remaining nodes.

The rtconfig File

If you generate C or ksh source code, in the working directory, Agent Builder generates a configuration file rtconfig, which contains the information that you entered on the Create and Configure screens. If you launch Agent Builder from the working directory for an existing resource type (or load an existing resource type using the File menu Load Resource Type command), Agent Builder reads the rtconfig file and fills in the Create and Configure screens with the information that you provided for the existing resource type. This feature is useful if you want to clone an existing resource type (see Cloning an Existing Resource Type.