RMAPI Callback Methods

Callback methods are the key elements 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 a node boot or crash.

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

This section describes callback method arguments and exit codes and lists and describes callback methods in the following categories:

• Control and initialization methods

• Administrative support methods

• Net-relative methods

• Monitor control methods

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

Method Arguments

The RGM invokes callback methods as follows:

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, with -R indicating the name of the resource instance, -T indicating the type of the resource, and -G indicating the group into which the resource is configured. Use the arguments with access functions to retrieve information about the resource.

The VALIDATE method is called with additional arguments (the property values of the resource and resource group on which it is called).

See rt_callbacks(1HA) for more information.

Exit Codes

All callback methods have the same exit codes defined to specify the effect of the method invocation on the resource state. The scha_calls(3HA) man page describes all these exit codes. The exit codes are:

• 0 - Method succeeded

• Any nonzero value - Method failed

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

Method implementations must output failure information using syslog(3) on each node. Output written to stdout or stderr is not guaranteed to be delivered to the user (though it currently is 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 - This required method is invoked on a cluster node when the resource group containing 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 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 time-out value for this method. For example, certain 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 (see Table A-2).

  The START_TIMEOUT property in the resource type registration file sets the time-out value for a resource's START method.

• STOP - This required method is invoked on a cluster node when the resource group containing 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 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 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 time-out value for this method. For example, certain resources, such as database daemons, take more time to stop, and thus require that the method have a longer time-out value.

  The way in which the RGM responds to failure of the STOP method depends on the setting of the Failover_mode property (see Table A-2).

  The STOP_TIMEOUT property in the resource type registration file sets the time-out value for a resource's STOP method.

• INIT - This optional method is invoked to perform a one-time initialization of the resource when the resource becomes managed--either when the resource group it is in 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 determined by the Init_nodes resource property.

• FINI - This optional method is invoked to clean up after the resource when the resource becomes unmanaged--either when the resource group it is in is switched to an unmanaged state or when the resource is deleted from a managed resource group. The method is called on nodes determined by the Init_nodes resource property.

• BOOT - This optional method, similar to INIT, is invoked to initialize the resource on nodes that join the cluster after the resource group containing the resource has already been put under the management of the RGM. The method is invoked on nodes determined by the Init_nodes resource property. The BOOT method is called when the node joins or rejoins the cluster as the result of being booted or rebooted.

Failure of the INIT, FINI, or BOOT methods causes the syslog(3) function to generate an error message but does not otherwise affect RGM management of the resource.

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 hook into these administrative actions.

• VALIDATE - This optional method is called when a resource is created and when administrative action updates the properties of the resource or its containing resource group. This method is called on the set of cluster nodes indicated by the Init_nodes property of the resource's type. VALIDATE is called before the creation or update is applied, and a failure exit code from the method on any node causes the creation or update to be canceled.

  VALIDATE is called only when resource or resource group properties are changed through administrative action, not when the RGM sets properties, or when a monitor sets the resource properties Status and Status_msg.

• UPDATE - This optional method is called to notify a running resource that properties have been changed. UPDATE is invoked after an administration 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 adjust the running resource accordingly.

  Failure of the UPDATE method causes the syslog(3) function to generate an error message but does not otherwise affect RGM management of the resource.

Net-Relative Callback Methods

Services that use network address resources might require that start or stop steps be done in a certain order relative to the network address configuration. The following optional callback methods, PRENET_START and POSTNET_STOP, enable a resource type implementation to do special startup and shutdown actions before and after a related network address is configured or unconfigured.

• PRENET_START - This optional method is called to do special startup actions before network addresses in the same resource group are configured.

• POSTNET_STOP - This optional method is called to do 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 on resource failure. 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 the node.