本章列出并简要介绍了构成资源管理 API (RMAPI) 的访问函数和回调方法。但是,RMAPI 手册页才是有关这些函数和方法的权威参考。
本章包括以下主题:
RMAPI 访问方法 – 以 shell 脚本命令和 C 函数的形式
RMAPI 回调方法 – rt_callbacks(1HA) 手册页中进行介绍
API 提供了用于访问资源类型、资源和资源组属性以及其他群集信息的函数。这些函数是以 shell 命令和 C 函数的形式提供的,使您可以实现 shell 脚本或 C 程序形式的控制程序。
Shell 命令是在资源类型的回调方法的 shell 脚本实现中使用的,这些资源类型表示由群集的 RGM 控制的服务。可以使用这些命令完成以下任务:
访问有关资源类型、资源、资源组和群集的信息。
使用监视器时,设置资源的 Status 和 Status_msg 属性。
请求重新启动或重定位资源组。
此部分仅简要介绍了 shell 命令,1HA 手册页中提供了 shell 命令的权威性参考。如果未另加说明,与命令同名的手册页即与相应命令相关。
使用这些命令,您可以访问关于资源的信息或设置资源的 Status 和 Status_msg 属性。
访问有关 RGM 控制下的资源或资源类型的信息。此命令提供的信息与 scha_resource_get() C 函数相同。有关详细信息,请参见 scha_resource_get(1HA) 手册页。
设置 RGM 控制下的资源的 Status 和 Status_msg 属性。资源的监视器使用此命令来指明监视器识别出的资源状态。此命令提供与 scha_resource_setstatus() C 函数相同的功能。scha_resource_setstatus(1HA) 手册页中对此命令进行了详细介绍。
虽然对于资源监视器来说 scha_resource_setstatus() 有特定用途,但是任何程序都可以调用该函数。
访问有关向 RGM 注册的资源类型的信息。此命令提供与 scha_resourcetype_get() C 函数相同的功能。scha_resourcetype_get(1HA) 手册页中对此命令进行了详细介绍。
访问关于 RGM 控制下的资源组的信息。此命令提供与 scha_resourcetype_get() C 函数相同的功能。scha_resourcegroup_get(1HA) 手册页中对此命令进行了详细介绍。
请求重新启动 RGM 控制下的资源组或将其重定位到其他节点。此命令提供与 scha_control() C 函数相同的功能。scha_control(1HA) 手册页中对此命令进行了详细介绍。
访问关于群集的信息,例如群集名称、节点名称、ID、状态和资源组。此命令提供的信息与 scha_cluster_get() C 函数相同。scha_cluster_get(1HA) 手册页中对此命令进行了详细介绍。
C 函数是在资源类型的回调方法的 C 程序实现中使用的,这些资源类型表示由群集的 RGM 控制的服务。可以使用这些函数完成以下任务:
访问关于资源类型、资源、资源组和群集的信息。
使用监视器时,设置资源的 Status 和 Status_msg 属性。
请求重新启动或重定位资源组。
将错误代码转换为相关错误消息。
此部分仅简要介绍了 C 函数,3HA 手册页中提供了 C 函数的权威性参考。如果未另加说明,与命令同名的手册页即与相应命令相关。有关 C 函数的输出参数和返回码的信息,请参见 scha_calls(3HA) 手册页。
这些函数用于访问有关 RGM 所管理的资源的信息,或指明监视器识别出的资源状态。
这些函数用于访问关于由 RGM 管理的资源的信息。scha_resource_open() 函数将对资源的访问进行初始化,并为 scha_resource_get()(该函数用于访问资源信息)返回句柄。scha_resource_close() 函数将使该句柄无效,并释放为 scha_resource_get() 返回值分配的内存。
当 scha_resource_open() 返回资源的句柄之后,可以通过群集重新配置或者管理操作更改资源。因此,scha_resource_get() 通过该句柄获取的信息就可能不准确。在对资源进行群集重新配置或管理操作的情况下,RGM 将把 scha_err_seqid 错误代码返回给 scha_resource_get(),以指明关于资源的信息可能已更改。此错误消息不是致命的。函数将成功返回。您可以选择忽略此消息并接受返回的信息,也可以关闭当前句柄并打开新句柄以访问关于资源的信息。
有一个手册页介绍了这三个函数。您可以通过 scha_resource_open(3HA)、scha_resource_get(3HA) 或 scha_resource_close(3HA) 中的任何一个函数访问此手册页。
设置 RGM 控制下的资源的 Status 和 Status_msg 属性。资源的监视器使用此函数指示该资源的状态。
虽然对于资源监视器来说 scha_resource_setstatus() 有特定用途,但是任何程序都可以调用该函数。
scha_resourcetype_open() 函数将对资源的访问进行初始化,并为 scha_resourcetype_get()(该函数用于访问资源类型信息)返回句柄。scha_resourcetype_close() 函数将使句柄无效,并释放为 scha_resourcetype_get() 返回值分配的内存。
当 scha_resourcetype_open() 返回资源类型的句柄之后,可以通过群集重新配置或管理操作更改资源类型。因此,scha_resourcetype_get() 通过该句柄获取的信息可能不准确。在对资源类型进行群集重新配置或管理操作的情况下,RGM 将把 scha_err_seqid 错误代码返回给 scha_resourcetype_get(),以指明关于资源类型的信息可能已更改。此错误消息不是致命的。函数将成功返回。您可以选择忽略此消息并接受返回的信息,也可以关闭当前句柄并打开新句柄以访问关于资源类型的信息。
有一个手册页介绍了这三个函数。您可以通过任一单个函数 scha_resourcetype_open(3HA)、scha_resourcetype_get(3HA) 或 scha_resourcetype_close(3HA) 访问此手册页。
这些函数用于访问关于由 RGM 管理的资源组的信息。scha_resourcegroup_open() 函数用来初始化对资源组的访问并返回 scha_resourcegroup_get () 的句柄,用于访问资源组信息。scha_resourcegroup_close() 函数将使句柄无效,并释放为 scha_resourcegroup_get() 返回值分配的内存。
当 scha_resourcegroup_open() 返回资源组句柄之后,可以通过群集重新配置或管理操作更改资源组。因此,scha_resourcegroup_get() 通过该句柄获取的信息可能不准确。在对资源组进行群集重新配置或管理操作的情况下,RGM 将把 scha_err_seqid 错误代码返回给 scha_resourcegroup_get(),以指明关于资源组的信息可能已更改。此错误消息不是致命的。函数将成功返回。您可以选择忽略此消息并接受返回的信息,也可以关闭当前句柄并打开新句柄以访问关于资源组的信息。
有一个手册页介绍了这三个函数。您可以通过任一单个函数 scha_resourcegroup_open(3HA)、scha_resourcegroup_get(3HA) 和 scha_resourcegroup_close(3HA) 访问此手册页。
请求重新启动 RGM 控制下的资源组或将其重定位到其他节点。scha_control(3HA) 手册页中对此函数进行了详细介绍。
这些函数用于访问关于群集的信息,例如群集名称、节点名称、ID、状态和资源组。
当 scha_cluster_open() 返回群集的句柄之后,可以通过重新配置或管理操作更改群集。因此,scha_cluster_get() 通过该句柄获取的信息可能不准确。在对群集进行重新配置或管理操作的情况下,RGM 将把 scha_err_seqid 错误代码返回给 scha_cluster_get(),以指明关于群集的信息可能已更改。此错误消息不是致命的。函数将成功返回。您可以选择忽略此消息并接受返回的信息,也可以关闭当前句柄并打开新句柄以访问关于群集的信息。
有一个手册页介绍了这三个函数。您可以通过任一单个函数 scha_cluster_open(3HA)、scha_cluster_get(3HA) 和 scha_cluster_close(3HA) 访问此手册页。
返回用作群集日志的系统日志工具的编号。将返回值与 syslog() Solaris 函数结合使用可以将事件和状态消息记录到群集日志中。scha_cluster_getlogfacility(3HA) 手册页中对此函数进行了详细介绍。
返回在其上调用该函数的群集节点的名称。scha_cluster_getnodename(3HA) 手册页中对此函数进行了详细介绍。
将某个 scha_ 函数返回的错误代码转换为相应的错误消息。将此函数与 logger 命令结合使用可以将消息记录到 Solaris 系统日志 (syslog) 中。scha_strerror(3HA) 手册页中对此函数进行了详细介绍。
回调方法是为实现资源类型由 API 提供的主要元素。当群集成员资格发生更改(例如节点引导或崩溃)时,回调方法使 RGM 可以控制群集中的资源。
回调方法是由具有超级用户权限或具有等效角色权限的 RGM 执行的,因为客户机程序控制了群集系统中的 HA 服务。安装和管理这些具有限制性文件拥有权和权限的方法。具体来讲,就是要赋予这些方法一个特权拥有者(例如 bin 或 root),并使这些方法不可写。
此部分介绍了回调方法参数和退出代码。介绍了以下几种类别的回调方法:
控制和初始化方法
管理支持方法
与网络相关的方法
监视器控制方法
此部分简要介绍了回调方法,包括何时运行方法和对资源的预期影响。但 rt_callbacks(1HA) 手册页才是回调方法的权威性参考。
method -R resource-name -T type-name -G group-name
其中 method 是注册为 Start、Stop 或其他回调方法的程序的路径名。资源类型的回调方法在其注册文件中进行声明。
所有回调方法参数均以带标志的值的形式进行传递,如下所示:
-R 表示资源实例的名称
-T 表示资源的类型
-G 表示资源配置在其中的组
使用变量和访问函数来检索关于资源的信息。
Validate 方法与其他参数(包括对其调用该方法的资源和资源组的属性值)一起调用。
scha_calls(3HA) 手册页包含更多信息。
所有回调方法具有相同退出代码。定义这些退出代码是为了指定方法调用对资源状态的影响。scha_calls(3HA) 手册页对这些退出代码进行了详细介绍。退出代码的两大类别为:
0 – 方法已成功
所有非零值 – 方法已失败
RGM 还可以处理在执行回调方法时出现的异常失败,例如超时和核心转储。
方法实现必须使用每个节点上的 syslog() 来输出失败信息。虽然写入到 stdout 或 stderr 的输出当前显示在本地节点的控制台上,但这并不保证会将该输出传送给用户。
主要的控制和初始化回调方法用于启动和停止资源。其它方法用来执行对资源的初始化和终止代码。
当包含资源的资源组在群集节点上联机后,RGM 将在该节点上运行此方法。此方法激活该节点上的资源。
在 Start 方法激活的资源启动并在本地节点上可用之前,不应退出 Start 方法。因此,在退出之前,Start 方法应轮询该资源,以确定该资源是否已启动。另外,应为此方法设置足够长的超时值。例如,诸如数据库守护进程之类的特定资源需要较长的时间才能启动,因而要求方法有较长的超时值。
RGM 对 Start 方法失败的响应方式取决于 Failover_mode 属性的设置。
资源类型注册 (RTR) 文件中的 Start_timeout 属性用于为资源的 Start 方法设置超时值。
当包含资源的资源组在群集节点上脱机后,RGM 将在该节点上运行此必需方法。如果该资源处于激活状态,则此方法可取消激活该资源。
在 Stop 方法控制的资源完全停止该资源在本地节点上的所有活动并关闭所有文件描述符之前,不应退出 Stop 方法。否则,由于 RGM 假定资源已停止,而实际上该资源仍处于活动状态,可能会导致损坏数据。避免损坏数据的最安全的方法是终止与资源相关的本地节点上的所有进程。
在退出之前,Stop 方法应该轮询该资源,以确定该资源是否停止。另外,应为此方法设置足够长的超时值。例如,诸如数据库守护进程之类的特定资源需要较长的时间才能停止,因而要求方法有较长的超时值。
RGM 响应 Stop 方法失败的方法取决于 Failover_mode 属性的设置。请参见资源属性。
RTR 文件中的 Stop_timeout 属性用于为资源的 Stop 方法设置超时值。
当资源成为受管理的资源后,RGM 将运行此可选方法来执行对资源的一次性初始化。当 RGM 的资源组从不受管理状态切换为受管理状态时,或者当在受管理资源组中创建资源时,RGM 将运行此方法。对 Init_nodes 资源属性所标识的节点调用此方法。
当资源成为不受管理的资源之后,RGM 将运行此可选方法以清理该资源。当 RGM 的资源组切换为不受管理的状态时,或从受管理的资源组中删除资源时,RGM 将运行此方法。对 Init_nodes 资源属性所标识的节点调用此方法。
当包含资源的资源组已经受 RGM 管理之后,RGM 将运行此可选方法(类似于 Init)以初始化加入了群集的节点上的资源。RGM 将在由 Init_nodes 资源属性标识的节点上运行此方法。由于引导或重新引导节点而使节点加入或重新加入群集时,将调用 Boot 方法。
Init、Fini 或 Boot 方法的失败将导致 syslog() 函数生成错误消息。但是,RGM 对资源的管理不受其他方面的影响。
对资源进行的管理操作包括设置和更改资源属性。Validate 和 Update 回调方法使资源类型实现可以执行这些管理操作。
创建资源时,以及群集管理员更新资源或其包含资源组的属性时,RGM 都将调用此可选方法。对资源类型的 Init_nodes 属性所标识的群集节点集调用此方法。Validate 是在应用创建或更新之前调用的。来自任何节点上的方法的失败退出代码都会导致取消创建或更新操作。
仅当群集管理员更改资源或资源组属性时才会调用 Validate,而在 RGM 设置属性时,或者监视器设置 Status 和 Status_msg 资源属性时不调用该方法。
RGM 将运行此可选方法以通知正在运行的资源,通知将说明属性已被更改。设置资源或资源组的属性的管理操作成功后,RGM 将运行 Update。对资源处于联机状态的节点调用此方法。方法将使用 API 访问函数以读取可能影响活动资源的属性值并相应调整正在运行的资源。
Update 方法的失败将导致 syslog() 函数生成错误消息。但是,RGM 对资源的管理不受其他方面的影响。
使用网络地址资源的服务可能需要以与网络地址配置相关的特定顺序执行启动或停止步骤。以下可选回调方法 Prenet_start 和 Postnet_stop 用于启用资源类型实现以在配置或取消配置相关网络地址之前和之后执行启动和关闭操作。
在配置同一资源组中的网络地址之前,调用此可选方法以执行特殊的启动操作。
将同一资源组中的网络地址配置为关闭之后,调用此可选方法以执行特殊的关闭操作。
资源类型实现可以可选包括用于监视资源性能、报告资源的状态或在资源出现故障时采取措施的程序。Monitor_start、Monitor_stop 和 Monitor_check 方法支持在资源类型实现中实现资源监视器。
资源启动后,将调用此可选方法来启动该资源的监视器。
在停止资源前,调用此可选方法停止资源的监视器。
在将资源组重定向到某个节点之前,将调用此可选方法以评定该节点的可靠性。必须实现 Monitor_check 方法,这样该方法才不会与同时运行的其他方法发生冲突。