使用 Agent Builder

本节介绍了 Agent Builder 的使用方法，包括在使用 Agent Builder 前必须完成的准备任务。本节还介绍了在生成资源类型代码之后充分利用 Agent Builder 的方法。

本章包括以下主题：

• 分析应用程序

• 安装和配置 Agent Builder

• Agent Builder 屏幕

• 启动 Agent Builder

• 浏览 Agent Builder

• 使用“创建”屏幕

• 使用“配置”屏幕

• 使用 Agent Builder 提供的 适用于 Korn Shell 的 $hostnames 变量

• 特性变量

• 克隆现有的资源类型的方法

• 编辑已生成的源代码

• 使用 Agent Builder 的命令行版本的方法

分析应用程序

在使用 Agent Builder 前，必须确定应用程序是否满足高可用性或可伸缩性的条件。Agent Builder 无法执行仅基于应用程序的运行时特性的分析。分析应用程序的适用性中提供了有关此主题的详细信息。

虽然在大多数情况下 Agent Builder 都可以至少提供一个部分解决方案，但它并不是始终能够为您的应用程序创建完整的资源类型。例如，较复杂的应用程序可能需要使用 Agent Builder 在缺省情况下不会生成的附加代码，例如为附加特性添加验证检查的代码或调整 Agent Builder 未提供的参数的代码。在这些情况下，您必须更改所生成的源代码或 RTR 文件。Agent Builder 的设计目的就是为您提供这种灵活性。

在生成的源代码中，Agent Builder 在某些位置放置了注释，您可以在这些位置添加自己的特定资源类型代码。更改源代码后，您可以使用 Agent Builder 生成的 make 程序的描述文件重新编译源代码并重新生成资源类型软件包。

即使在编写全部资源类型代码时没有用到 Agent Builder 生成的任何代码，您也可以使用 Agent Builder 提供的 make 程序的描述文件和结构为您的资源类型创建 Solaris 软件包。

安装和配置 Agent Builder

Agent Builder 不需要专门进行安装。Agent Builder 已包括在 SUNWscdev 软件包中，缺省情况下，该软件包将被作为标准的 Sun Cluster 软件安装的一部分进行安装。《Sun Cluster 软件安装指南（适用于 Solaris OS）》中介绍了这方面的详细信息。

使用 Agent Builder 前，请检验以下信息：

• 变量 $PATH 中是否已经包括 Java 运行时环境。Agent Builder 基于 Java（Java Development Kit，1.3.1 版以上）运行。如果在变量 $PATH 中没有包括 Java，则 scdsbuilder 将返回并显示一条错误消息。

• 是否已安装了 Solaris 8 或更高版本的“开发者系统支持”软件组。

• 变量 $PATH 中是否已包含 cc 编译器。Agent Builder 将 $PATH 变量中出现的第一个 cc 标识为要用来生成资源类型的 C 二进制代码的编译器。如果变量 $PATH 中未包括 cc，则 Agent Builder 将禁用生成 C 代码的选项。请参见使用“创建”屏幕。

除了标准 cc 编译器之外，您可以将其他编译器与 Agent Builder 一起使用。要使用其他编译器，请在 $PATH 中创建从 cc 到其他编译器（例如 gcc）的符号链接。或者，将 makefile 中的编译器定义（当前为 CC=cc）更改为其他编译器的完整路径。例如，在 Agent Builder 生成的 makefile 中，将 CC=cc 更改为 CC=路径名/gcc。在此情况下，您不能直接运行 Agent Builder，而必须要使用 make 和 make pkg 命令生成数据服务代码和软件包。

Agent Builder 屏幕

Agent Builder 是一个包含两个步骤的向导，每个步骤都有对应的屏幕。Agent Builder 提供了以下两个屏幕，用来帮助您完成创建新资源类型的过程。

1. 创建。可在此屏幕上提供关于要创建的资源类型的基本信息，例如，该资源类型的名称和用于保存生成的文件的工作目录。工作目录是您创建和配置资源类型模板的位置。您还需要确定要创建的资源的种类（可伸缩或故障转移）、基本应用程序是否支持网络（即该应用程序是否使用网络与它的客户机进行通信）以及要生成的代码的类型（C、Korn shell [ksh] 或 GDS）。有关 GDS 的更多信息，请参见第 10 章，普通数据服务。必须提供此屏幕上提示的所有信息并选择“创建”以便生成相应的输出。然后，您就可以看到“配置”屏幕。

2. 配置。在此屏幕上必须指定可以传递给任何 UNIX® shell 的完整的命令行以启动基本应用程序。您还可以提供停止和探测应用程序的命令（可选操作）。如果不指定这些命令，则生成的输出结果将使用信号停止应用程序并提供缺省的探测机制。请参见使用“配置”屏幕中对探测命令的说明。此屏幕还使您可以分别更改这三个命令的超时值。

启动 Agent Builder

如果不能访问 Agent Builder 的图形用户界面版本，则可以通过命令行界面访问 Agent Builder。请参见使用 Agent Builder 的命令行版本的方法。

如果是从现有资源类型的工作目录启动 Agent Builder，则“创建”和“配置”屏幕将使用现有资源类型的值作为初始值。

请键入以下命令来启动 Agent Builder：

% /usr/cluster/bin/scdsbuilder

将显示“创建”屏幕。

图 9–1 “创建”屏幕

浏览 Agent Builder

请执行以下操作，在“创建”屏幕和“配置”屏幕中输入信息：

• 在字段中键入信息。

• 浏览目录结构并选择文件或目录。

• 从一组相互排斥的单选按钮中选择一个按钮，例如单击“可伸缩”或“故障转移”。

• 单击“打开”或“关闭”框。例如，单击“支持网络”将基本应用程序标识为支持网络的应用程序，而不选中此框则将基本应用程序标识为不支持网络的应用程序。

使用每个屏幕底部的各个选项，您可以完成相应的任务、进入到下一屏或上一屏或退出 Agent Builder。Agent Builder 会相应地突出显示或灰显这些选项以示强调。

例如，在“创建”屏幕上，向字段中填入所需信息并选中所需的选项后，单击屏幕底部的“创建”。“上一步”和“下一步”将呈灰色显示，这是因为上一屏幕不存在，并且只有在完成此屏幕后才能进入下一步。

Agent Builder 将在屏幕底部的输出日志区域显示进度消息。当 Agent Builder 完成操作后，它将显示成功消息或请您查看输出日志的警告消息。将突出显示“下一步”，或如果此屏幕是最后一屏，则仅突出显示“取消”。

您可以随时选择“取消”来退出 Agent Builder。

浏览

对于一些特定的 Agent Builder 字段，您既可以在其中键入信息，也可以单击“浏览”来浏览目录结构并选择文件或目录。

单击“浏览”，将显示类似于下图所示的屏幕：

双击某个文件夹以打开该文件夹。如果将光标移动到某个文件上，该文件的名称将显示在“文件名”框中。在找到所需文件并将光标移动到该文件上后，单击“选择”。

如果正在浏览以查找目录，请将光标移动到所需的目录上，然后单击“打开”。如果该目录没有子目录，Agent Builder 将关闭浏览窗口并将刚才光标所指的目录的名称填入恰当的字段中。如果该目录具有子目录，请单击“关闭”关闭浏览窗口并重新显示上一屏。Agent Builder 会将刚才光标所指的目录的名称填入恰当的字段中。

位于屏幕右上角的图标用来执行以下操作：

菜单

Agent Builder 提供了“文件”和“编辑”下拉菜单。

“文件”菜单

“文件”菜单包含两个选项：

• “装入资源类型”选项。装入现有的资源类型。Agent Builder 提供了浏览屏幕，您可以从中选择现有资源类型的工作目录。如果从中启动 Agent Builder 的目录中存在某个资源类型，则 Agent Builder 将自动装入该资源类型。“装入资源类型”选项使您可以从任意目录中启动 Agent Builder，并选择现有资源类型作为创建新资源类型时使用的模板。请参见克隆现有的资源类型的方法。

• “退出”选项。退出 Agent Builder。您也可以单击“创建”或“配置”屏幕上的“取消”来退出 Agent Builder。

“编辑”菜单

“编辑”菜单包含以下两个选项：

• “清除输出日志”选项。清除输出日志中的信息。每当您选择“创建”或“配置”时，Agent Builder 都将向输出日志中附加状态消息。如果您是在执行这样的一个循环操作：更改源代码然后在 Agent Builder 中重新生成输出，并且希望分开各个状态消息，则可以在每次使用之前保存并清除日志文件。

• “保存日志文件”选项。将输出日志保存为文件。Agent Builder 提供了一个浏览屏幕，用于选择目录和指定文件名。

使用“创建”屏幕

“创建”屏幕

创建资源类型的第一个步骤是填写“创建”屏幕（即启动 Agent Builder 后显示的屏幕）上的各项内容。下图显示的是已在各个字段输入信息的“创建”屏幕。

图 9–2 “创建”屏幕

“创建”屏幕中包含以下字段、单选按钮和复选框：

• “供应商名”。用于标识资源类型供应商的名称。通常要指定供应商的股票标志，但是任何可唯一标识供应商的名称也有效。仅可使用字母数字字符。

• “应用程序名”。资源类型的名称。仅可使用字母数字字符。

  ---

  注意 –

  供应商名称和应用程序名称合在一起组成资源类型的全名。全名不能超过九个字符。

  ---

• “RT 版本”。生成的资源类型的版本。RT 版本用于区分同一基本资源类型的多个已注册版本或升级版本。

  在“RT 版本”字段中不能使用以下字符：空白、制表符、斜杠 (/)、反斜杠 (\)、星号 (*)、问号 (?)、逗号 (,)、分号 (;)、左方括号 ([) 或右方括号 (])。

• “工作目录”。Agent Builder 将在此目录下创建目录结构以包含为目标资源类型创建的所有文件。在任意一个工作目录中仅能创建一个资源类型。Agent Builder 将此字段的值初始化为启动 Agent Builder 的目录的路径，您也可以键入其他名称或使用“浏览”按钮来定位其他目录。

  在工作目录下，Agent Builder 将使用资源类型的名称创建子目录。例如，如果 SUNW 是供应商名，ftp 是应用程序名，则 Agent Builder 将把此子目录命名为 SUNWftp。

  Agent Builder 将在此子目录下放置目录资源类型的所有目录和文件。请参见目录结构。

• “可伸缩”或“故障转移”。指定目标资源类型是故障转移还是可伸缩。

• “支持网络”。指定基本应用程序是否支持网路，即它是否使用网络与客户机进行通信。选择“支持网络”复选框以指定应用程序支持网络，或不选择此复选框以指定应用程序不支持网络。

• "C" 和 "ksh"。指定生成的源代码所用的语言。虽然这些选项是相互排斥的，但是在 Agent Builder 中，您可以创建资源类型并用 Korn shell 语言生成代码，然后重新使用这些信息创建用 C 语言生成的代码。请参见克隆现有的资源类型的方法。

• "GDS"。指定此服务为通用数据服务。有关创建和配置普通数据服务的信息，请参见第 10 章，普通数据服务。

如果在 $PATH 中没有包括 cc 编译器，则 Agent Builder 将禁用 "C" 单选按钮，而允许您选择 "ksh" 单选按钮。要指定其他编译器，请参见安装和配置 Agent Builder结尾处的说明。

输入必需的信息后，请单击“创建”。屏幕底部的“输出日志”窗口用来显示 Agent Builder 执行的操作。您可以从“编辑”菜单中选择“保存输出日志”来保存输出日志中的信息。

完成操作后，Agent Builder 将显示一条成功消息或警告消息。

• 如果 Agent Builder 无法完成此步骤，请检查输出日志以获得详细信息。

• 如果 Agent Builder 成功完成操作，则可以单击“下一步”以显示“配置”屏幕，使用该屏幕可以完成生成资源类型的步骤。

虽然生成完整的资源类型需要两步才能完成，但是您可以在完成第一步（创建）后就退出 Agent Builder，这样做既不会丢失已输入的信息也不会丢失 Agent Builder 已完成的工作。请参见重复使用完成的工作。

使用“配置”屏幕

“配置”屏幕

在 Agent Builder 完成创建资源类型的操作后，在“创建”屏幕上选择“下一步”，将会出现“配置”屏幕（如下图所示）。必须先创建资源类型才能存取“配置”屏幕。

图 9–3 “配置”屏幕

“配置”屏幕上包含以下字段：

• “启动命令”。可以传递到任意 UNIX shell 以启动基本应用程序的完整命令行。必须指定启动命令。您可以在提供的字段中键入该命令，或使用“浏览”按钮定位包含用来启动应用程序的命令的文件。

  完整的命令行必须包含启动应用程序必需的所有内容，例如主机名、端口号和指向配置文件的路径等。您也可以指定在特性变量中介绍的特性变量。如果基于 Korn shell 的应用程序要求您在命令行上指定主机名，则可以使用 Agent Builder 定义的 $hostnames 变量。请参见使用 Agent Builder 提供的 适用于 Korn Shell 的 $hostnames 变量。

  请不要将命令置于双引号 (””) 之间。

  ---

  注意 –

  如果基本应用程序具有多个独立的进程树（每一个进程树都在进程监视工具 (PMF) 控制下以其各自的标记来启动），则不能只指定一个命令。而是必须创建一个文本文件，其中包含启动每一个进程树的各个命令，并且还要在“启动命令”文本字段中指定指向此文件的路径。请参见创建具有多个独立的进程树的资源类型，其中列出了此文件正常工作所需的一些特殊特性。

  ---

• “停止命令”。可以传递到任意 UNIX shell 以停止基本应用程序的完整命令行。您可以在提供的字段中键入该命令，也可以使用“浏览”按钮定位包含用来停止应用程序的命令的文件。您也可以指定特性变量中介绍的特性变量。如果基于 Korn shell 的应用程序要求您在命令行上指定主机名，则可以使用 Agent Builder 定义的 $hostnames 变量。请参见使用 Agent Builder 提供的 适用于 Korn Shell 的 $hostnames 变量。

  此命令是可选的。如果不指定停止命令，则生成的代码将按以下步骤使用信号（包含在 Stop 方法中）来停止应用程序：

  • Stop 方法发送 SIGTERM 来停止应用程序，并等待应用程序退出（等待的时间为超时值的 80%）。

  • 如果 SIGTERM 信号没有成功停止应用程序，则 Stop 方法将发送 SIGKILL 来停止应用程序，并等待应用程序退出（等待的时间为超时值的 15%）。

  • 如果 SIGKILL 没有成功停止应用程序，Stop 方法将失败而退出。余下的 5% 的超时值被认为是系统开销。

  ---

  注意 –

  请确保该停止命令在应用程序完全停止之后返回。

  ---

• “探测命令”。此命令可以定期运行以检查应用程序的运行状况并返回相应的退出状态（介于 0 [成功] 和 100 [完全失败] 之间）。此命令是可选的。您可以键入指向该命令的完整路径，也可以使用“浏览”按钮来定位包含用来探测应用程序的命令的文件。

  通常，您需指定基本应用程序的简单客户机。如果您不指定探测命令，则生成的代码仅连接到资源所用的端口（或仅从该端口上断开连接）。如果探测成功，则表明该应用程序运行正常。您也可以指定特性变量中介绍的特性变量。如果基于 Korn shell 的应用程序要求您在命令行上的探测命令中指定主机名，则可以使用 Agent Builder 定义的 $hostnames 变量。请参见使用 Agent Builder 提供的 适用于 Korn Shell 的 $hostnames 变量。

• “超时”。每个命令的超时值（单位为秒）。您可以指定新值，或接受 Agent Builder 提供的缺省值（启动和停止的缺省值为 300 秒，探测的缺省值为 30 秒）。

使用 Agent Builder 提供的 适用于 Korn Shell 的 $hostnames 变量

对于许多应用程序，尤其是支持网络的应用程序而言，必须将应用程序侦听时所在的和响应用户请求的主机的主机名通过命令行传递给应用程序。大多数情况下，必须为目标资源类型的启动、停止和探测命令指定主机名参数（在“配置”屏幕上）。但是，应用程序侦听时所在的主机的主机名是特定于群集的。主机名是在群集上运行资源时才确定的，在 Agent Builder 生成资源类型代码时，并不能确定主机名。

要解决此问题，Agent Builder 提供了您可以在启动、停止和探测命令的命令行中指定的 $hostnames 变量。

$hostnames 变量只适用于基于 Korn shell 的服务。不支持对基于 C 和 GDS 的服务使用 $hostnames 变量。

指定 $hostnames 变量的方法就像指定实际主机名一样，例如：

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

如果目标资源类型的资源在群集上运行，则为该资源配置的 LogicalHostname 或 SharedAddress 主机名（在该资源的 Network_resources_used 资源特性中）将替换 $hostnames 变量的值。

如果配置的是包含多个主机名的 Network_resources_used 特性，则 $hostnames 变量中将包含所有主机名（用逗号分开各主机名）。

特性变量

您可以使用特性变量从 RGM 框架中检索选中的 Sun Cluster 资源、资源类型和资源组特性的值。Agent Builder 将在启动、探测或停止脚本中扫描特性变量，并在 Agent Builder 启动脚本前用这些变量的值替换这些变量。

基于 Korn shell 的服务不支持使用特性变量。

特性变量列表

以下列表列出了可以在脚本中使用的特性变量。附录 A，标准特性中介绍了 Sun Cluster 资源、资源类型和资源组特性。

以下列表列出了资源特性变量：

• 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

以下列表列出了资源类型特性变量：

• RT_API_VERSION

• RT_BASEDIR

• RT_FAILOVER

• RT_INSTALLED_NODES

• RT_NAME

• RT_RT_VERSION

• RT_SINGLE_INSTANCE

以下列表列出了资源组特性变量：

• 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

特性变量的语法

表示特性变量的方法是在特性名之前加上一个百分号 (%)，如以下示例所示。

# /opt/network_aware/echo_server -t %RS_STOP_TIMEOUT -n %RG_NODELIST

按以上示例给定特性变量后，Agent Builder 就可以解释这些特性变量，然后以以下值启动 echo_server 脚本。

# /opt/network_aware/echo_server -t 300 -n phys-node-1,phys-node-2,phys-node-3

Agent Builder 替换特性变量的方式

以下列表说明了 Agent Builder 如何解释各类型的特性变量：

• 整型值被替换为该变量的实际值（例如 300）。

• 布尔型值被替换为字符串 TRUE 或 FALSE。

• 字符串被替换为实际的字符串（例如 phys-node-1）。

• 字符串列表被替换为该列表中包含的所有的字符串值，并以逗号隔开各个值（例如 phys-node-1,phys-node-2,phys-node-3）。

• 整型值列表被替换为该列表中包含的所有的整型值，并以逗号隔开各个整型值（例如 1,2,3）。

• 枚举类型将按字符串格式被替换为该类型本身的值。

重复使用完成的工作

使用 Agent Builder，您可以通过以下多种方式重复使用已完成的工作：

• 您可以克隆使用 Agent Builder 创建的现有资源类型。

• 您可以编辑 Agent Builder 生成的源代码，然后重新编译该代码以创建新的软件包。

克隆现有的资源类型的方法

请按照一下步骤克隆已由 Agent Builder 生成的现有资源类型。

1. 使用以下方法之一可将现有资源类型装入到 Agent Builder 中：

   • 从现有资源类型（用 Agent Builder 创建的资源类型）的工作目录（即包含 rtconfig 文件的目录）中启动 Agent Builder。Agent Builder 将在“创建”和“配置”屏幕装入该资源类型的值。

   • 从“文件”下拉菜单中选择“装入资源类型”选项。

2. 在“创建”屏幕上更改工作目录。

   必须使用“浏览”按钮来选择目录。仅键入新目录的名称是不够的。选择目录后，Agent Builder 将重新启用“创建”按钮。

3. 进行更改。

   您可以使用此步骤来更改该资源类型的生成代码的类型。例如，如果原来创建的是 Korn shell 版本的资源类型，但是过了一段时间发现需要 C 版本的资源类型，则可以装入现有的 Korn shell 资源类型，并将输出语言更改为 C 语言，然后使用 Agent Builder 创建 C 版本的资源类型。

4. 创建克隆的资源类型。

   单击“创建”按钮创建该资源类型。单击“下一步”将显示“配置”屏幕。单击“配置”按钮以配置该资源类型，然后单击“取消”以完成操作。

编辑已生成的源代码

为使创建资源类型的过程保持简单，Agent Builder 将限制输出数量，这必将限定已生成的资源类型的范围。因此，为了添加更复杂的特征（例如附加特性的验证检查）或调整 Agent Builder 未提供的参数，您需要修改已生成的源代码或 RTR 文件。

源文件位于 install_directory /rt_name/src 目录中。在源代码中，Agent Builder 在您可以添加代码的位置嵌入了注释。这些注释的格式如下（针对 C 代码）：

/* 用户添加的代码 -- 开始 vvvvvvvvvvvvvvv */ 
/* 用户添加的代码 -- 结束 ^^^^^^^^^^^^^^^ */

除了 Korn shell 规定以井号 (#) 表示注释的开始外，以上这些注释与 Korn shell 源代码中的注释完全相同。

例如，rt_name.h 用来声明其他程序使用的所有实用程序例程。声明列表的结尾处是注释，您可以使用这些注释声明已向任意代码添加的附加例程。

Agent Builder 还可以使用相应的目标在 install_directory/rt_name/src 目录中生成make 程序的描述文件。使用 make 命令重新编译源代码，并使用 make pkg 命令重新生成资源类型软件包。

RTR 文件位于 install_directory/ rt_name/etc 目录中。您可以使用标准的文本编辑器编辑 RTR 文件。有关 RTR 文件的更多信息请参见设置资源和资源类型特性，有关特性的更多信息请参见附录 A，标准特性。

使用 Agent Builder 的命令行版本的方法

Agent Builder 的命令行版本也采用与图形用户界面版本相同的基本过程。但是，与在图形用户界面上输入信息不同，您需要将参数传递给命令 scdscreate 和 scdsconfig。请参见scdscreate(1HA) 和 scdsconfig(1HA)手册页。

按照以下步骤使用 Agent Builder 的命令行版本：

1. 使用 scdscreate 来创建 Sun Cluster 资源类型模板，以便使应用程序具有高可用性和可伸缩性。

2. 使用 scdsconfig 来配置您用 scdscreate 所创建的资源类型模板。

   您可以指定特性变量。在特性变量中介绍了特性变量。

3. 将目录更改为工作目录中的 pkg 子目录。

4. 使用 pkgadd 命令来安装用 scdscreate 创建的软件包。

5. 如果需要，可以编辑已生成的源代码。

6. 运行启动脚本。