Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Data Services Developer's Guide Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

## Agent Builder Output

This section describes the output that Agent Builder generates.

This section covers the following topics:

- Source and Binary Files

- Utility Scripts and Man Pages That 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 failure, the RGM calls the resource type's methods for each of the resources that are running on the affected node. For example, the RGM calls the `Stop` method to stop a resource that is running on the affected node, and calls the resource's `Start` method to start the resource on a different node. 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.

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

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

Note - 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 `ORCL` is the vendor and `ftp` is the application name, type the following command to view the `startftp`(1M) man page:

    % man -M install-directory/ORCLftp/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/ORCLftp/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, `ORCL.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 an Oracle Solaris SVR4 package. The name of the package is a concatenation of the vendor name and the application name, for example, `ORCLftp`. 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.

Note - If you need an IPS version of the package that Agent Builder creates, use the `pkgsend` command to convert your SVR4 agent package to an IPS package, and use the `pkg install` command to install the IPS package. For more information, see the `pkgsend`(1) and `pkg`(1) man pages.

When you remove a package from a cluster, the `pkgrm` (SVR4) or `pkg remove` (IPS) 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.

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |