test

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

第 4 章 资源管理 API 参考

本章提供组成资源管理 API (RMAPI) 的存取函数和回叫方法的参考信息， 其中列出并简单介绍了每一个函数和方法。 但是，RMAPI 手册页才是有关这些函数和方法的权威参考。

本章内容包括：

RMAPI 存取方法

API 提供可用来存取资源、资源类型和资源组特性以及其它群集信息的函数。 这些函数以 shell 命令和 C 函数的形式提供，从而使资源类型提供者可以实现 shell 脚本或 C 程序形式的控制程序。

RMAPI Shell 命令

shell 命令用于资源类型的回叫方法的 shell 脚本实现，这些资源类型表示群集的 RGM 所控制的服务。 您可以使用这些命令执行以下操作：

注意：

虽然本节中提供了对 shell 命令的简单介绍，但是 1HA 一节中各个手册页提供的信息才是有关 shell 命令的权威参考。 每个命令都对应一个具有相同名称的手册页，除非另外注明。

RMAPI 资源命令

您可以使用下面这些命令存取资源的信息或设置资源的 Status 和 Status_msg 特性。

scha_resource_get

存取关于 RGM 所控制的资源和资源类型的信息。它提供的信息与 scha_resource_get () 函数提供的相同。

scha_resource_setstatus

设置 RGM 所控制的资源的 Status 和 Status_msg 特性。 资源的监视器用它来指示监视器探测到的资源状态。 它提供的功能与 scha_resource_setstatus() C 函数相同。

注意：

虽然对于资源监视器来说 scha_resource_setstatus() 有特定用途，但是任何程序都可以调用该函数。

资源类型命令

下面的命令用来存取使用 RGM 登记的资源类型的信息。

scha_resourcetype_get

此命令提供与 scha_resourcetype_get() C 函数相同的功能。

资源组命令

您可以使用下面这些命令存取资源组的信息或重新启动资源组。

scha_resourcegroup_get

存取关于 RGM 所控制的资源组的信息。 此命令提供与 scha_resourcetype_get() C 函数相同的功能。

scha_control

请求重新启动 RGM 所控制的资源组或将其重定位到其它节点。 此命令提供与 scha_control() C 函数相同的功能。

群集命令

下面的命令用来存取有关群集的信息，例如节点名称、节点 ID、节点状态、群集名称、资源组等。

scha_cluster_get

此命令提供与 scha_cluster_get() C 函数相同的信息。

C 函数

C 函数用于资源类型的回叫方法的 C 程序实现，该资源类型表示群集的 RGM 所控制的服务。 您可以使用这些函数执行以下操作：

注意：

虽然本节中提供了对 C 函数的简单说明，但是各个 (3HA) 手册页中提供的信息才是有关 C 函数的权威参考。 每个函数都对应一个具有相同名称的手册页，除非另外注明。 有关 C 函数的输出变量和返回代码的信息，请参阅 scha_calls( 3HA) 手册页。

资源函数

下面这些函数用来存取关于 RGM 所管理的资源的信息或用来指示监视器探测到的资源状态。

scha_resource_open()、scha_resource_get () 和 scha_resource_close()

这些函数共同用于存取有关 RGM 所管理的资源的信息。 scha_resource_open() 函数用来初始化对资源的存取并返回 scha_resource_get () 的句柄，用于存取资源信息。 scha_resource_close() 函数可使该句柄无效并释放为 scha_resource_get() 的返回值分配的内存。

在 scha_resource_open() 返回资源的句柄后，通过群集重新配置或管理操作，可以更改资源； 在这种情况下，scha_resource_get() 通过该句柄获得的信息可能不准确。 对资源进行群集重新配置或管理操作时，RGM 将向 scha_resource_get () 返回 scha_err_seqid 错误代码，以表明该资源的信息可能已更改。 这是一个非致命性错误消息；函数将成功返回。 您可以选择忽略该消息并接受返回的信息；您也可以关闭当前句柄并打开一个新的句柄，以存取该资源的信息。

在单个手册页中描述了这三个函数。 您可以通过以下任意一个函数存取此手册页：scha_resource_open(3HA)、scha_resource_get(3HA) 或 scha_resource_close(3HA)。

scha_resource_setstatus()

设置 RGM 所控制的资源的 Status 和 Status_msg 特性。 资源的监视器使用此函数指示该资源的状态。

注意：

虽然对于资源监视器来说 scha_resource_setstatus() 有特定用途，但是任何程序都可以调用该函数。

资源类型函数

下面这些函数共同用于存取通过 RGM 登记的资源类型的信息。

scha_resourcetype_open()、scha_resourcetype_get()、scha_resourcetype_close()

scha_resourcetype_open() 函数用来初始化对资源类型的存取并返回 scha_resourcetype_get () 的句柄，用于存取资源类型的信息。 scha_resourcetype_close() 函数可使该句柄无效并释放为 scha_resourcetype_get() 的返回值分配的内存。

在 scha_resourcetype_open() 返回资源类型的句柄后，通过群集重新配置或管理操作，可以更改资源类型；在这种情况下，scha_resourcetype_get() 通过该句柄获得的信息可能不准确。 对资源类型进行群集重新配置或管理操作时，RGM 将向 scha_resourcetype_get() 返回 scha_err_seqid 错误代码，以表明该资源类型的信息可能已更改。 这是一个非致命性错误消息；函数将成功返回。 您可以选择忽略该消息并接受返回的信息；您也可以关闭当前句柄并打开一个新的句柄，以存取关于该资源类型的信息。

在单个手册页中描述了这三个函数。 您可以通过以下任意一个函数存取此手册页：scha_resourcetype_open(3HA)、scha_resourcetype_get(3HA) 或 scha_resourcetype_close(3HA)。

资源组函数

您可以通过下面这些函数存取资源组信息或重新启动该资源组。

scha_resourcegroup_open(3HA)、scha_resourcegroup_get(3HA) 和 scha_resourcegroup_close(3HA)

这些函数共同用于存取有关 RGM 所管理的资源组的信息。 scha_resourcegroup_open() 函数用来初始化对资源组的存取并返回 scha_resourcegroup_get () 的句柄，用于存取资源组信息。 scha_resourcegroup_close() 函数可使该句柄无效并释放为 scha_resourcegroup_get() 的返回值分配的内存。

可以在 scha_resourcegroup_open() 返回该资源的句柄后通过群集重新配置或管理操作更改资源类型，这时 scha_resourcegroup_get() 通过该句柄获得信息可能会不准确。 对资源组进行群集重新配置或管理操作时，RGM 将向 scha_resourcegroup_get () 返回 scha_err_seqid 错误代码，以表明该资源组的信息可能已更改。 这是一个非致命性错误消息；函数将成功返回。 您可以选择忽略该消息并接受返回的信息；您也可以关闭当前句柄并打开一个新的句柄，以存取关于该资源组的信息。

scha_control(3HA)

请求重新启动 RGM 所控制的资源组或将其重定位到其它节点。

群集函数

下面这些新函数用来存取或返回群集的信息。

scha_cluster_open(3HA)、scha_cluster_get(3HA)、 scha_cluster_close(3HA)

这些函数共同用来存取群集信息，例如节点名称、节点 ID 和节点状态、群集名称、资源组等。

可以在 scha_cluster_open() 返回该资源的句柄后通过群集重新配置或管理操作更改资源，这时 scha_cluster_get() 通过该句柄获得信息可能会不准确。 对群集进行重新配置或管理操作时，RGM 将向 scha_cluster_get() 返回 scha_err_seqid 错误代码，以表明该群集的信息可能已更改。 这是一个非致命性错误；函数将成功返回。 您可以选择忽略该消息并接受返回的信息；您也可以关闭当前句柄并打开一个新的句柄，以存取关于该群集的信息。

scha_cluster_getlogfacility(3HA)

返回用作群集记录的系统记录工具的数量。 使用返回值和 Solaris syslog() 函数将事件和状态消息记录到群集记录中。

scha_cluster_getnodename(3HA)

返回在其上调用该函数的群集节点的名称。

公用程序函数

此函数用来将错误代码转换成错误消息。

scha_strerror(3HA)

将某个 scha_ 函数返回的错误代码转换成相应的错误消息。 使用此函数和 logger 可以将消息记录到系统日志 (syslog) 中。

RMAPI 回叫方法

回叫方法是 API 提供的用来实现资源类型的主要元素。 当群集成员有所更改时（例如节点引导或崩溃），回叫方法将启用 RGM 来控制该群集中的资源。

注意：

RGM 以引导权限执行该回叫方法，因为客户机程序将控制群集系统上的 HA 服务。 安装和管理这些具有限制性文件拥有权和权限的方法。 有时需要为它们指定特权属主，例如 bin 或 root，请不要使它们可写。

本节介绍回叫方法变量和出口代码，还按以下分类列出并介绍了各个回叫方法：

注意：

虽然本节提供了回叫方法的简要说明（包括何时调用方法以及对资源的预期影响），但是 rt_callbacks( 1HA) 手册页才是有关回叫方法的权威参考。

方法变量

RGM 按照以下方式调用回叫方法： 


method -R resource-name -T type-name -G group-name

其中 method 是登记为 Start、Stop 或其它回叫方法的程序的路径名。 资源类型的回叫方法在其登记文件中进行声明。

所有回叫方法变量都作为标记值传送，-R 用来表示资源实例的名称，-T 用来表示资源的类型，-G 用来表示配置该资源的组。 使用变量和存取函数来检索关于资源的信息。

Validate 方法通过附加变量（所调用资源和资源组的特性值）调用。

有关详细信息，请参阅 scha_calls(3HA)。

出口代码

所有回叫方法都定义了相同的出口代码，以指定方法调用对资源状态的影响。 scha_calls (3HA) 手册页中介绍了所有这些出口代码。 出口代码为：

RGM 还可处理回叫方法执行过程中的不正常失败，例如超时和信息转储。

方法实现必须使用每个节点上的 syslog 输出失败信息。 并不能保证写入 stdout 或 stderr 的输出信息一定会传送到用户（尽管它当前显示在本地节点的控制台中）。

控制和初始化回叫方法

主要的控制和初始化回叫方法用来启动和停止资源。 其它方法用来执行对资源的初始化和终止代码。

Start

当包含该资源的资源组在某个群集节点联机时，会对此节点调用此必需方法。 此方法激活该节点上的资源。

在所激活的资源启动并且在本地节点上可用之前，Start 方法不应退出。 因此，在退出之前，Start 方法应轮询该资源，以确定该资源是否已启动。 此外，您应该为此方法设置足够长的超时值。 例如，某些资源（例如数据库守护程序）需要较长的时间进行启动，因此，就要求该方法具有较长的超时值。

RGM 对 Start 方法失败的响应方式取决于 Failover_mode 特性的设置。

资源类型登记文件中的 START_TIMEOUT 特性用来设置资源的 Start 方法的超时值。

Stop

当包含该资源的资源组在群集节点上脱机时，将对该群集节点调用此必需方法。 如果该资源处于激活状态，则此方法可取消激活该资源。

在所控制资源在本地节点上完全停止所有活动并关闭所有文件描述符之前，Stop 方法不应退出， 否则，因为 RGM 将认为该资源已经停止，而实际上它仍处于活动状态，就会导致数据被破环。 避免数据被破坏的最可靠方法是终止与该资源有关的本地节点上的所有进程。

在退出之前，Stop 方法应该轮询该资源，以确定该资源是否停止。 此外，您应该为此方法设置足够长的超时值。 例如，某些资源（如数据库守护程序）需要较长的时间进行停止操作，因此，就要求该方法具有较长的超时值。

RGM 对 Stop 方法失败的响应方式取决于 Failover_mode 特性的设置 （请参阅表 A–2）。

资源类型登记文件中的 STOP_TIMEOUT 特性用来设置资源的 Stop 方法的超时值。

Init

当资源变为被管理的资源时（资源所在的资源组从未被管理状态切换到已管理状态或资源创建在已被管理的资源组中），调用此可选方法以对资源执行一次性初始化。 对哪些节点调用该方法由 Init_nodes 资源特性决定。

Fini

当资源变为未被管理的资源时（资源所在的资源组切换到未被管理状态或从被管理的资源组中删除了该资源），调用此可选方法以清除资源。 对哪些节点调用该方法由 Init_nodes 资源特性决定。

Fini

此可选方法与 Init 相似，在包含资源的资源组处于 RGM 的管理之下后调用此方法可初始化与群集相连接的节点上的资源。 对哪些节点调用该方法由 Init_nodes 资源特性决定。 引导或重新引导操作导致该节点连接或重新连接群集时，将调用 Boot 方法。

注意：

Init、Fini 或 Boot 方法的失败将导致 syslog() 函数生成错误消息，但是不会影响该资源的 RGM 管理。

管理支持方法

对资源进行的管理操作包括设置和更改资源特性。 Validate 和 Update 回叫方法将启用资源类型实现来介入这些管理操作。

Validate

当创建了资源且管理操作更新资源或其资源组的特性时，调用此可选方法。 将对由资源类型的 Init_nodes 特性指定的一组群集节点调用此方法。 在进行创建或更新之前，将调用 Validate，任何节点上的方法返回失败出口代码都将导致创建或更新操作取消。

仅当通过管理操作更改资源或资源组特性时（而不是在 RGM 设置特性时或监视器设置资源组特性 Status 和 Status_msg 时），才调用 Validate。

Update

调用此可选方法将特性已更改的消息通知正在运行的资源。 在管理操作成功地设置了资源及其资源组后，将调用 Update。 对资源处于联机状态的节点调用此方法。 该方法将通过 API 存取函数来读取可能会影响活动资源的特性值并相应地调整正在运行的资源。

Update 方法的失败将导致 syslog() 函数生成错误消息，但是不会影响该资源的 RGM 管理。

与网络相关的回叫方法

使用网络地址资源的服务可能要求按某种顺序（相对于网络地址配置）执行启动或停止步骤。 以下可选回叫方法 Prenet_start 和 Postnet_stop 使资源类型实现在配置/取消配置相关网络地址之前/之后执行特殊的启动和关闭操作。

Prenet_start

在配置同一资源组中的网络地址之前，将调用此可选方法执行特殊的启动操作。

Postnet_stop

在同一资源组中的网络地址配置为停止使用之后，调用此可选的方法执行特殊停机操作。

监视器控制回叫方法

资源类型实现中可包含一个用来监视资源性能、报告其状态或针对资源失败情况进行操作的程序（可选）。 在资源类型实现中，Monitor_start、Monitor_stop 和 Monitor_check 方法支持资源监视器的实现。

Monitor_start

资源启动后，将调用此可选方法来启动该资源的监视器。

Monitor_stop

在停止资源前，调用此可选方法停止资源的监视器。

Monitor_check

在资源组重新定位到节点之前，将调用此可选方法来评估该节点的可靠性。 必须实现 Monitor_check 方法，以免与当前运行的其它方法发生冲突。