使用 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 至少可以提供部分解决方案。例如，更复杂的应用程序可能需要 Agent Builder 在默认情况下不生成的其他代码。其他代码的示例包括添加其他属性的验证检查的代码，或调谐 Agent Builder 不显示的参数的代码。在这些情况下，您必须更改所生成的源代码或 RTR 文件。Agent Builder 正是提供了这种灵活性。

Agent Builder 将注释置于生成的源代码中的特定点处，您可以在此处添加您自己的资源类型代码。更改源代码之后，您可以使用 Agent Builder 生成的 make 程序的描述文件重新编译该源代码并重新生成资源类型软件包。

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

安装和配置 Agent Builder

Agent Builder 不需要专门进行安装。SUNWscdev 软件包中包含 Agent Builder，默认情况下，安装 Sun Cluster 软件时安装此软件包。《Sun Cluster 软件安装指南（适用于 Solaris OS）》中介绍了这方面的更多信息。

使用 Agent Builder 之前，请检验是否满足以下要求：

• $PATH 变量中包含 Java 运行时环境。Agent Builder 基于 Java 开发工具包（不低于 1.3.1 版）进行工作。如果 $PATH 变量中未包含 Java 开发工具包，Agent Builder 命令 (scdsbuilder) 将返回并显示错误消息。

• 已安装不低于 Solaris 8 OS 版本的开发者系统支持软件组。

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

除了标准 cc 编译器，您还可以在 Agent Builder 中使用其他编译器。要使用其他编译器，请在 $PATH 中将符号链接 cc 更改为其他编译器的符号链接，例如 gcc。或者，将 make 程序的描述文件中的编译器定义（当前为 CC=cc）更改为其他编译器的完整路径。例如，在 Agent Builder 生成的 make 程序的描述文件中，将 CC=cc 更改为 CC=pathname/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 的 GUI 版本，可以通过命令行界面访问 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。

Agent Builder “编辑”菜单

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

• “清除输出日志”选项。清除输出日志中的信息。每当您选择“创建”或“配置”时，Agent Builder 都将向输出记录中附加状态消息。如果要不断地在 Agent Builder 中对源代码进行更改并重新生成输出，而且要隔离不同的状态消息，请在每次使用之前保存并清除日志文件。

• “保存日志文件”选项。将日志输出保存到文件中。Agent Builder 提供了浏览屏幕，通过该屏幕可以选择目录并指定文件名。

使用“创建”屏幕

创建资源类型的第一个步骤是完成“创建”屏幕（即启动 Agent Builder 后显示的屏幕）上的各项内容。下图显示键入了信息后的“创建”屏幕。

图 9–2 键入信息后的 Agent Builder“创建”屏幕

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

• “供应商名”。用于标识资源类型供应商的名称。通常是指定供应商的库存符号。但是，任何能够唯一标识供应商的名称都是有效的。仅可使用字母数字字符。

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

  ---

  注 –

  供应商名称和应用程序名称合在一起组成资源类型的全名。从 Solaris 9 操作系统开始，供应商名称和应用程序名称的组合可以超过九个字符。但是，如果您使用的是早于 Solaris 9 的操作系统版本，则供应商名称和应用程序名称的组合不能超过九个字符。

  ---

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

  不能在“RT 版本”字段中使用以下字符：

  • 空格键

  • Tab

  • 斜杠 (/)

  • 反斜杠 (\)

  • 星号 (*)

  • 问号 (?)

  • 逗号 (,)

  • 分号 (;)

  • 左方括号 ([)

  • 右方括号 (])

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

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

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

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

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

• "C" 和 "ksh"。指定生成的源代码所用的语言。尽管这些选项是互斥的，但是通过 Agent Builder，您可以使用 Korn shell 生成的代码创建资源类型，并再次使用相同的信息创建 C 生成的代码。请参见重复使用使用 Agent Builder 创建的代码。

• "GDS"。指定此服务为通用数据服务。第 10 章，普通数据服务包含关于创建和配置通用数据服务的更多详细信息。

如果 $PATH 变量中不包含 cc 编译器，则 Agent Builder 将灰显 C 单选按钮并允许您选择 ksh 单选按钮。要指定其他编译器，请参见安装和配置 Agent Builder结尾处的注释。

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

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

• 如果 Agent Builder 不能完成此步骤，请查看输出日志中的详细信息。

• 如果 Agent Builder 成功完成此步骤，请单击“下一步”以显示“配置”屏幕。通过“配置”屏幕，您可以完成资源类型的生成。

虽然生成完整资源类型的过程只有两步，但是您也可以在完成第一步（创建）之后退出 Agent Builder，您已指定的信息或 Agent Builder 已完成的工作并不会丢失。请参见重复使用使用 Agent Builder 创建的代码。

使用“配置”屏幕

Agent Builder 完成资源类型的创建后，如果您在“创建”屏幕上单击“下一步”，将显示如下图所示的“配置”屏幕。必须先创建资源类型才能访问“配置”屏幕。

图 9–3 Agent Builder 的“配置”屏幕

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

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

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

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

  ---

  注 –

  如果基本应用程序具有多个独立的进程树（每一个进程树都在进程监视工具 (PMF) 控制下以其各自的标记来启动），则不能只指定一个命令。您必须创建包含多个单独命令（启动每个进程树）的文本文件，并在“启动命令”文本字段中指定此文件的路径。请参见Agent Builder 使用前须知。本节列出了此文件正确运行需要的一些特性。

  ---

• “停止命令”。可以传送到任意 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 主机名替换 $hostnames 变量的值。为资源配置的主机名位于资源的 Network_resources_used 资源属性中。

如果配置的 Network_resources_used 属性具有多个主机名，则 $hostnames 变量将包含所有主机名，并用逗号将其隔开。

使用属性变量

您还可以通过使用属性变量，从 RGM 框架恢复选定 Sun Cluster 资源类型、资源和资源组属性的值。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 生成的源代码，并重新编译该代码来创建新的软件包。

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

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

步骤

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

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

   • 使用“文件”下拉式菜单中的“装入资源类型”选项。

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

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

3. 对现有资源类型进行所需更改。

   您可能更改生成该资源类型的代码的类型。例如，如果您最初创建了资源类型的 Korn shell 版本，却发现超时并需要 C 版本，则可以进行以下操作：

   • 装入现有的 Korn shell 资源类型。

   • 将输出语言更改为 C。

   • 单击“创建”以使 Agent Builder 生成该资源类型的 C 版本。

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

   1. 单击“创建”按钮创建该资源类型。

   2. 单击“下一步”将显示“配置”屏幕。

   3. 单击“配置”以配置资源类型，然后单击“取消”完成。

编辑已生成的源代码

为了简化创建资源类型的过程，Agent Builder 限制您可以指定的信息量，从而限制了生成的资源类型的范围。因此，要添加更多的复杂功能，您需要修改已生成的源代码或 RTR 文件。其他功能的示例包括添加其他属性的验证检查的代码，或调谐 Agent Builder 不显示的参数的代码。

源文件位于 install-directory/rt-name/src 目录中。Agent Builder 将注释嵌入在源代码中，您可以在这些注释中添加代码。这些注释的格式如下（针对 C 代码）：

/* User added code -- BEGIN vvvvvvvvvvvvvvv */
/* User added code -- END   ^^^^^^^^^^^^^^^ */

这些注释与 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 的命令行版本的使用过程与 GUI 相同。但是，与在 GUI 中键入信息不同，您需要把参数传送到 scdscreate 和 scdsconfig 命令。有关更多信息，请参见 scdscreate(1HA) 和 scdsconfig(1HA) 手册页。

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

步骤

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

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

   您可以指定属性变量。使用属性变量中介绍了属性变量。

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

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

   • 对于区环境中的 Solaris 10 OS，请做为全局区域中的全局管理员键入以下命令：

     # pkgadd -G -d . package-name

     如果软件包的内容不影响全局区域中与非全局区域共享的任何区域，则指定的软件包将被添加到全局区域中。

   • 对于任何其他版本的 Solaris OS 或非区环境中的 Solaris 10 OS，请键入以下命令：

     # pkgadd -d . package-name

5. （可选的）编辑已生成的源代码

6. 运行启动脚本。