test

Sun Cluster Data Services Developer's Guide for Solaris OS

Using Agent Builder

This section describes how to use Agent Builder, including tasks you must complete before you can use Agent Builder. This section also explains ways you can leverage Agent Builder after you have generated your resource type code.

Analyzing the Application

Before using Agent Builder you must determine if your application meets the criteria to be made highly available or scalable. Agent Builder cannot perform this analysis, which is based solely on the runtime characteristics of the application. Analyzing the Application for Suitability provides more information about this topic.

Agent Builder may not always be able to create a complete resource type for your application, though in most cases Agent Builder provides at least a partial solution. For example, more sophisticated applications might require additional code that Agent Builder does not generate by default, such as code to add validation checks for additional properties or to tune parameters that Agent Builder does not expose. In these cases, you must make changes to the generated source code or to the RTR file. Agent Builder is designed to provide just this sort of flexibility.

Agent Builder places comments at certain points in the generated source code where you can add your own specific resource type code. After making changes to the source code, you can use the makefile that Agent Builder generates to recompile the source code and regenerate the resource type package.

Even if you write your entire resource type code without using any code generated by Agent Builder, you can leverage the makefile and structure that Agent Builder provides to create the Solaris package for your resource type.

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

Note –

You can use a different compiler with Agent Builder than the standard cc compiler. One way to do this is to create a symbolic link in $PATH from cc to a different compiler, such as gcc. Another way is to change the compiler specification in the makefile (currently, CC=cc) to the complete path for a different compiler. For example, in the makefile generated by Agent Builder, change CC=cc to CC=pathname/gcc. In this case you cannot run Agent Builder directly but must use the make and make pkg commands to generate data service code and a package.

Launching Agent Builder

Launch Agent Builder by entering the following command:


% /usr/cluster/bin/scdsbuilder

The initial Sun Builder screen, as shown in the following figure, appears.

Figure 9–1 Initial Screen

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

Note –

You can access Agent Builder through a command-line interface (see Using the Command-Line Version of Agent Builder) if the GUI version is not accessible.

Agent Builder provides 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 (that is, the directory where you create and configure the resource type template) for the generated files. You also identify the kind of resource to create (scalable or failover), whether the base application is network aware (that is, if it uses the network to communicate with its clients), and the type of code (C, ksh, or GDS) to generate. For information on GDS (generic data service), see Chapter 10, Generic Data Services. You must complete the information in this screen, and select Create to generate the corresponding output, before you can display the Configure screen.

  2. Configure—On this screen, you are required to provide a command to start the application. Optionally, you can provide commands to stop and probe the application. If you do not specify these commands, the generated output uses signals to stop the application and provides a default probe mechanism (see the description of the probe command in Using the Configure Screen). This screen also enables you to change the timeout values for each of these three commands.

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.

See Navigating Agent Builder if you have questions about how to use any of the buttons or menu commands on either of the Agent Builder screens.

Using the 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 option button and puts a check in the ksh button. To specify a different compiler, see the note at the end of Installing and Configuring Agent Builder.

After you have entered the required information, click the Create button. The Output Log at the bottom of the screen shows the actions that Agent Builder is taking. You can use the Save Output Log command in the Edit menu to save the information in the output log.

When finished, Agent Builder displays either a success message or a warning message that it was unable to complete this step, and you should check the output log for details.

If Agent Builder completes successfully, you can Click the Next button to bring up the Configure screen, which enables you to finish generating the resource type.

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

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

Figure 9–3 Configure Screen

Dialog box that shows the Configure screen

The Configure screen contains the following fields:

Using the Agent Builder $hostnames Variable

For many applications, specifically network-aware applications, the hostname on which the application listens and services customer requests must be passed to the application on the command line. Therefore, in many cases, hostname is a parameter you must specify for start, stop, and probe commands for the target resource type (on the Configure screen). However, the hostname on which an application listens is cluster specific—it is determined when the resource is run on a cluster and cannot be determined when Agent Builder generates your resource type code.

To solve this problem, Agent Builder provides the $hostnames variable that you can specify on the command line for the start, stop, and probe commands. You specify the $hostnames variable exactly as you would an actual hostname, for example:


/opt/network_aware/echo_server -p port_no -l $hostnames

When a resource of the target resource type is run on a cluster, the LogicalHostname or SharedAddress hostname configured for that resource (in the Network_resources_used resource property of the resource) is substituted for the value of the $hostnames variable.

If you configure the Network_resources_used property with multiple hostnames, the $hostnames variable contains all of them separated by commas.

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. You cannot use Agent Builder to create these resource types for ksh or for GDS. To create these resource types for ksh or for GDS, you must write the code by hand.

In the case of a base application with multiple independent process trees, you cannot specify a single command line to start the application. Rather, you must create a text file, with each line specifying the full path to a command to start one of the application's process trees. This file must not contain any blank lines. You specify this text file in the Start Command text field in the Configure screen.

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 containing multiple commands. If this text file is given execute permissions, the resources would come up with no problems or errors on a cluster, but all the commands would be started under one PMF tag, precluding the possibility of monitoring and restarting the process trees individually by PMF.

Reusing Completed Work

Agent Builder enables you leverage completed work in several ways.

Cloning 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. You can do this in either of two ways:

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

    2. Use the Load Resource Type command in the File menu.

  2. Change the working directory on the Create screen.

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

  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 ksh version of a resource type but find over time that you require a C version, you can load the existing ksh resource type, change the language for the output to C, and then have Agent Builder build a C version of the resource type.

  4. Create the cloned resource type.

    Select Create to create the resource type. Select Next to bring up the Configure screen. Select Configure to configure the resource type and then Cancel to finish.

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 code, except they use the pound sign (#) to begin the comment line.

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

Agent Builder also generates the makefile in the install_directory/rt_name/src directory, with appropriate targets. Use the make command to recompile the source code, and the make pkg command to regenerate the resource type package.

The RTR file is in the install_directory/rt_name/etc directory. You can edit the RTR file with a standard text editor (see Setting Resource and Resource Type Properties for more information about the RTR file and Appendix A, Standard Properties for information about properties).

Using the Command-Line Version of Agent Builder

The command-line version of Agent Builder has the same two-step process as the graphical user interface. However, instead of entering information in the graphical user interface, you pass parameters to the commands scdscreate(1HA) and scdsconfig(1HA).

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

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

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

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

  4. Use the pkgadd(1M) command to install the packages that you created with scdscreate.

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

  6. Run the start script.