Sun Cluster Data Services Developer's Guide for Solaris OS

Chapter 9 SunPlex Agent Builder

This chapter describes SunPlex 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 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.

The following topics are covered in this chapter:

Agent Builder Overview

Agent Builder provides a screen-based interface for entering information about your application and the kind of resource type that you want to create.


Note –

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.


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

Agent Builder supports network aware applications (applications that use the network to communicate with clients) as well as non-network aware (or stand-alone) applications. 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. See Creating Resource Types With Multiple Independent Process Trees.

Before You Use Agent Builder

The following section presents information that you need to know before you use Agent Builder.

Creating 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 PMF monitors and starts them individually. PMF starts each process tree with its own tag.


Note –

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 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 on the Configure screen.

Ensuring that this file does not have execute permissions enables Agent Builder to distinguish this file, whose purpose 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, but all the commands are started under one PMF tag, precluding the possibility of monitoring and restarting the process trees individually by PMF.

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

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:


Note –

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


Note –

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.



Note –

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

Dialog box titled SunPlex Agent Builder that shows the main Agent Builder screen

Navigating Agent Builder

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

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.

Panel at bottom of screen that shows Create, Previous, Next, and Cancel commands

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.

Browse command

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

Browse screen that shows a list of files

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.


Note –

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:

Icon that shows up arrow

 

This icon moves you up one level in the directory tree. 

Icon that shows home

 

This icon returns you to the home folder. 

Icon that shows a new folder

 

This icon creates a new folder under the currently selected folder. 

Icon that you use to change views

 

This icon, for toggling between different views, is reserved for future use. 

Menus

Agent Builder provides File and Edit pull-down menus.

File Menu

The File menu contains two options:

Edit Menu

The Edit menu contains the following options:

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

Dialog box that shows the create screen after information has been entered

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


Note –

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.


Note –

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

Dialog box that shows the Configure screen

The Configure screen contains the following fields:

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.


Note –

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.


Note –

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:

The following list includes resource type property variables:

The following list includes resource group property variables:

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:

Reusing Completed Work

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

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   ^^^^^^^^^^^^^^^ */


Note –

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.

Directory Structure

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 (from the Create screen). For example, if you specify SUNW as the vendor name and create a resource type called ftp, Agent Builder creates a directory called SUNWftp under the working directory.

Under this subdirectory, Agent Builder creates and populates the directories listed in the following table.

Directory Name 

Contents 

bin

For C output, contains the binary files compiled from the source files. For Korn shell output, contains the same files as the src directory.

etc

Contains the RTR file. Agent Builder concatenates the vendor name and application name, separated by a period (.), to form the RTR file name. For example, if the vendor name is SUNW and the name of the resource type is ftp, the name of the RTR file is SUNW.ftp.

man

Contains customized man pages for the start, stop, and remove utility scripts. For example, startftp(1M), stopftp(1M), and removeftp(1M).

 

To view these man pages, specify the path with the man -M option. For example:


# man -M install_directory/SUNWftp/man removeftp

pkg

Contains the final package. 

src

Contains the source files that Agent Builder generates. 

util

Contains the start, stop, and remove utility scripts that Agent Builder generates. See Utility Scripts and man Pages. Agent Builder appends the application name to each of these script names, for example, startftp, stopftp, removeftp.

Agent Builder Output

This section describes the output that Agent Builder generates.

Source and Binary Files

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


Note –

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


The eight methods that Agent Builder generates are listed here:

See the rt_callbacks(1HA) man page for specific information about each of these methods.

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

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

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


Note –

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

Utility Scripts and man Pages

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


Note –

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


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

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

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


% man -M install_directory/SUNWftp/man startftp

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


% man -M /opt/SUNWftp/man startftp

Support Files

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

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

Package Directory

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

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

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

rtconfig File

If you generate C or Korn shell 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 by choosing Load Resource Type from the File pull-down menu), 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 How to Clone an Existing Resource Type.

Cluster Agent Module for Agent Builder

The Cluster Agent module for Agent Builder is a NetBeansTM module. The Cluster Agent module enables users of the Sun Java Studio (formerly Sun 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.


Note –

The Sun Java Studio documentation contains information about how to set up, install, and use the Sun Java Studio product.


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.


Note –

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


      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.

  1. From the Sun Java Studio File menu, choose New, or click this icon on the toolbar: Graphic that shows the New icon on the toolbar in the Sun Java Studio software

    The New Wizard screen appears.

    Dialog box that shows the New Wizard screen

  2. In the Select a Template window, scroll down (if necessary) and click the key next to the Other folder.Inline graphic that shows the key for the Other folder

    The Other folder opens.

    Figure that shows the expanded Other folder menu

  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.

    Dialog box that shows New Wizard Sun Cluster Agent Builder screen when it first 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

Dialog box that shows the create screen after information has been entered

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

Dialog box that shows the New Wizard Sun Cluster Agent Builder screen after information has been entered

Differences Between the Cluster Agent Module and Agent Builder

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