Sun Cluster 数据服务开发者指南(适用于 Solaris OS)

使用 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 之前,请检验以下信息:


注意:

除了标准 cc 编译器之外,您可以将其它编译器与 Agent Builder 一起使用。 执行此操作的方法之一是在 $PATH 中创建从 cc 到其它编译器(例如 gcc)的符号链接。 另一个方法是将 make 程序的描述文件中的编译器定义(当前为 CC=cc)更改为其它编译器的完整路径。 例如,在 Agent Builder 生成的 make 程序的描述文件中,将 CC=cc 更改为 CC=pathname/gcc。 在这种情况下,您不能直接运行 Agent Builder,而是必须使用 makemake pkg 命令生成数据服务代码和软件包。


启动 Agent Builder

输入以下命令启动 Agent Builder:


% /usr/cluster/bin/scdsbuilder

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

图形 9–1 初始屏幕

标题为“SunPlex Agent Builder”的对话框,显示了 Agent Builder 的主屏幕


注意:

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


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

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

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


注意:

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


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

使用“创建”屏幕

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

图形 9–2 “创建”屏幕

显示已输入信息的“创建”屏幕的对话框

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


注意:

如果 $PATH 中未包含 cc 编译器,则 Agent Builder 将灰显“C ”选项按钮并在 ksh 按钮中加入一个选中标记。 要指定其它编译器,请参阅安装和配置 Agent Builder结尾处的说明。


输入必需信息后,请单击“创建”按钮。 屏幕底部的“输出记录”用来显示 Agent Builder 正在执行的操作。 您可以使用“编辑”菜单中的“保存输出记录”命令来保存输出记录中的信息。

完成后,Agent Builder 将显示一条成功消息或一条警告消息。警告消息表明 Agent Builder 无法完成此步骤,您应该检查输出记录获取详细信息。

如果 Agent Builder 成功地完成了操作,您可以单击“下一步”按钮进入“配置”屏幕,使用该屏幕您可以完成生成资源类型的过程。


注意:

虽然生成完整资源类型的过程只有两步,但是您也可以在完成第一步(创建)之后退出 Agent Builder,您已输入的信息或 Agent Builder 已完成的工作并不会丢失(请参阅重复使用完成的工作)。


使用“配置”屏幕

Agent Builder 完成创建资源类型的工作后,如果您选择“创建”屏幕上的“下一步”按钮,将会显示“配置”屏幕,如下图所示。 必须先创建资源类型才能存取“配置”屏幕。

图形 9–3 “配置”屏幕

显示“配置”屏幕的对话框

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

使用 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 生成的现有资源类型。

  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. 运行启动脚本。