Using the Command-Line Version of Agent Builder
The command-line version of Agent Builder has the same two-step process as the graphical user interface. However, instead of entering information in the graphical user interface, you pass parameters to the commands scdscreate(1HA) and scdsconfig(1HA).
Follow these steps to use the command-line version of Agent Builder:
Use scdscreate to create a Sun Cluster resource type template for making an application highly available (HA) or scalable.
Use scdsconfigure to configure the resource type template that you created with scdscreate.
Change directories to the pkg subdirectory in the working directory.
Use the pkgadd(1M) command to install the packages that you created with scdscreate.
If you want, edit the generated source code.
Run the start script.
Directory Structure
Agent Builder creates a directory structure to hold all the files it generates for the target resource type. You specify (on the Create screen) the working directory. You must specify separate install directories for any additional resource types you develop. Under the working directory, Agent Builder creates a subdirectory whose name is a concatenation of the vendor name and the resource-type name (from the Create screen). For example, if you specify SUNW as the vendor name and create a resource type called ftp, Agent Builder creates a directory called SUNWftp under the working directory.
Under this subdirectory, Agent Builder creates and populates the directories listed in the following table.
Directory Name | Contents |
|---|---|
bin | For C output, contains the binary files compiled from the source files. For ksh output, contains the same files as the src directory. |
etc | Contains the RTR file. Agent Builder concatenates the vendor name and application name, separated by a period (.), to form the RTR filename. For example, if the vendor name is SUNW and the name of the resource type is ftp, the name of the RTR file is SUNW.ftp. |
man | Contains customized (man1m) man pages for the start, stop, and remove utility scripts. For example, startftp(1M), stopftp(1M), and removeftp(1M).
To view these man pages, specify the path with the man -M option. For example, man -M install_directory/SUNWftp/man removeftp. |
pkg | Contains the final package. |
src | Contains the source files that Agent Builder generates. |
util | Contains the start, stop, and remove utility scripts that Agent Builder generates. See Utility Scripts and man Pages. Agent Builder appends the application name to each of these script names; for example, startftp, stopftp, removeftp. |
Output
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:
rt_name_monitor_check
rt_name_monitor_start
rt_name_monitor_stop
rt_name_probe
rt_name_svc_start
rt_name_svc_stop
rt_name_update
rt_name_validate
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:
A header file (rt_name.h).
A source file (rt_name.c) containing code common to all methods.
An object file (rt_name.o) for the common code.
Source files (*.c) for each of the methods.
Object files (*.o) for each of the methods.
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:
Start script--registers the resource type, and creates the necessary resource groups and resources. It also creates the network address resources (LogicalHostname or SharedAddress) that enable the application to communicate with the clients on the network.
Stop script--stops and disables the resource.
Remove script--undoes the work of the start script, that is, it stops and removes the resources, resource groups, and the target resource type from the system.
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 |