This chapter describes SunPlexTM Agent Builder and the Cluster Agent module for Agent Builder, which are tools that automate the creation of resource types, or data services, to be run under the Resource Group Manager (RGM). A resource type essentially is a wrapper around an application to enable the application to run in a clustered environment under control of the RGM.
Agent Builder provides a screen-based interface for entering simple information about your application and the kind of resource type that you want to create. Based on the information you enter, Agent Builder generates the following software:
A set of source files—C, Korn shell (ksh), or GDS (generic data service)—for a failover or scalable resource type, corresponding to the resource type's method callbacks
A customized Resource Type Registration (RTR) file (if you generate C or Korn shell source)
Customized utility scripts for starting, stopping, and removing an instance (resource) of the resource type, as well as customized man pages documenting how to use each of these files
A Solaris package that includes the binaries (if you generate C source), an RTR file (if you generate C or Korn shell source), and the utility scripts
This section describes how to use Agent Builder, including tasks you must complete before you can use Agent Builder. This section also explains ways you can leverage Agent Builder after you have generated your resource type code.
Before using Agent Builder you must determine if your application meets the criteria to be made highly available or scalable. Agent Builder cannot perform this analysis, which is based solely on the runtime characteristics of the application. Analyzing the Application for Suitability provides more information about this topic.
Agent Builder may not always be able to create a complete resource type for your application, though in most cases Agent Builder provides at least a partial solution. For example, more sophisticated applications might require additional code that Agent Builder does not generate by default, such as code to add validation checks for additional properties or to tune parameters that Agent Builder does not expose. In these cases, you must make changes to the generated source code or to the RTR file. Agent Builder is designed to provide just this sort of flexibility.
Agent Builder places comments at certain points in the generated source code where you can add your own specific resource type code. After making changes to the source code, you can use the makefile that Agent Builder generates to recompile the source code and regenerate the resource type package.
Even if you write your entire resource type code without using any code generated by Agent Builder, you can leverage the makefile and structure that Agent Builder provides to create the Solaris package for your resource type.
Agent Builder requires no special installation. Agent Builder is included in the SUNWscdev package, which is installed by default as part of a standard Sun Cluster software installation (the Sun Cluster 3.1 10/03 Software Installation Guide contains more information). Before you use Agent Builder, verify the following information:
Java is included in your $PATH variable Agent Builder depends on Java (Java Development Kit version 1.3.1 or higher) and if Java is not in your $PATH, scdsbuilder returns with an error message.
You have installed the “Developer System Support” software group of Solaris 8 or higher.
The cc compiler is included in your $PATH variable Agent Builder uses the first occurrence of cc in your $PATH variable to identify the compiler with which to generate C binary code for the resource type. If cc is not included in $PATH, Agent Builder disables the option to generate C code (see Using the Create Screen.
You can use a different compiler with Agent Builder than the standard cc compiler. One way to do this is to create a symbolic link in $PATH from cc to a different compiler, such as gcc. Another way is to change the compiler specification in the makefile (currently, CC=cc) to the complete path for a different compiler. For example, in the makefile generated by Agent Builder, change CC=cc to CC=pathname/gcc. In this case you cannot run Agent Builder directly but must use the make and make pkg commands to generate data service code and a package.
The initial Sun Builder screen, as shown in the following figure, appears.
You can access Agent Builder through a command-line interface (see Using the Command-Line Version of Agent Builder) if the GUI version is not accessible.
Create—On this screen you provide basic information about the resource type to create, such as its name and the working directory (that is, the directory where you create and configure the resource type template) for the generated files. You also identify the kind of resource to create (scalable or failover), whether the base application is network aware (that is, if it uses the network to communicate with its clients), and the type of code (C, ksh, or GDS) to generate. For information on GDS (generic data service), see Chapter 10, Generic Data Services. You must complete the information in this screen, and select Create to generate the corresponding output, before you can display the Configure screen.
Configure—On this screen, you are required to provide a command to start the application. Optionally, you can provide commands to stop and probe the application. If you do not specify these commands, the generated output uses signals to stop the application and provides a default probe mechanism (see the description of the probe command in Using the Configure Screen). This screen also enables you to change the timeout values for each of these three commands.
If you launch Agent Builder from the working directory for an existing resource type, Agent Builder initializes the Create and Configure screens to the values of the existing resource type.
See Navigating Agent Builder if you have questions about how to use any of the buttons or menu commands on either of the Agent Builder screens.
The first step in creating a resource type is to fill out the Create screen, which appears when you launch Agent Builder. The following figure shows the Create screen after you enter information in the fields.
Vendor Name — A name to identify the vendor of the resource type. Typically, you specify the stock symbol of the vendor, but any name that uniquely identifies the vendor is valid. Use alphanumeric characters only.
Application Name — The name of the resource type. Use alphanumeric characters only.
Together, the vendor name and application name make up the full name of the resource type. The full name must not exceed nine characters.
Working Directory — The directory under which Agent Builder creates a directory structure to contain all the files created for the target resource type. You can create only one resource type in any one working directory. Agent Builder initializes this field to the path of the directory from which you launched Agent Builder, though you can type a different name or use the Browse button to locate a different directory.
Under the working directory, Agent Builder creates a subdirectory with the resource-type name. For example, if SUNW is the vendor name and ftp is the application name, then Agent Builder names this subdirectory SUNWftp.
Agent Builder places all the directories and files for the target resource type under this subdirectory (see Directory Structure).
Scalable or Failover — Specify whether the target resource type will be failover or scalable.
Network Aware — Specify whether the base application is network aware; that is, if it uses the network to communicate with its clients. Check the box to specify network aware; leave it blank to specify non-network aware. Korn shell code requires that the application be network aware. Therefore, Agent Builder checks this box, and grays it out if you check the ksh or the GDS button.
C, ksh — Specify the language of the generated source code. Although these options are mutually exclusive, with Agent Builder you can create a resource type with ksh generated code and then reuse the same information to create C generated code (see Cloning an Existing Resource Type).
GDS — Specifies that this service is a generic data service. See Chapter 10, Generic Data Services for information about creating and configuring a generic data service.
If the cc compiler is not in your $PATH, Agent Builder grays out the C option button and puts a check in the ksh button. To specify a different compiler, see the note at the end of Installing and Configuring Agent Builder.
After you have entered the required information, click the Create button. The Output Log at the bottom of the screen shows the actions that Agent Builder is taking. You can use the Save Output Log command in the Edit menu to save the information in the output log.
When finished, Agent Builder displays either a success message or a warning message that it was unable to complete this step, and you should check the output log for details.
If Agent Builder completes successfully, you can Click the Next button to bring up the Configure screen, which enables you to finish generating the resource type.
Although generation of a complete resource type is a two-step process, you can exit Agent Builder after completing the first step (create) without losing the information you have entered or the work that Agent Builder has completed (see Reusing Completed Work).
The Configure screen, shown in the following figure, appears after Agent Builder finishes creating the resource type and you select the Next button on the Create screen. You cannot access the Configure screen before the resource type has been created.
Start Command — The full command line that can be passed to any UNIX shell to start the base application. It is required that you specify this command. You can type the command in the field provided or use the Browse button to locate a file containing the command to start the application.
The complete command line must include everything necessary to start the application, such as hostnames, port numbers, a path to configuration files, and so on. If your application requires a hostname to be specified on the command line, you can use the $hostnames variable that Agent Builder defines (see Using the Agent Builder $hostnames Variable).
Do not enclose the command in double quotes (““).
If the base application has multiple independent process trees, each of which is started with its own tag under PMF control, you cannot specify a single command. Rather, you must create a text file with individual commands to start each process tree, and specify the path to this file in the Start Command text field. See Creating Resource Types With Multiple Independent Process Trees, which lists some special characteristics this file requires to work properly.
Stop Command — The full command line that can be passed to any UNIX shell to stop the base application. You can type the command in the field provided or use the Browse button to locate a file containing the command to stop the application. If your application requires a hostname to be specified on the command line, you can use the $hostnames variable defined by Agent Builder (see Using the Agent Builder $hostnames Variable).
This command is optional. If you do not specify a stop command, the generated code uses signals (in the Stop method) to stop the application, as follows.
The Stop method sends SIGTERM to stop the application and waits for 80% of the timeout value for the application to exit.
If the SIGTERM signal is unsuccessful, the Stop method sends SIGKILL to stop the application and waits for 15% of the timeout value for the application to exit.
If SIGKILL is unsuccessful the Stop method exits unsuccessfully (the remaining 5% of the timeout value is considered overhead).
Be certain the stop command does not return before the application has stopped completely.
Probe Command — A command that can be run periodically to check the health of the application and return an appropriate exit status between 0 (success) and 100 (complete failure). This command is optional. You can type the complete path to the command or use the Browse button to locate a file that contains the commands to probe the application.
Typically, you specify a simple client of the base application. If you do not specify a probe command, the generated code simply connects to and disconnects from the port used by the resource, and if that succeeds, declares the application healthy. You can only use a probe command with network aware applications. Agent Builder always generates a probe command, but disables it for non-network aware applications.
If your application requires that you specify a hostname on the probe command line, you can use the $hostnames variable that Agent Builder defines (see Using the Agent Builder $hostnames Variable).
Timeout — (for each command)—A timeout value (in seconds) for each command. You can specify a new value or accept the default value Agent Builder provides (300 seconds for start and stop, 30 seconds for probe).
For many applications, specifically network-aware applications, the hostname on which the application listens and services customer requests must be passed to the application on the command line. Therefore, in many cases, hostname is a parameter you must specify for start, stop, and probe commands for the target resource type (on the Configure screen). However, the hostname on which an application listens is cluster specific—it is determined when the resource is run on a cluster and cannot be determined when Agent Builder generates your resource type code.
To solve this problem, Agent Builder provides the $hostnames variable that you can specify on the command line for the start, stop, and probe commands. You specify the $hostnames variable exactly as you would an actual hostname, for example:
/opt/network_aware/echo_server -p port_no -l $hostnames
When a resource of the target resource type is run on a cluster, the LogicalHostname or SharedAddress hostname configured for that resource (in the Network_resources_used resource property of the resource) is substituted for the value of the $hostnames variable.
If you configure the Network_resources_used property with multiple hostnames, the $hostnames variable contains all of them separated by commas.
Agent Builder can create resource types for applications that have more than one independent process tree. These process trees are independent in the sense that PMF monitors and starts them individually. PMF starts each process tree with its own tag.
Agent Builder enables you to create resource types with multiple independent process trees only if the generated source code that you specify is C. You cannot use Agent Builder to create these resource types for ksh or for GDS. To create these resource types for ksh or for GDS, you must write the code by hand.
In the case of a base application with multiple independent process trees, you cannot specify a single command line to start the application. Rather, you must create a text file, with each line specifying the full path to a command to start one of the application's process trees. This file must not contain any blank lines. You specify this text file in the Start Command text field in the Configure screen.
You must also make certain this text file does not have execute permissions. This enables Agent Builder to distinguish this file, whose purpose is to start multiple process trees, from a simple executable script containing multiple commands. If this text file is given execute permissions, the resources would come up fine on a cluster, but all the commands would be started under one PMF tag, precluding the possibility of monitoring and restarting the process trees individually by PMF.
You can clone an existing resource type created with Agent Builder.
You can edit the source code Agent Builder generates and then recompile the code to create a new package.
Load an existing resource type into Agent Builder. You can do this in either of two ways:
Change the working directory on the Create screen.
You must use the Browse button to select a directory—typing a new directory name is not sufficient. After you select a directory, Agent Builder re-enables the Create button.
You might use this procedure to change the type of code generated for the resource type. For example, if you initially create a ksh version of a resource type but find over time that you require a C version, you can load the existing ksh resource type, change the language for the output to C, and then have Agent Builder build a C version of the resource type.
Create the cloned resource type.
Select Create to create the resource type. Select Next to bring up the Configure screen. Select Configure to configure the resource type and then Cancel to finish.
To keep the process of creating a resource type simple, Agent Builder limits the number of inputs, which necessarily limits the scope of the generated resource type. Therefore, to add more sophisticated features, such as validation checks for additional properties, or to tune parameters Agent Builder does not expose, you need to modify the generated source code or the RTR file.
The source files are in the install_directory/rt_name/src directory. Agent Builder embeds comments in the source code at places you can add code. These comments are of the form (for C code):
/* User added code -- BEGIN vvvvvvvvvvvvvvv */ /* User added code -- END ^^^^^^^^^^^^^^^ */
These comments are identical in Korn shell code, except they use the pound sign (#) to begin the comment line.
For example, rt_name.h declares all the utility routines that the different programs use. At the end of the list of declarations are comments that enable you to declare additional routines you might have added to any of your code.
Agent Builder also generates the makefile in the install_directory/rt_name/src directory, with appropriate targets. Use the make command to recompile the source code, and the make pkg command to regenerate the resource type package.
The RTR file is in the install_directory/rt_name/etc directory. You can edit the RTR file with a standard text editor (see Setting Resource and Resource Type Properties for more information about the RTR file and Appendix A, Standard Properties for information about properties).
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.
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.
For C output, contains the binary files compiled from the source files. For ksh output, contains the same files as the src directory.
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.
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.
Contains the final package.
Contains the source files that Agent Builder generates.
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.
This section describes the output that Agent Builder generates.
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.
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.
Refer to the rt_callbacks(1HA) man page for specific information on each of these methods.
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.
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.
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.
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
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.
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.
Run the removert_name script from one node of the cluster before running pkgrm from any node.
Run pkgrm from one node of the cluster, which takes care of all necessary clean up, then run pkgrm from the remaining nodes, simultaneously if necessary.
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.
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.
Typing information in a field.
Browsing your directory structure and selecting a file or directory.
Checking one of a set of mutually exclusive radio buttons—for example, Scalable or Failover.
Checking an on/off box. For example, checking Network Aware identifies the base application as network aware, while leaving this box blank identifies a non-network aware application.
The buttons at the bottom of each screen enable you to complete the task, move to the next or previous screen, or exit Agent Builder. Agent Builder highlights or grays out these buttons as appropriate.
For example, when you have filled in the fields and checked the desired options on the Create screen, click the Create button at the bottom of the screen. The Previous and Next buttons are grayed out because no previous screen exists and you cannot go to the next step before you complete this one.
Agent Builder displays progress messages in the output log area at the bottom of the screen. When Agent Builder finishes, it displays a success message, or a warning to look at the output log. The Next button is highlighted, or if this is the last screen, only the Cancel button is highlighted.
You can select Cancel at any time to exit Agent Builder.
When you click Browse, a screen similar to the following screen appears:
Double click on a folder to open it. When you highlight a file, its name appears in the File name box. Click Select when you have located and highlighted the appropriate file.
If you are browsing for a directory, highlight it and select the Open button. If there are no subdirectories, Agent Builder closes the browse window and places the name of the directory you highlighted in the appropriate field. If this directory has subdirectories, click the close button to close the browse window and return to the previous screen. Agent Builder places the name of the directory you highlighted in the appropriate field.
This icon moves you up one level in the directory tree.
This icon returns you to the home folder.
This icon creates a new folder under the currently selected folder.
This icon, for toggling between different views, is reserved for future use.
Load Resource Type — Load an existing resource type. Agent Builder provides a browse screen from which you select the working directory for an existing resource type. If a resource type exists in the directory from which you launch Agent Builder, Agent Builder automatically loads the resource type. The Load Resource Type command allows you to launch Agent Builder from any directory and select an existing resource type to use as a template for creating a new resource type (see Cloning an Existing Resource Type).
Exit — Exit Agent Builder. You can also exit by clicking Cancel on the Create or Configure screen.
Clear Output Log — Clears the information from the output log. Each time you select Create or Configure, Agent Builder appends status messages to the output log. If you are engaged in an iterative process of making changes to your source code and regenerating output in Agent Builder and want to segregate the status messages, you can save and clear the log file before each use.
Save Log File — Save the log output to a file. Agent Builder provides a browse screen that enables you to choose the directory and specify a filename.
The Cluster Agent module for Agent Builder is a NetBeansTM module. The Cluster Agent module enables users of the SunTM ONE Studio product to create resource types, or data services, for the Sun Cluster software through an integrated development environment. The Cluster Agent module provides a screen-based interface for describing the kind of resource type that you want to create.
The Sun ONE Studio documentation contains information about how to set up, install, and use the Sun ONE Studio product.
The Cluster Agent module is installed when you install the Sun Cluster software. The Sun Cluster installation tool places the Cluster Agent module file scdsbuilder.jar in /usr/cluster/lib/scdsbuilder. To use the Cluster Agent module with the Sun ONE Studio software, you need to create a symbolic link to this file.
The Sun Cluster and Sun ONE Studio products and JavaTM 1.4 must be installed and available to the system on which you intend to run the Cluster Agent module.
Do you want to enable all users or only yourself to use the Cluster Agent module?
To enable all users, become superuser or assume an equivalent role and create the symbolic link in the global module directory:
# cd /opt/s1studio/ee/modules # ln -s /usr/cluster/lib/scdsbuilder/scdsbuilder.jar
If you installed the Sun ONE Studio software in a directory other than /opt/s1studio/ee, substitute this directory path with the path that you used.
To enable only yourself, create the symbolic link in your modules subdirectory:
% cd ~your-home-dir/ffjuser40ee/modules % ln -s /usr/cluster/lib/scdsbuilder/scdsbuilder.jar
Stop and restart the Sun ONE Studio software.
From the Sun ONE Studio File menu, select New, or click this icon on the toolbar:
The New Wizard screen appears.
In the Select a Template window, scroll down (if necessary) and click the key next to the Other folder:
The Other menu opens.
From the Other menu, select Sun Cluster Agent Builder and click Next.
The Cluster Agent module for Sun One Studio starts. The first New Wizard - Sun Cluster Agent Builder screen appears.
Use the Cluster Agent module as you would the Agent Builder software. The interfaces are identical. For example, the following figures show that the Create screen in the Agent Builder software and the first New Wizard - Sun Cluster Agent Builder screen in the Cluster Agent module contain the same fields and selections.
In the Cluster Agent module, the resource type is created and configured only after you click Finish on the second New Wizard - Sun Cluster Agent Builder screen. The resource type is not created when you click Next on the first New Wizard - Sun Cluster Agent Builder screen.
In Agent Builder, the resource type is immediately created when you click Create on the Create screen and configured when you click Configure on the Configure screen.
The information that appears in the Output Log window in Agent Builder appears in a separate output window in the Sun ONE Studio product.