Using Agent Builder

This section describes how to use Agent Builder, including 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

• Launching Agent Builder

• Navigating Agent Builder

• Using the Create Screen

• Using the Configure Screen

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

• Property Variables

• How to Clone an Existing Resource Type

• Editing the Generated Source Code

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

Analyzing the Application

Before using Agent Builder, you must determine if your application meets the criteria that is 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 might not always be able to create a complete resource type for your application, although 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 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 as part of a standard Sun Cluster software installation. The Sun Cluster Software Installation Guide for Solaris OS contains more information.

Before you use Agent Builder, verify the following:

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

• You have installed the Developer System Support software group, at least Solaris 8.

• 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 but must use the make and make pkg commands to generate data service code and a 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. 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 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 to generate (C, Korn shell (ksh), or GDS). For information about GDS, see Chapter 10, Generic Data Services. You must provide all the information about this screen and select Create to generate the corresponding output. Then, you can display the Configure screen.

2. Configure. 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 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.

Launching Agent Builder

If the graphical user interface 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 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.

Launch Agent Builder by typing the following command:

% /usr/cluster/bin/scdsbuilder

The Create screen appears.

Figure 9–1 Create Screen

Navigating Agent Builder

You enter information about 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, clicking Scalable or Failover.

• Clicking an on or off box. For example, clicking Network Aware identifies the base application as network aware, while leaving this box blank identifies a non-network aware application.

The options 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 by highlighting or grays out these options as appropriate.

For example, when you have filled in the fields and checked the desired 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 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. Next is highlighted, or if this is the last screen, only Cancel is highlighted.

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

Browse

Particular Agent Builder fields enable you to type information or to click Browse to browse your directory structure and select a file or 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 box. 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 there are 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 correct field.

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

Menus

Agent Builder provides File and Edit pull-down menus.

File Menu

The File menu contains two options:

• 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. Load Resource Type enables 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 How to Clone an Existing Resource Type.

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

Edit Menu

The Edit menu contains the following 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 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 file name.

Using the Create Screen

Create Screen

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.

Figure 9–2 Create Screen

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, 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.

  ---

  Note –

  Together, the vendor name and application name make up the full name of the resource type. The full name must not 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: blank, tab, slash (/), backslash (\), asterisk (*), question mark (?), comma (,), semicolon (;), left square bracket ([), or right square bracket (]).

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

• 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. Select the Network Aware check box to specify network aware, or do not select the check box to specify non-network 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 then reuse the same information to create C generated code. See How to Clone an Existing Resource Type.

• GDS. Specify 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 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 entered the required information, click Create. The Output Log window 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, check the output log for details.

• If Agent Builder completes successfully, click Next to display 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.

Using the Configure Screen

Configure Screen

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

Figure 9–3 Configure Screen

The Configure screen contains the following fields:

• Start Command. The full 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, and so on. You can also specify property variables, which are described in 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 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 Browse to locate a file containing the command to stop the application. You can also specify property variables, which are described in 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 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 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 used by the resource, and if that succeeds, declares the application healthy. You can also specify property variables, which are described in 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.

• Timeout. A timeout value (in seconds) for each command. You can specify a new value or accept the default value that Agent Builder provides (300 seconds for start and stop, 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 a parameter 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 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.

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 (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 host names, the $hostnames variable contains all of them, each separated by a comma.

Property Variables

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

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

List of Property Variables

The following list includes the property variables that you can use with your scripts. Sun Cluster resource, resource type, and resource group properties are described in Appendix A, Standard Properties.

The following list includes 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

The following list includes resource type property variables:

• RT_API_VERSION

• RT_BASEDIR

• RT_FAILOVER

• RT_INSTALLED_NODES

• RT_NAME

• RT_RT_VERSION

• RT_SINGLE_INSTANCE

The following list includes 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 launch 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

The following list describes how Agent Builder interprets the types of property variables:

• 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 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 separated by a comma (1,2,3, for example).

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

Reusing Completed Work

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

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

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

How to Clone an Existing Resource Type

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

1. Load an existing resource type into Agent Builder by using one of these methods:

   • Launch Agent Builder from the working directory (which contains the rtconfig file) for an existing resource type (created with Agent Builder). Agent Builder loads the values for that resource type in the Create and Configure screens.

   • Use the Load Resource Type option from the File pull-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 changes.

   You might use this procedure to change the type of code 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 load the existing Korn shell resource type, change the language for the output to C, and then have Agent Builder build a C version of the resource type.

4. Create the cloned resource type.

   Click Create to create the resource type. Click Next to display the Configure screen. Click Configure to configure the resource type, and then click Cancel to finish.

Editing the Generated Source Code

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 source code, except the pound sign (#) indicates the beginning of a comment.

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 that 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 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 and 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 graphical user interface. However, instead of entering information in the graphical user interface, you pass parameters to the commands scdscreate and scdsconfig. See the scdscreate(1HA) and scdsconfig(1HA) man pages.

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

5. If you want, edit the generated source code.

6. Run the start script.