rt_callbacks(1HA) (Sun Cluster Reference Manual for Solaris OS)

Sun Cluster Reference Manual for Solaris OS

rt_callbacks(1HA)

NAME

rt_callbacks – callback interface for management of services as Sun Cluster resources

Synopsis

method-path -R resource -T type -G group [-Z zonename]

 
validate-path [-c |  -u] -R resource -T type -G group
 [-r prop=val] [-x prop=val] [-g prop=val] [-Z zonename]

Description

The callback interface for Sun Cluster resource types defines the interface that the Resource Group Manager (RGM) uses to control services as cluster resources. The implementor of a resource type provides programs or scripts that serve as the callback methods.

method-path: The path to the program that is declared in the resource-type registration file. This program is registered with the clresourcetype command as one of the following callback methods for the resource type: START, STOP, INIT, FINI, BOOT, PRENET_START, POSTNET_STOP, MONITOR_START, MONITOR_STOP, MONITOR_CHECK, or UPDATE. See the clresourcetype(1CL) and rt_reg(4) man pages.
validate-path: The path to the program that is declared as a resource type's VALIDATE method in the resource-type registration file. This program is registered with the clresourcetype command.

The callback methods are passed prescribed options and are expected to take specific actions to control the operation of the service on the cluster.

The resource-type developer declares the paths to the callback method programs in the resource-type registration file. The cluster administrator uses the clresourcetype command to register the resource type in the cluster configuration. The cluster administrator can then use this registered resource type to create resources. These resources are configured in resource groups that the RGM manages.

The RGM responds to events by automatically invoking the callback methods of the resources in the resource groups that the RGM manages. The callback methods are expected to take specific actions on the service that is represented by the resource. Examples of these actions include stopping and starting the service on a cluster node or zone.

The exit status code that is returned from the callback method indicates to the RGM whether the callback method succeeded or failed. The RGM takes action if a method fails, or it reports the failure in the resource state. As a result, the cluster administrator can note the failure and take appropriate action.

Options

The following options are supported:

-c

Specifies that the method is called when the cluster administrator creates the resource to validate the initial settings of all resource and resource-group properties.

The RGM specifies either the -c option or the -u option, but never both options at the same time.

When the cluster administrator creates a resource and the VALIDATE method is called, all system-defined, extension, and resource-group properties are passed to the VALIDATE method. When the cluster administrator updates a resource and the VALIDATE method is called, only the properties that are being updated are passed to the VALIDATE method.

-g prop=val

Specifies the value of a resource-group property that is passed to a VALIDATE method.

prop: The name of a resource-group property.
val: The value that is passed to the method when the cluster administrator creates or updates the resource.

-G group

Specifies the name of the resource group in which the resource is configured.

-r prop=val

Specifies the value of a system-defined resource property that is passed to a VALIDATE method.

prop: The name of a system-defined resource property.
val: The value that is passed to the method when the cluster administrator creates or updates the resource.

-R resource

Specifies the name of the resource for which the method is invoked.

-T type

Specifies the name of the resource type of the resource.

-u

Specifies that the method is called when the cluster administrator updates a property of an existing resource or an existing resource group.

The RGM specifies either the -c option or the -u option, but never both options at the same time.

-x prop=val

Specifies the value of a resource extension property that is passed to a VALIDATE method.

prop: The name of a resource extension property. An extension property is defined by the resource-type implementation. This extension property is declared in the parameters table of the resource-type registration file.
val: The value that is passed to the method when the cluster administrator creates or updates the resource.

-Z zonename

Specifies the name of the non-global zone in which a resource group is configured to run.

If the Global_zone resource-type property is set to TRUE, methods execute in the global zone, even if the resource group that contains the resource runs in a non-global zone. This option provides the name of the non-global zone in which the resource group is configured to run.

The -Z option is not passed whenever either of the following conditions is met:

The Global_zone property is set to FALSE.
The resource group is configured to run in the global zone.

Usage

The callback methods are defined by the RGM mechanism that invokes them. These methods are expected to execute operations on a cluster resource. These methods are also expected to return an exit status that reports whether the method succeeded or failed. The following section describes each callback method.

BOOT

This method is invoked when a node or zone joins or rejoins the cluster when it is booted or rebooted. This method is called on nodes or zones that are specified by the Init_nodes resource-type property. Similar to INIT, this method is intended to initialize the resource on nodes or zones that join the cluster after the resource group that contains the resource has been brought online. This method is invoked on resources that are in managed resource groups but not on resources that are in unmanaged resource groups.

FINI

This method is invoked when the resource group that contains the resource is removed from management by the RGM. This method is called on nodes or zones that are specified by the Init_nodes resource-type property. This method unconfigures the resource and cleans up any persistent settings that are made by the INIT method or the BOOT method.

INIT

This method is invoked when the resource group that contains the resource is put under the management of the RGM. This method is called on nodes or zones that are specified by the Init_nodes resource-type property. This method initializes the resource.

MONITOR_CHECK

This method is called before the resource group that contains the resource is relocated to a new node or zone. This method is called when the fault monitor executes the GIVEOVER option of either the scha_control command or the scha_control() function. See the scha_control(1HA) and the scha_control(3HA) man pages.

This method is called on any node or zone that is a potential new master for the resource group. The MONITOR_CHECK method assesses whether a node or zone is healthy enough to run a resource. The MONITOR_CHECK method must be implemented in such a way that it does not conflict with the running of another method concurrently.

If the MONITOR_CHECK method fails, it vetoes the relocation of the resource group to the node or zone where the callback was invoked.

MONITOR_START

This method is called after the resource is started, on the same node or zone where the resource is started. This method starts a monitor for the resource.

MONITOR_START failure causes the RGM to set the resource state to MONITOR_FAILED.

MONITOR_STOP

This method is called before the resource is stopped, on the same node or zone where the resource is running. This method stops a monitor for the resource. This method is also called when monitoring is disabled by the cluster administrator.

The action that the RGM takes when a MONITOR_STOP method fails depends on the setting of the Failover_mode property for the resource. If Failover_mode is set to HARD, the RGM attempts to forcibly stop the resource by rebooting the node or zone. Otherwise, the RGM sets the resource's state to STOP_FAILED.

POSTNET_STOP

An auxiliary to the STOP method, this method is intended to perform shutdown actions that are needed after the related network address is configured down. This method is called on nodes or zones where the STOP method has been called. This method is invoked after the network addresses in the resource group have been configured down, and after the STOP method for the resource has been called. However, this method is invoked before the network addresses have been unplumbed. The POSTNET_STOP method is called after the STOP method for the resource and after the POSTNET_STOP method of any resource that depends on the resource.

The action that the RGM takes when a POSTNET_STOP method fails depends on the setting of the Failover_mode property for the resource. If Failover_mode is set to HARD, the RGM attempts to forcibly stop the resource by aborting the node or zone. Otherwise, the RGM sets the resource's state to STOP_FAILED.

PRENET_START

An auxiliary to the START method, this method is intended to perform startup actions that are needed before the related network address is configured up. This method is called on nodes or zones where the START method is to be called. This method is invoked after network addresses in the same resource group have been plumbed. However, this method is invoked before the addresses have been configured up and before the START method for the resource is called. The PRENET_START method is called before the START method for the resource and before the PRENET_START method of any resource that depends on the resource.

The action that the RGM takes when a PRENET_START method fails depends on the setting of the Failover_mode property for the resource. If Failover_mode is set to SOFT or HARD, the RGM attempts to relocate the resource group that contains the resource to another node or zone. Otherwise, the RGM sets the resource's state to START_FAILED.

START

This method is invoked on a cluster node or zone when the resource group that contains the resource is brought online on that node or zone. The cluster administrator can toggle the state between on and off by using the clresourcegroup command. The START method activates the resource on a node or zone.

The action that the RGM takes when a START method fails depends on the setting of the Failover_mode property for the resource. If Failover_mode is set to SOFT or HARD, the RGM attempts to relocate the resource's group to another node or zone. Otherwise, the RGM sets the resource's state to START_FAILED.

STOP

This method is invoked on a cluster node or zone when the resource group that contains the resource is brought offline on that node or zone. The cluster administrator can toggle the state between on and off by using the clresourcegroup command. This method deactivates the resource if the resource is active.

The action that the RGM takes when a STOP method fails depends on the setting of the Failover_mode property for the resource. If Failover_mode is set to HARD, the RGM attempts to forcibly stop the resource by rebooting the node or zone. Otherwise, the RGM sets the resource's state to STOP_FAILED.

UPDATE

This method is called to notify a running resource that properties have been changed. The UPDATE method is invoked after the RGM succeeds in setting properties of a resource or its resource group. This method is called on nodes or zones where the resource is online. This method can call the scha_resource_get and scha_resourcegroup_get commands to read property values that can affect an active resource and adjust the running resource accordingly.

VALIDATE

This method is called when a resource is created or when a resource or its containing resource group is updated. VALIDATE is called on the set of cluster nodes or zones that are specified by the Init_nodes property of the resource's type.

The VALIDATE method is called before the creation or update of the resource is applied. If the method fails on a node or zone and a failure exit status code is generated, the creation or update is canceled.

When you implement the VALIDATE method, any message that you write to stdout or stderr is passed back to the user command. This action is useful to explain the reason for a validation failure or to provide instructions to the user regarding the resource.

Environment Variables

The Sun Cluster resource management callback methods are executed with superuser permission by the RGM. The programs that implement the methods are expected to be installed with appropriate execution permissions, and for security, should not be writable.

Environment variables that are set for callback method execution are as follows:

HOME=/
PATH=/usr/bin:/usr/cluster/bin
LD_LIBRARY_PATH=/usr/cluster/lib

SIGNALS

If a callback method invocation exceeds its timeout period, the process is sent a SIGTERM signal. If the SIGTERM signal fails to stop the method execution, the process is sent a SIGKILL signal.

Exit Status

The following exit status codes are returned.

0: The command completed successfully.
nonzero: An error occurred.

The specific value of a failure exit status does not affect the RGM's action on failure. However, the exit status is recorded in the cluster log when the method fails. A resource-type implementation might define different nonzero exit codes to communicate error information to the cluster administrator through the cluster log.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWscdev
Interface Stability	Evolving