test

Sun Cluster Data Services Developer's Guide for Solaris OS

Chapter 3 Resource Management API Reference

This chapter lists and briefly describes the access functions and callback methods that make up the Resource Management API (RMAPI). However, the definitive reference for these functions and methods is the RMAPI man pages.

This chapter covers the following topics:

RMAPI Access Methods

The API provides functions to access resource type, resource, and resource group properties, and other cluster information. These functions are provided both in the form of shell commands and C functions, which enable you to implement control programs as shell scripts or as C programs.

RMAPI Shell Commands

Shell commands are used in shell script implementations of the callback methods for resource types that represent services that are controlled by the cluster's RGM. You can use these commands to complete the following tasks:

Note –

Although this section provides brief descriptions of the shell commands, the 1HA man pages provide the definitive reference for the shell commands. A man page of the same name is associated with each command, unless otherwise noted.

RMAPI Resource Commands

You can access information about a resource or set the Status and Status_msg properties of a resource with these commands.

scha_resource_get

Accesses information about a resource or resource type that is under the control of the RGM. This command provides the same information as the scha_resource_get() C function. For details, see the scha_resource_get(1HA) man page.

scha_resource_setstatus

Sets the Status and Status_msg properties of a resource that is under the control of the RGM. This command is used by the resource's monitor to indicate the state of the resource as perceived by the monitor. This command provides the same functionality as the scha_resource_setstatus() C function. This command is described in more detail in the scha_resource_setstatus(1HA) man page.

Note –

Although scha_resource_setstatus() is of particular use to a resource monitor, any program can call it.

Resource Type Command

scha_resourcetype_get

Accesses information about a resource type that is registered with the RGM. This command provides the same functionality as the scha_resourcetype_get() C function. This command is described in more detail in the scha_resourcetype_get(1HA) man page.

Resource Group Commands

You can access information about or restart a resource group with these commands.

scha_resourcegroup_get

Accesses information about a resource group that is under the control of the RGM. This command provides the same functionality as the scha_resourcetype_get() C function. This command is described in more detail in the scha_resourcegroup_get(1HA) man page.

scha_control

Requests the restart of a resource group that is under the control of the RGM or its relocation to a different node. This command provides the same functionality as the scha_control() C function. This command is described in more detail in the scha_control(1HA) man page.

Cluster Command

scha_cluster_get

Accesses information about a cluster, such as the cluster name, node names, IDs, states, and resource groups. This command provides the same information as the scha_cluster_get() C function. This command is described in more detail in the scha_cluster_get(1HA) man page.

C Functions

C functions are used in C program implementations of the callback methods for resource types that represent services that are controlled by the cluster's RGM. You can use these functions to complete the following tasks:

Note –

Although this section provides brief descriptions of the C functions, the 3HA man pages provide the definitive reference for the C functions. A man page of the same name is associated with each function, unless otherwise noted. See the scha_calls(3HA) man page for information about the output arguments and return codes of the C functions.

Resource Functions

These functions access information about a resource that is managed by the RGM or indicate the state of the resource as perceived by the monitor.

scha_resource_open(), scha_resource_get(), and scha_resource_close()

These functions access information about a resource that is managed by the RGM. The scha_resource_open() function initializes access to a resource and returns a handle for scha_resource_get(), which accesses the resource information. The scha_resource_close() function invalidates the handle and frees memory that is allocated for scha_resource_get() return values.

A resource can change, through cluster reconfiguration or administrative action, after scha_resource_open() returns the resource's handle. As a result, the information that scha_resource_get() obtains through the handle might be inaccurate. In cases of cluster reconfiguration or administrative action on a resource, the RGM returns the scha_err_seqid error code to scha_resource_get() to indicate that information about the resource might have changed. This error message is non-fatal. The function returns successfully. You can choose to ignore the message and accept the returned information. Alternatively, you can close the current handle and open a new handle to access information about the resource.

One man page describes these three functions. You can access this man page through any of the individual functions scha_resource_open(3HA), scha_resource_get(3HA), or scha_resource_close(3HA).

scha_resource_setstatus()

Sets the Status and Status_msg properties of a resource that is under the control of the RGM. The resource's monitor uses this function to indicate the resource's state.

Note –

Although scha_resource_setstatus() is of particular use to a resource monitor, any program can call it.

Resource Type Functions

These functions access information about a resource type that is registered with the RGM.

scha_resourcetype_open(), scha_resourcetype_get(), and scha_resourcetype_close()

The scha_resourcetype_open() function initializes access to a resource and returns a handle for scha_resourcetype_get(), which accesses the resource type information. The scha_resourcetype_close() function invalidates the handle and frees memory that is allocated for scha_resourcetype_get() return values.

A resource type can change, through cluster reconfiguration or administrative action, after scha_resourcetype_open() returns the resource type's handle. As a result, the information that scha_resourcetype_get() obtains through the handle might be inaccurate. In cases of cluster reconfiguration or administrative action on a resource type, the RGM returns the scha_err_seqid error code to scha_resourcetype_get() to indicate that information about the resource type might have changed. This error message is non-fatal. The function returns successfully. You can choose to ignore the message and accept the returned information. Alternatively, you can close the current handle and open a new handle to access information about the resource type.

One man page describes these three functions. You can access this man page through any of the individual functions scha_resourcetype_open(3HA), scha_resourcetype_get(3HA), or scha_resourcetype_close(3HA).

Resource Group Functions

You can access information about a resource group or restart a resource group with these functions.

scha_resourcegroup_open(), scha_resourcegroup_get(), and scha_resourcegroup_close()

These functions access information about a resource group that is managed by the RGM. The scha_resourcegroup_open() function initializes access to a resource group and returns a handle for scha_resourcegroup_get(), which accesses the resource group information. The scha_resourcegroup_close() function invalidates the handle and frees memory that is allocated for scha_resourcegroup_get() return values.

A resource group can change, through cluster reconfiguration or administrative action, after scha_resourcegroup_open() returns the resource group's handle. As a result, the information that scha_resourcegroup_get() obtains through the handle might be inaccurate. In cases of cluster reconfiguration or administrative action on a resource group, the RGM returns the scha_err_seqid error code to scha_resourcegroup_get() to indicate that information about the resource group might have changed. This error message is non-fatal. The function returns successfully. You can choose to ignore the message and accept the returned information. Alternatively, you can close the current handle and open a new handle to access information about the resource group.

One man page describes these three functions. You can access this man page through any of the individual functions scha_resourcegroup_open(3HA), scha_resourcegroup_get(3HA), and scha_resourcegroup_close(3HA).

scha_control()

Requests the restart of a resource group that is under the control of the RGM or its relocation to a different node. This function is described in more detail in the scha_control(3HA) man page.

Cluster Functions

These functions access or return information about a cluster.

scha_cluster_open(), scha_cluster_get(), and scha_cluster_close()

These functions access information about a cluster, such as the cluster name, node names, IDs, states, and resource groups.

A cluster can change, through reconfiguration or administrative action, after scha_cluster_open() returns the cluster's handle. As a result, the information that scha_cluster_get() obtains through the handle might be inaccurate. In cases of reconfiguration or administrative action on a cluster, the RGM returns the scha_err_seqid error code to scha_cluster_get() to indicate that information about the cluster might have changed. This error message is non-fatal. The function returns successfully. You can choose to ignore the message and accept the returned information. Alternatively, you can close the current handle and open a new handle to access information about the cluster.

One man page describes these three functions. You can access this man page through any of the individual functions scha_cluster_open(3HA), scha_cluster_get(3HA), and scha_cluster_close(3HA).

scha_cluster_getlogfacility()

Returns the number of the system log facility that is being used as the cluster log. Uses the returned value with the syslog() Solaris function to record events and status messages to the cluster log. This function is described in more detail in the scha_cluster_getlogfacility(3HA) man page.

scha_cluster_getnodename()

Returns the name of the cluster node on which the function is called. This function is described in more detail in the scha_cluster_getnodename(3HA) man page.

Utility Function

This function converts an error code to an error message.

scha_strerror()

Translates an error code that is returned by one of the scha_ functions to a corresponding error message. Use this function with the logger command to log messages in the Solaris system log (syslog). This function is described in more detail in the scha_strerror(3HA) man page.

RMAPI Callback Methods

Callback methods are the key elements that are provided by the API for implementing a resource type. Callback methods enable the RGM to control resources in the cluster in the event of a change in cluster membership, such as the boot or crash of a node.

Note –

The callback methods are executed by the RGM with superuser or equivalent role permissions because the client programs control HA services in the cluster system. Install and administer these methods with restrictive file ownership and permissions. Specifically, give these methods a privileged owner, such as bin or root, and do not make them writable.

This section describes callback method arguments and exit codes. Callback methods in the following categories are described:

Note –

This section provides brief descriptions of the callback methods, including the point at which the method is run and the expected effect on the resource. However, the rt_callbacks(1HA) man page is the definitive reference for the callback methods.

Arguments That You Can Provide to Callback Methods

The RGM runs callback methods, as follows:

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

The method is the path name of the program that is registered as the Start, Stop, or other callback. The callback methods of a resource type are declared in its registration file.

All callback method arguments are passed as flagged values, as follows:

Use the arguments with access functions to retrieve information about the resource.

The Validate method is called with additional arguments that include the property values of the resource and resource group on which it is called.

The scha_calls(3HA) man page contains more information.

Callback Method Exit Codes

All callback methods have the same exit codes. These exit codes are defined to specify the effect of the method invocation on the resource state. The scha_calls(3HA) man page describes these exit codes in more detail. The two major categories of exit codes are as follows:

The RGM also handles abnormal failures of callback method execution, such as timeouts and core dumps.

Method implementations must output failure information by using syslog() on each node. Output written to stdout or stderr is not guaranteed to be delivered to the user, although it is currently displayed on the console of the local node.

Control and Initialization Callback Methods

The primary control and initialization callback methods start and stop a resource. Other methods execute initialization and termination code on a resource.

Start

The RGM runs this method on a cluster node when the resource group that contains the resource is brought online on that node. This method activates the resource on that node.

A Start method should not exit until the resource that it activates has been started and is available on the local node. Therefore, before exiting, the Start method should poll the resource to determine that it has started. In addition, you should set a sufficiently long timeout value for this method. For example, particular resources, such as database daemons, take more time to start, and thus require that the method have a longer timeout value.

The way in which the RGM responds to failure of the Start method depends on the setting of the Failover_mode property.

The Start_timeout property in the resource type registration (RTR) file sets the timeout value for a resource's Start method.

Stop

The RGM runs this required method on a cluster node when the resource group that contains the resource is brought offline on that node. This method deactivates the resource if it is active.

A Stop method should not exit until the resource that it controls has completely stopped all its activity on the local node and has closed all file descriptors. Otherwise, because the RGM assumes the resource has stopped when, in fact, it is still active, data corruption can result. The safest way to avoid data corruption is to terminate all processes on the local node that is related to the resource.

Before exiting, the Stop method should poll the resource to determine that it has stopped. In addition, you should set a sufficiently long timeout value for this method. For example, particular resources, such as database daemons, take more time to stop, and thus require that the method have a longer timeout value.

The way in which the RGM responds to failure of the Stop method depends on the setting of the Failover_mode property. See Resource Properties.

The Stop_timeout property in the RTR file sets the timeout value for a resource's Stop method.

Init

The RGM runs this optional method to perform a one-time initialization of the resource when the resource becomes managed. The RGM runs this method when its resource group is switched from an unmanaged to a managed state or when the resource is created in a resource group that is already managed. The method is called on nodes that are identified by the Init_nodes resource property.

Fini

The RGM runs this optional method to clean up after the resource when the resource becomes unmanaged. The RGM runs this method when its resource group is switched to an unmanaged state or when the resource is deleted from a managed resource group. The method is called on nodes that are identified by the Init_nodes resource property.

Boot

The RGM runs this optional method, which is similar to Init, to initialize the resource on nodes that join the cluster after the resource group that contains the resource has already been put under the management of the RGM. The RGM runs this method on nodes that are identified by the Init_nodes resource property. The Boot method is called when the node joins or rejoins the cluster as a result of being booted or rebooted.

Note –

Failure of the Init, Fini, or Boot methods causes the syslog() function to generate an error message. However, management of the resource by the RGM is not otherwise affected.

Administrative Support Methods

Administrative actions on resources include setting and changing resource properties. The Validate and Update callback methods enable a resource type implementation to carry out these administrative actions.

Validate

The RGM calls this optional method when a resource is created and when the cluster administrator updates the properties of the resource or its containing resource group. This method is called on the set of cluster nodes that are identified by the Init_nodes property of the resource's type. Validate is called before the creation or the update is applied. A failure exit code from the method on any node causes the creation or the update to be canceled.

Validate is called only when resource or resource group properties are changed by the cluster administrator, not when the RGM sets properties, or when a monitor sets the Status and Status_msg resource properties.

Update

The RGM runs this optional method to notify a running resource that properties have been changed. The RGM runs Update after an administrative action succeeds in setting properties of a resource or its group. This method is called on nodes where the resource is online. The method uses the API access functions to read property values that might affect an active resource and to adjust the running resource accordingly.

Note –

Failure of the Update method causes the syslog() function to generate an error message. However, management of the resource by the RGM is not otherwise affected.

Net-Relative Callback Methods

Services that use network address resources might require that start or stop steps be carried out in a particular order relative to the network address configuration. The following optional callback methods, Prenet_start and Postnet_stop, enable a resource type implementation to carry out special startup and shutdown actions before and after a related network address is configured or unconfigured.

Prenet_start

This optional method is called to carry out special startup actions before network addresses in the same resource group are configured.

Postnet_stop

This optional method is called to carry out special shutdown actions after network addresses in the same resource group are configured down.

Monitor Control Callback Methods

A resource type implementation optionally can include a program to monitor the performance of a resource, report on its status, or take action when a resource fails. The Monitor_start, Monitor_stop, and Monitor_check methods support the implementation of a resource monitor in a resource type implementation.

Monitor_start

This optional method is called to start a monitor for the resource after the resource is started.

Monitor_stop

This optional method is called to stop a resource's monitor before the resource is stopped.

Monitor_check

This optional method is called to assess the reliability of a node before a resource group is relocated to that node. You must implement the Monitor_check method so that it does not conflict with the concurrent running of another method.