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 Resource Group Manager (RGM). A resource type essentially is a wrapper around an application to enable the application to run in a clustered environment under control of the RGM.
Agent Builder provides a screen-based interface for entering simple information about your application and the kind of resource type that you want to create. Based on the information you enter, Agent Builder generates the following software:
A set of source files--C, Korn shell (ksh), or GDS (generic data service)--for a failover or scalable resource type, corresponding to the resource type's method callbacks
A customized Resource Type Registration (RTR) file (if you generate C or Korn shell source)
Customized utility scripts for starting, stopping, and removing an instance (resource) of the resource type, as well as customized man pages documenting how to use each of these files
A Solaris package that includes the binaries (if you generate C source), an RTR file (if you generate C or Korn shell source), and the utility scripts
Topics covered in this chapter include:
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 3.1 10/03 Software Installation Guide contains more information). Before you use Agent Builder, verify the following information:
Java is included in your $PATH variable Agent Builder depends on Java (Java Development Kit version 1.3.1 or higher) and if Java is not in your $PATH, scdsbuilder returns with an error message.
You have installed the "Developer System Support" software group of Solaris 8 or higher.
The cc compiler is included in your $PATH variable Agent Builder uses the first occurrence of cc in your $PATH variable to identify the compiler with which to generate C binary code for the resource type. If cc is not included in $PATH, Agent Builder disables the option to generate C code (see Using the Create Screen.
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
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:
Create--On this screen you provide basic information about the resource type to create, such as its name and the working directory (that is, the directory where you create and configure the resource type template) for the generated files. You also identify the kind of resource to create (scalable or failover), whether the base application is network aware (that is, if it uses the network to communicate with its clients), and the type of code (C, ksh, or GDS) to generate. For information on GDS (generic data service), see Chapter 10, Generic Data Services. You must complete the information in this screen, and select Create to generate the corresponding output, before you can display the Configure screen.
Configure--On this screen, you are required to provide a command to start the application. Optionally, you can provide commands to stop and probe the application. If you do not specify these commands, the generated output uses signals to stop the application and provides a default probe mechanism (see the description of the probe command in Using the Configure Screen). This screen also enables you to change the timeout values for each of these three commands.
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
The Create screen contains the following fields, radio buttons, and check box:
Vendor Name -- A name to identify the vendor of the resource type. Typically, you specify the stock symbol of the vendor, but any name that uniquely identifies the vendor is valid. Use alphanumeric characters only.
Application Name -- The name of the resource type. Use alphanumeric characters only.
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.
Working Directory -- The directory under which Agent Builder creates a directory structure to contain all the files created for the target resource type. You can create only one resource type in any one working directory. Agent Builder initializes this field to the path of the directory from which you launched Agent Builder, though you can type a different name or use the Browse button to locate a different directory.
Under the working directory, Agent Builder creates a subdirectory with the resource-type name. For example, if SUNW is the vendor name and ftp is the application name, then Agent Builder names this subdirectory SUNWftp.
Agent Builder places all the directories and files for the target resource type under this subdirectory (see Directory Structure).
Scalable or Failover -- Specify whether the target resource type will be failover or scalable.
Network Aware -- Specify whether the base application is network aware; that is, if it uses the network to communicate with its clients. Check the box to specify network aware; leave it blank to specify non-network aware. Korn shell code requires that the application be network aware. Therefore, Agent Builder checks this box, and grays it out if you check the ksh or the GDS button.
C, ksh -- Specify the language of the generated source code. Although these options are mutually exclusive, with Agent Builder you can create a resource type with ksh generated code and then reuse the same information to create C generated code (see Cloning an Existing Resource Type).
GDS -- Specifies that this service is a generic data service. See Chapter 10, Generic Data Services for information about creating and configuring a generic data service.
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.