使用 Agent Builder

本节介绍 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 不需要专门进行安装。 Agent Builder 包含在 SUNWscdev 软件包中，缺省情况下在标准 Sun Cluster 软件安装过程中会安装该软件包（《Sun Cluster 软件安装指南（适用于 Solaris OS）》中包含有详细信息）。 使用 Agent Builder 之前，请检验以下信息：

• Java 是否包含在 $PATH 变量中。Agent Builder 依赖于 Java（Java 开发工具 1.3.1 版或更高版本），如果 $PATH 中未包含 Java，则 scdsbuilder 将返回一条错误消息。

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

• cc 编译器是否包含在 $PATH 变量中。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：

% /usr/cluster/bin/scdsbuilder

将显示初始的 Sun Builder 屏幕，如下图所示。

图形 9–1 初始屏幕

如果无法存取 GUI 版本，则可以通过命令行界面存取 Agent Builder（请参阅使用 Agent Builder 的命令行版本）。

Agent Builder 提供了两个屏幕，用来指导您完成创建新资源类型的过程：

1. 创建 — 在此屏幕上，您需要提供关于要创建的资源类型的基本信息，例如其名称和所生成文件的工作目录（即您创建并配置资源类型模板的目录）。 您还需确定要创建的资源的种类（“可伸缩”或“故障切换”）、基本应用程序是否支持网络（即该应用程序是否使用网络与其客户机通信）以及要生成的代码的类型（C、ksh 或 GDS）。 有关 GDS（普通数据服务）的信息，请参阅第 10 章，普通数据服务。 您必须完成此屏幕上的信息并选择“创建”来生成相应的输出后才会显示“配置”屏幕。

2. 配置 — 在此屏幕上，您需要提供一条启动应用程序的命令。 您还可以提供停止或探测应用程序的命令（可选操作）。 如果您不指定这些命令，生成的输出将使用信号停止应用程序并提供缺省探测机制（请参阅使用“配置”屏幕中对探测命令的说明）。 此屏幕还使您可以分别更改这三个命令的超时值。

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

如果您对如何使用 Agent Builder 各个屏幕上的任意按钮或菜单命令存在疑问，请参阅浏览 Agent Builder。

使用“创建”屏幕

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

图形 9–2 “创建”屏幕

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

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

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

  ---

  注意：

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

  ---

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

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

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

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

• 支持网络 — 指定基本应用程序是否支持网络；即，它是否使用网络与客户进行通信。 选中该框表示指定支持网络；否则表示指定不支持网络。 Korn shell 代码要求应用程序必须是支持网络的。 因此，如果您选中 ksh 或 GDS 按钮，则 Agent Builder 将复选该框并将其灰显。

• C、ksh — 指定生成的源代码的语言。 尽管这些选项是互斥的，但是借助 Agent Builder 您可以先使用 ksh 类型的生成代码创建资源类型，然后重复使用相同信息创建 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 以启动基本应用程序的完整命令行。 您必须指定此命令。 您可以在提供的字段中键入该命令，也可以使用“浏览”按钮定位包含用来启动应用程序的命令的文件。

  完整的命令行中必须包含启动应用程序必需的所有内容，例如主机名、端口号、指向配置文件的路径等。 如果应用程序需要在命令行上指定一个主机名，则可以使用 Agent Builder 定义的 $hostnames 变量（请参阅使用 Agent Builder $hostnames 变量）。

  请不要将命令置于双引号（““）中。

  ---

  注意：

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

  ---

• 停止命令 — 可以传送到任意 UNIX shell 以停止基本应用程序的完整命令行。 您可以在提供的字段中键入该命令，也可以使用“浏览”按钮定位包含用来停止应用程序的命令的文件。 如果应用程序需要在命令行上指定一个主机名，则可以使用 Agent Builder 定义的 $hostnames 变量（请参阅使用 Agent Builder $hostnames 变量）。

  此命令是可选的。 如果您不指定停止命令，则生成的代码将使用信号（位于 Stop 方法中）停止该应用程序，如下所示。

  • Stop 方法发送 SIGTERM 以停止应用程序，等待应用程序退出的时间长度为超时值的 80%。

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

  • 如果 SIGKILL 也未成功，则 Stop 方法将在未成功的状态下退出（超时值的剩余 5% 视为额外开销）。

  ---

  小心：

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

  ---

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

  通常，您需指定基本应用程序的简单客户机。 如果您不指定探测命令，则生成的代码仅连接到资源所用的端口（或仅从该端口上断开连接）。如果探测成功，则表明该应用程序运行正常。 探测命令仅适用于支持网络的应用程序。 Agent Builder 通常会生成探测命令，但是对于不支持网络的应用程序，Agent Builder 将禁止该探测命令。

  如果应用程序需要在探测命令行上指定一个主机名，则可以使用 Agent Builder 定义的 $hostnames 变量（请参阅使用 Agent Builder $hostnames 变量）。

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

使用 Agent Builder $hostnames 变量

对于很多应用程序（特别是支持网络的应用程序），必须在命令行上将主机（在该主机上应用程序进行监听并处理服务用户请求）的名称传送给应用程序。 因此，在大多数情况下，必须为目标资源类型的启动、停止和探测命令指定主机名参数（在“配置”屏幕上）。 但是，应用程序进行监听的主机的名称是群集特有的 — 该主机名是资源在群集上运行时确定的，而不能在 Agent Builder 生成资源类型代码时确定。

要解决此问题，Agent Builder 提供了您可以在启动、停止和探测命令的命令行中指定的 $hostnames 变量。 指定 $hostnames 变量时就像指定实际主机名一样，例如：

/opt/network_aware/echo_server -pport_no-l $hostnames

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

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

创建具有多个独立的进程树的资源类型

Agent Builder 可以创建具有多个独立进程树的应用程序的资源类型。 从 PMF 分别监视并启动这些进程树这一方面来说，这些进程树是独立的。 PMF 用进程树自身的标记启动每一个进程树。

仅当您指定生成的资源代码为 C 时，才能通过 Agent Builder 创建具有多个独立进程树的资源类型。当指定的代码为 ksh 或 GDS 时，您无法使用 Agent Builder 创建这些资源类型。 要在已指定 ksh 或 GDS 的情况下创建这些资源类型，您必需以手动的方式编写代码。

在基本应用程序具有多个独立的进程树的情况下，不能通过仅指定一个命令行来启动该应用程序， 而是必须创建一个文本文件，并在每一行中指定指向用来启动一个应用程序进程树的命令的完整路径。 此文件中不能包含任何空行。 您需要在“配置”屏幕上的“启动命令”文本字段中指定此文本文件。

确保此文件没有执行权限以使 Agent Builder 能够区分此文件，其目的是从包含多个命令的简单可执行脚本中启动多个进程树。 如果此文本文件被赋予了执行权限，则资源将在群集上正常启用，但是所有的命令都将在一个 PMF 标记下启动，这样就无法由 PMF 分别监视和重新启动进程树。

重复使用完成的工作

使用 Agent Builder， 您可以通过多种方式利用已完成的工作。

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

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

克隆现有的资源类型

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

1. 将现有资源类型装入 Agent Builder。 可以使用以下两种方法之一来执行此操作：

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

   2. 使用“文件”菜单中的“装入资源类型”命令。

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

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

3. 进行更改。

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

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

   选择“创建”以创建该资源类型。 选择“下一步”进入“配置”屏幕。 选择“配置”以配置该资源类型，然后选择“取消”完成操作。

编辑已生成的源代码

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

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

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

在 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(1HA) 和 scdsconfig(1HA) 命令，不是在图形用户界面中输入信息。

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

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

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

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

4. 使用 pkgadd(1M) 命令安装您使用 scdscreate 创建的软件包。

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

6. 运行启动脚本。