Chapter 9 Sun Cluster Agent Builder

This chapter describes Sun Cluster Agent Builder and the Cluster Agent module for Agent Builder. Both tools automate the creation of resource types, or data services, to be run under the control of the Resource Group Manager (RGM). A resource type is a wrapper around an application that enables that application to run in a clustered environment, under control of the RGM.

This chapter covers the following topics:

• Agent Builder Overview

• Before You Use Agent Builder

• Using Agent Builder

• Directory Structure That Agent Builder Creates

• Agent Builder Output

• Cluster Agent Module for Agent Builder

Agent Builder Overview

Agent Builder provides a graphical user interface (GUI) for specifying information about your application and the kind of resource type that you want to create. Agent Builder supports network-aware applications and nonnetwork-aware applications. Network-aware applications use the network to communicate with clients. Nonnetwork-aware applications are standalone applications.

If the GUI version of Agent Builder is not accessible, you can access Agent Builder through a command-line interface. See How to Use the Command-Line Version of Agent Builder.

Based on the information you specify, Agent Builder generates the following software:

• A set of C, Korn shell (ksh), or generic data service (GDS) source files for a failover or scalable resource type that corresponds to the resource type's method callbacks. These files are intended for both network-aware (client-server model) and nonnetwork-aware (clientless) applications.

• A customized Resource Type Registration (RTR) file (if you generate C or Korn shell source code).

• Customized utility scripts for starting, stopping, and removing an instance (resource) of the resource type, as well as customized man pages that document how to use each one of these files.

• A Solaris package that includes the binaries (if you generate C source code), an RTR file (if you generate C or Korn shell source code), and the utility scripts.

Agent Builder also enables you to generate a resource type for an application that has multiple independent process trees that the Process Monitor Facility (PMF) must monitor and restart individually.

Before You Use Agent Builder

Before you use Agent Builder, you need to know how to create resource types with multiple independent process trees.

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 the PMF monitors and starts them individually. The 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 or GDS. You cannot use Agent Builder to create these resource types for the Korn shell. To create these resource types for the Korn shell, you must manually write the code.

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 empty lines. You specify this text file in the Start Command text field on the Agent Builder Configure screen.

Ensuring that this file does not have execute permissions enables Agent Builder to distinguish this file. The purpose of this file is to start multiple process trees from a simple executable script that contains multiple commands. If this text file is given execute permissions, the resources come up with no problems or errors on a cluster. However, all the commands are started under one PMF tag. As a result, the PMF is unable to monitor and restart the process trees individually.

Using Agent Builder

This section describes how to use Agent Builder. In addition, this section includes tasks that you must complete before you can use Agent Builder. This section also explains ways that you can take advantage of Agent Builder after you generate your resource type code.

The following topics are discussed:

• Analyzing the Application

• Installing and Configuring Agent Builder

• Agent Builder Screens

• Starting Agent Builder

• Navigating Agent Builder

• Using the Create Screen

• Using the Configure Screen

• Using the Agent Builder Korn Shell-Based $hostnames Variable

• Using Property Variables

• Reusing Code That You Create With Agent Builder

• How to Use the Command-Line Version of Agent Builder

Analyzing the Application

Before using Agent Builder, you must determine whether the application that you intend to make highly available or scalable meets the required criteria. 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 might not always be able to create a complete resource type for your application. However, 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. Examples of additional code include code that adds validation checks for additional properties or that tunes 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 kind of flexibility.

Agent Builder places comments at particular points in the generated source code where you can add your own 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 that is generated by Agent Builder, you can use the makefile and structure that Agent Builder provides to create the Solaris package for your resource type.

Installing and Configuring Agent Builder

Agent Builder requires no special installation. Agent Builder is included in the SUNWscdev package, which is installed by default when you install the Sun Cluster software. The Sun Cluster Software Installation Guide for Solaris OS contains more information.

Before you use Agent Builder, verify the following requirements:

• The Java runtime environment is included in your $PATH variable. Agent Builder depends on the Java Development Kit, at least Version 1.3.1. If the Java Development Kit is not included in your $PATH variable, the Agent Builder command (scdsbuilder) returns and displays an error message.

• You have installed the Developer System Support software group of the Solaris 9 OS or Solaris 10 OS.

• 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. To use a different compiler, create a symbolic link in $PATH from cc to a different compiler, such as gcc. Or, change the compiler specification in the makefile (currently, CC=cc) to the complete path for a different compiler. For example, in the makefile that is generated by Agent Builder, change CC=cc to CC=pathname/gcc. In this case, you cannot run Agent Builder directly. Instead, you must use the make and make pkg commands to generate data service code and the package.

Agent Builder Screens

Agent Builder is a two-step wizard with a corresponding screen for each step.

Agent Builder provides the following two screens to guide you through the process of creating a new resource type:

1. Create screen. On this screen, you provide basic information about the resource type to create, such as its name and the working directory for the generated files. The working directory is where you create and configure the resource type template.

   You also specify the following information:

   • 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)

   • The type of code to generate (C, Korn shell (ksh), or GDS)

   For information about GDS, see Chapter 10, Generic Data Services. You must provide all the information on this screen and select Create to generate the corresponding output. Then, you can display the Configure screen.

2. Configure screen. On this screen, you must specify the full command line that can be passed to any UNIX shell to start your base application. Optionally, you can provide commands to stop and to probe your application. If you do not specify these two 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. The Configure screen also enables you to change the timeout values for each of these three commands: start, stop, probe.

Starting Agent Builder

If the GUI version of Agent Builder is not accessible, you can access Agent Builder through a command-line interface. See How to Use the Command-Line Version of Agent Builder.

If you start 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.

Start Agent Builder by typing the following command:

% /usr/cluster/bin/scdsbuilder

The Create screen appears.

Figure 9–1 Create Screen for Agent Builder

Navigating Agent Builder

You enter information on the Create and Configure screens by performing the following operations:

• Typing information in a field

• Browsing your directory structure and selecting a file or directory

• Selecting one of a set of mutually exclusive radio buttons, for example, selecting Scalable or Failover

• Selecting the Network Aware check box to identify the base application as network aware, or leaving this box empty to identify a nonnetwork-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 emphasizes or grays out these buttons, as necessary.

For example, when you have filled in the fields and selected the preferred options on the Create screen, click Create at the bottom of the screen. Previous and Next are grayed out because no previous screen exists and you cannot go to the next step before you complete this step.

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 message. Next is highlighted, or if this is the last screen, only Cancel is highlighted.

You can click Cancel at any time to exit Agent Builder.

Browse Command

Some Agent Builder fields enable you to type information in them. Other fields enable you to click Browse to browse a directory structure and select a file or a directory.

When you click Browse, a screen similar to this screen appears.

Double-click a folder to open it. When you move the cursor to a file, the file's name appears in the File Name field. Click Select when you have located and moved the cursor to the file that you want.

If you are browsing for a directory, move the cursor to the directory that you want and click Open. If the directory contains no subdirectories, Agent Builder closes the browse window and places the name of the directory to which you moved the cursor in the appropriate field. If this directory has subdirectories, click Close to close the browse window and redisplay the previous screen. Agent Builder places the name of the directory to which you moved the cursor in the appropriate field.

The icons in the upper right corner of the Browse screen do the following:

Icon	Purpose
	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.

Agent Builder Menus

Agent Builder provides File and Edit drop-down menus.

Agent Builder File Menu

The File menu contains two options:

• Load Resource Type. Loads 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 start Agent Builder, Agent Builder automatically loads the resource type. Load Resource Type enables you to start Agent Builder from any directory and select an existing resource type to use as a template for creating a new resource type. See Reusing Code That You Create With Agent Builder.

• Exit. Exits Agent Builder. You can also exit by clicking Cancel on the Create or the Configure screen.

Agent Builder Edit Menu

The Edit menu contains two options:

• 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 iteratively 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. Saves the log output to a file. Agent Builder provides a browse screen that enables you to select the directory and specify a file name.

Using the Create Screen

The first step in creating a resource type is to complete the Create screen, which appears when you start Agent Builder. The following figure shows the Create screen after you type information in the fields.

Figure 9–2 Agent Builder Create Screen, After You Type Information

The Create screen contains the following fields, radio buttons, and check box:

• Vendor Name. A name that identifies the vendor of the resource type. Typically, you specify the stock symbol of the vendor. However, 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.

  ---

  Note –

  Together, the vendor name and application name make up the full name of the resource type. Starting with the Solaris 9 OS, the combination of Vendor Name and Application Name can exceed nine characters.

  ---

• RT Version. The version of the generated resource's type. The RT Version distinguishes between multiple registered versions, or upgrades, of the same base resource type.

  You cannot use the following characters in the RT Version field:

  • Space

  • Tab

  • Slash (/)

  • Backslash (\)

  • Asterisk (*)

  • Question mark (?)

  • Comma (,)

  • Semicolon (;)

  • Left square bracket ([)

  • Right square bracket (])

• Working Directory. The directory under which Agent Builder creates a directory structure to contain all the files that are 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 started Agent Builder. However, you can type a different name or use Browse 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, 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 That Agent Builder Creates.

• Scalable or Failover. Specify whether the target resource type is 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. Select the Network Aware check box to specify network aware, or do not select the check box to specify nonnetwork aware.

• 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 Korn shell-generated code and reuse the same information to create C generated code. See Reusing Code That You Create With Agent Builder.

• GDS. Specify that this service is a generic data service. Chapter 10, Generic Data Services contains more detailed information about creating and configuring a generic data service.

If the cc compiler is not in your $PATH variable, Agent Builder grays out the C radio button and allows you to select the ksh radio button. To specify a different compiler, see the note at the end of Installing and Configuring Agent Builder.

After you have specified the required information, click Create. The Output Log area at the bottom of the screen shows the actions that Agent Builder performs. You can choose Save Output Log from the Edit menu to save the information in the output log.

When finished, Agent Builder displays either a success message or a warning message.

• If Agent Builder was unable to complete this step, examine the output log for details.

• If Agent Builder completes successfully, click Next to display the Configure screen. The Configure screen 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 that you have specified or the work that Agent Builder has completed. See Reusing Code That You Create With Agent Builder.

Using the Configure Screen

The Configure screen, shown in the following figure, appears after Agent Builder finishes creating the resource type and you click Next on the Create screen. You cannot access the Configure screen before the resource type has been created.

Figure 9–3 Configure Screen for Agent Builder

The Configure screen contains the following fields:

• Start Command. The complete command line that can be passed to any UNIX shell to start the base application. You must specify a start command. You can type the command in the field provided, or use Browse to locate a file that contains the command to start the application.

  The complete command line must include everything necessary to start the application, such as host names, port numbers, a path to configuration files. You can also specify property variables, which are described in Using Property Variables. If your Korn shell-based application requires a host name to be specified on the command line, you can use the $hostnames variable that Agent Builder defines. See Using the Agent Builder Korn Shell-Based $hostnames Variable.

  Do not enclose the command in double quotation marks (””).

  ---

  Note –

  If the base application has multiple independent process trees, each of which is started with its own tag under Process Monitor Facility (PMF) control, you cannot specify a single command. Rather, you must create a text file that contains individual commands to start each process tree, and specify the path to this file in the Start Command text field. See Before You Use Agent Builder. This section lists some special characteristics that this file requires to work correctly.

  ---

• Stop Command. The complete 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 Browse to locate a file that contains the command to stop the application. You can also specify property variables, which are described in Using Property Variables. If your Korn shell-based application requires a host name to be specified on the command line, you can use the $hostnames variable that Agent Builder defines. See Using the Agent Builder Korn Shell-Based $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 percent 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 percent of the timeout value for the application to exit.

  • If SIGKILL is unsuccessful, the Stop method exits unsuccessfully. The remaining 5 percent of the timeout value is considered overhead.

  ---

  Caution –

  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 exit status between 0 (success) and 100 (complete failure). This command is optional. You can type the complete path to the command, or use Browse 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 that is used by the resource. If the connect and disconnect succeed, the generated code declares the application healthy. You can also specify property variables, which are described in Using Property Variables. If your Korn shell-based application requires that you specify a host name on the probe command line, you can use the $hostnames variable that Agent Builder defines. See Using the Agent Builder Korn Shell-Based $hostnames Variable.

  Do not enclose the command in double quotation marks (””).

• Timeout. A timeout value, in seconds, for each command. You can specify a new value, or accept the default value that Agent Builder provides. The default value is 300 seconds for start and stop and 30 seconds for probe.

Using the Agent Builder Korn Shell-Based $hostnames Variable

For many applications, specifically network-aware applications, the host name on which the application listens and services customer requests must be passed to the application on the command line. In many cases, the host name is an argument that you must specify for start, stop, and probe commands for the target resource type on the Configure screen. However, the host name on which an application listens is cluster specific. The host name is determined when the resource is run on a cluster. The host name 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.

The $hostnames variable is supported for use with Korn shell-based services only. The $hostnames variable is not supported for use with C-based and GDS-based services.

You specify the $hostnames variable exactly as you would an actual host name, 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 host name that is configured for that resource is substituted for the value of the $hostnames variable. The host name is configured for that resource in the Network_resources_used resource property of the resource.

If you configure the Network_resources_used property with multiple host names, the $hostnames variable contains all host names, each host name separated by a comma.

Using Property Variables

You can also retrieve the values of selected Sun Cluster resource type, resource, and resource group properties from the RGM framework by using property variables. Agent Builder scans your start, probe, or stop command strings for property variables and substitutes these variables with their values before Agent Builder executes the command.

Property variables are not supported for use with Korn shell-based services.

List of Property Variables

This section lists the property variables that you can use. The Sun Cluster resource type, resource, and resource group properties are described in Appendix A, Standard Properties.

Resource Property Variables

• HOSTNAMES

• RS_CHEAP_PROBE_INTERVAL

• RS_MONITOR_START_TIMEOUT

• RS_MONITOR_STOP_TIMEOUT

• RS_NAME

• RS_NUM_RESTARTS

• RS_RESOURCE_DEPENDENCIES

• RS_RESOURCE_DEPENDENCIES_WEAK

• RS_RETRY_COUNT

• RS_RETRY_INTERVAL

• RS_SCALABLE

• RS_START_TIMEOUT

• RS_STOP_TIMEOUT

• RS_THOROUGH_PROBE_INTERVAL

• SCHA_STATUS

Resource Type Property Variables

• RT_API_VERSION

• RT_BASEDIR

• RT_FAILOVER

• RT_INSTALLED_NODES

• RT_NAME

• RT_RT_VERSION

• RT_SINGLE_INSTANCE

Resource Group Property Variables

• RG_DESIRED_PRIMARIES

• RG_GLOBAL_RESOURCES_USED

• RG_IMPLICIT_NETWORK_DEPENDENCIES

• RG_MAXIMUM_PRIMARIES

• RG_NAME

• RG_NODELIST

• RG_NUM_RESTARTS

• RG_PATHPREFIX

• RG_PINGPONG_INTERVAL

• RG_RESOURCE_LIST

Syntax of Property Variables

You include a percent sign (%) before a property name to indicate a property variable, as shown in this example:

/opt/network_aware/echo_server -t %RS_STOP_TIMEOUT -n %RG_NODELIST

Given the preceding example, Agent Builder might interpret these property variables and start the echo_server script with the following values:

/opt/network_aware/echo_server -t 300 -n phys-node-1,phys-node-2,phys-node-3

How Agent Builder Substitutes Property Variables

Agent Builder interprets the types of property variables, as follows:

• An integer is substituted with its actual value (300, for example).

• A Boolean value is substituted with the string TRUE or FALSE.

• A string is substituted with the actual string (phys-node-1, for example).

• A list of strings is substituted with all members in the list, each string separated by a comma (phys-node-1,phys-node-2,phys-node-3, for example).

• A list of integers is substituted with all members in the list, each integer separated by a comma (1,2,3, for example).

• An enumerated type is substituted with its value, in string form.

Reusing Code That You Create With Agent Builder

Agent Builder enables you to reuse completed work in the following ways:

• You can clone an existing resource type that you created with Agent Builder.

• You can edit the source code that Agent Builder generates and recompile the code to create a new package.

How to Clone an Existing Resource Type

Follow this procedure to clone an existing resource type that is generated by Agent Builder.

1. Load an existing resource type into Agent Builder.

   Use one of the following methods:

   • Start Agent Builder from the working directory for an existing resource type that you created with Agent Builder. Ensure that the working directory contains the rtconfig file. Agent Builder loads the values for that resource type in the Create and Configure screens.

   • Use the Load Resource Type option from the File drop-down menu.

2. Change the working directory on the Create screen.

   You must use Browse to select a directory. Typing a new directory name is not sufficient. After you select a directory, Agent Builder re-enables the Create button.

3. Make the changes that you want to the existing resource type.

   You might change the type of code that is generated for the resource type.

   For example, if you initially create a Korn shell version of a resource type but find over time that you require a C version, you can do the following:

   • Load the existing Korn shell resource type.

   • Change the language for the output to C.

   • Click Create to have Agent Builder build a C version of the resource type.

4. Create the cloned resource type.

   1. Click Create to create the resource type.

   2. Click Next to display the Configure screen.

   3. Click Configure to configure the resource type, and click Cancel to finish.

Editing the Generated Source Code

To simplify the process of creating a resource type, Agent Builder limits the amount of information that you can specify, which necessarily limits the scope of the generated resource type. Therefore, to add more sophisticated features, you need to modify the generated source code or the RTR file. Examples of additional features include code that adds validation checks for additional properties or that tunes parameters that Agent Builder does not expose.

The source files are in the install-directory/rt-name/src directory. Agent Builder embeds comments in the source code where 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 source code, except the comment mark (#) indicates the beginning of a comment.

For example, rt-name.h declares all the utility functions that the different programs use. At the end of the list of declarations are comments that enable you to declare additional functions that you might have added to your code.

Agent Builder also generates the makefile in the install-directory/rt-name/src directory with corresponding targets. Use the make command to recompile the source code. Use 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. See Appendix A, Standard Properties for information about properties.

How to Use the Command-Line Version of Agent Builder

The command-line version of Agent Builder follows the same basic process as the GUI. However, instead of typing information in the GUI, you pass arguments to the scdscreate and scdsconfig commands. See the scdscreate(1HA) and scdsconfig(1HA) man pages for more information.

Follow these steps to use the command-line version of Agent Builder.

1. Use scdscreate to create a Sun Cluster resource type template for making an application highly available or scalable.

2. Use scdsconfig to configure the resource type template that you created with scdscreate.

   You can specify property variables. Property variables are described in Using Property Variables.

3. Change directories to the pkg subdirectory in the working directory.

4. Use the pkgadd command to install the packages that you created with scdscreate.

   # pkgadd -d . package-name

5. (Optional) Edit the generated source code.

6. Run the start script.

Directory Structure That Agent Builder Creates

Agent Builder creates a directory structure to hold all the files that it generates for the target resource type. You specify the working directory on the Create screen. You must specify separate install directories for any additional resource types that 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. 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 that are listed in the following table.

% man -M install-directory/SUNWftp/man removeftp

Agent Builder Output

This section describes the output that Agent Builder generates.

The following topics are covered:

• Source and Binary Files

• Utility Scripts and Man Pages That Sun Cluster Agent Builder Creates

• Support Files That Agent Builder Creates

• Package Directory That Agent Builder Creates

• rtconfig File

Source and Binary Files

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

To support this model, Agent Builder generates eight executable C programs or Korn shell scripts in the install-directory/rt-name/bin directory. These programs or shell scripts 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. Instead, the RGM calls rt-name_monitor_start and rt-name_monitor_stop. These methods start and stop the fault monitor by calling rt-name _probe.

Here are the eight methods that Agent Builder generates:

• 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

See the rt_callbacks(1HA) man page for specific information about each method.

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) that contains code that is common to all methods

• An object file (rt-name.o) for the common code

• Source files (*.c) for each method

• Object files (*.o) for each method

Agent Builder links the rt-name.o file to each of the method .o files to create the executable files in the install-directory/rt-name/bin directory.

For Korn shell output, the install-directory/rt-name/bin and install-directory/rt-name/src directories are identical. Each directory contains the eight executable scripts that correspond to the seven callback methods and the Probe method.

The Korn shell output includes two compiled utility programs, gettime and gethostnames. Particular callback methods require these methods for getting the time and for 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 correct locations where you can add code. See Editing the Generated Source Code.

Utility Scripts and Man Pages That Sun Cluster Agent Builder Creates

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 that is running on a cluster. Generally, to get an instance, you use administrative commands or Sun Cluster Manager. However, as a convenience, Agent Builder generates a customized utility script for this purpose as well as scripts for stopping and removing a resource of the target resource type.

These three scripts, which are 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. This script also creates the network address resource (LogicalHostname or SharedAddress) that enables the application to communicate with the clients on the network.

• Stop script. Stops the resource.

• Remove script. Undoes the work of the start script. That is, this script 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 that was 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 utility script. You should read these man pages before you start these scripts because they document the arguments that you need to pass to the script.

To view these man pages, specify the path to this man directory by using the -M option with the man command. For example, if SUNW is the vendor and ftp is the application name, type 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, type the following command to view the startftp(1M) man page:

% man -M /opt/SUNWftp/man startftp

Support Files That Agent Builder Creates

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. The RTR file declares resource and resource type properties that are 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 That Agent Builder Creates

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 the creation of a new package. For example, if you make changes to the source files and recompile the code, or you 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 simultaneously from more than one node.

You can solve this problem in one of two ways:

• Run the remove rt-name script from one node of the cluster before running the pkgrm command from any node.

• Run the pkgrm command from one node of the cluster, which takes care of all necessary cleanup operations. Then, run the pkgrm command from the remaining nodes, simultaneously if necessary.

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

rtconfig File

If you generate C or Korn shell source code in the working directory, Agent Builder generates a configuration file called rtconfig. This file contains the information that you specified on the Create and Configure screens. If you start Agent Builder from the working directory for an existing resource type, Agent Builder reads the rtconfig file. Agent Builder fills in the Create and Configure screens with the information that you provided for the existing resource type. Agent Builder works similarly if you load an existing resource type by choosing Load Resource Type from the File drop-down menu. This feature is useful if you want to clone an existing resource type. See Reusing Code That You Create With Agent Builder.

Cluster Agent Module for Agent Builder

The Cluster Agent module for Agent Builder is a NetBeans^TM module. This module provides a GUI that enables you to create resource types for the Sun Cluster software through the Sun Java Studio (formerly Sun ONE Studio) product.

The Sun Java Studio documentation contains information about how to set up, install, and use the Sun Java Studio product. You can find this documentation at the http://wwws.sun.com/software/sundev/jde/documentation/index.html web site.

How to Install and Set Up the Cluster Agent Module

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 Java Studio software, you need to create a symbolic link to this file.

The Sun Cluster and Sun Java Studio products and Java 1.4 must be installed and available to the system on which you intend to run the Cluster Agent module.

1. Enable all users or only yourself to use the Cluster Agent module.

   • To enable all users, become superuser or assume a role that provides solaris.cluster.modify RBAC authorization, and create the symbolic link in the global module directory.

     # cd /opt/s1studio/ee/modules # ln -s /usr/cluster/lib/scdsbuilder/scdsbuilder.jar

     ---

     Note –

     If you installed the Sun Java 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

2. Stop and restart the Sun Java Studio software.

How to Start the Cluster Agent Module

The following steps describe how to start the Cluster Agent module from the Sun Java Studio software.

The Sun Java Studio documentation contains information about how to set up, install, and use the Sun Java Studio product. You can find this documentation at the http://wwws.sun.com/software/sundev/jde/documentation/index.html web site.

1. From the Sun Java Studio File menu, choose New, or click this icon on the toolbar:

   

   The New Wizard screen appears.

   

2. In the Select a Template pane, scroll down (if necessary) and click the key next to the Other folder.

   

   The Other folder opens.

   

3. From the Other folder, select Sun Cluster Agent Builder and click Next.

   The Cluster Agent module for Sun Java Studio starts. The first New Wizard - Sun Cluster Agent Builder screen appears.

   

Using the Cluster Agent Module

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.

Figure 9–4 Create Screen in the Agent Builder Software

Figure 9–5 New Wizard - Sun Cluster Agent Builder Screen in the Cluster Agent Module

Differences Between the Cluster Agent Module and Agent Builder

Despite the similarities between the Cluster Agent module and Agent Builder, minor differences exist:

• 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. In addition, the resource type is immediately configured when you click Configure on the Configure screen.

• The information that appears in the Output Log area in Agent Builder appears in a separate window in the Sun Java Studio product.