rt_callbacks, the callback interface for Sun Cluster resource types, defines the interface used by the cluster's Resource Group Manager (RGM) facility to control services as cluster resources. This man page describes the callback methods and arguments for the Version 2 API shipped with Sun Cluster 3.x.

The implementor of a resource type provides programs or scripts that serve as the callback methods:

method-path

The path the program that has been declared in the rt_reg(4) registration file, and registered with scrgadm(1M) as one of a resource type's callback methods: START, STOP, INIT, FINI, BOOT, PRENET_START, POSTNET_STOP, MONITOR_START, MONITOR_STOP, MONITOR_CHECK, or UPDATE.

validate-path

The path to the program that has been declared as a resource type's VALIDATE method in the rt_reg(4) registration file, and registered with scrgadm(1m).

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

The paths to the callback method programs are declared in a resource type registration file, see rt_reg(4), by the resource type implementor. The cluster administrator uses scrgadm(1m) to register the resource type into the cluster configuration using the registration file. Also using scrgadm(1m), the registered resource type can then be used to create resources configured in resource groups managed by the RGM.

The RGM responds to events by automatically invoking the callback methods of the resources in the resource groups it manages. The callback methods are expected to take certain actions on the service represented by the resource, such as stopping or starting the service on a cluster node.

The exit value returned from the callback method indicates to the RGM whether the callback method succeeded or failed. The RGM either takes additional action in the event of a method failure, or records the failure in the resource state to indicate the need for administrative action.

The following operands are supported:

-c

Operand for a VALIDATE method invocation. Indicates that the method is being called at the time of resource creation to validate the initial setting of all resource and resource group properties.

A VALIDATE invocation will either be passed a -c or -u flag, but not both.

The -c flag indicates that there will also be -r and -x operands passed giving values for all properties and extension properties in the resource, and -g operands passed giving values for all properties in the resource group.

-g prop=val

The operand provides the value of a resource group property to a VALIDATE method. The prop is the name of a resource group property, and val is the value of the property when the administrator creates the resource, or the value set when the resource group containing the resource is updated.

There might be several -g operands passed in a VALIDATE call.

-G group

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

-r prop=val

The operand provides the value for a system-defined resource property to a VALIDATE method. The prop is the name of a system-defined resource property, and val the value set by the administrator on resource creation or update.

There might be several -r operands passed in a VALIDATE call.

-R resource

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

-T type

The name of the resource type of the resource.

-u

Operand for a VALIDATE method invocation. Indicates that the method is being called at the time of an administrative update of properties of an already existing resource, or update of the properties of the resource group containing the resource.

A VALIDATE invocation will either be passed a -c or -u flag, but not both.

The -u flag indicates that there will also be -r, -x, and -g passed giving values for all resource and resource group properties that were set by the administrative action. Only properties that have had values set in the update operation are passed. In contrast, the -c flag indicates that values for all properties are passed.

-x prop=val

The operand provides the value of a resource extension property to a VALIDATE method. The prop is the name of a resource extension property. An extension property is defined by the resource type implementation and declared in the paramtable of the resource type registration file. The val is the value set by the administrator on resource creation or update.

There might be several -x operands passed in a VALIDATE call.

The callback methods are defined by the cluster RGM mechanism that invokes them. The methods are expected to execute operations on a cluster resource, and return an exit status reporting on the success of the operation. Following is a description of each callback method: how it is used by the RGM, what action it is expected to take, and the effect of a failure exit status.

START

The START method is invoked on a cluster node when the resource group containing the resource is brought online on that node. The administrator can toggle the state between on and off using the scswitch command. The START method activates the resource on a node.

RGM action on START method failure depends on the setting of the Failover_mode property of the resource. If Failover_mode is set to SOFT or HARD, the RGM will attempt to relocate the resource's group to another node, otherwise the RGM sets the resource's state to START_FAILED.

STOP

The STOP method is invoked on a cluster node when the resource group containing the resource is brought offline on that node. The administrator can toggle the state between on and off using the scswitch command. This method deactivates the resource if it is active.

RGM action on STOP method failure depends on the setting of the Failover_mode property of the resource. If Failover_mode is set to HARD, the RGM will attempt to forcibly stop the resource by aborting the node, otherwise the RGM sets the resource's state to STOP_FAILED.

INIT

The INIT method is invoked when the resource group containing the resource is put under the management of the RGM. It is called on nodes determined by the Init_nodes resource type property. The method is intended to do initialization of the resource.

FINI

The FINI method is invoked when the resource group containing the resource is removed from RGM management. It is called on nodes determined by the Init_nodes resource type property. The method is intended to do clean-up activities of the resource.

BOOT

The BOOT method is invoked when a node joins or rejoins the cluster as the result of being booted or rebooted. It is called on nodes determined by the Init_nodes resource type property. Similar to INIT, the method is intended to do initialization of the resource on nodes that join the cluster after the resource group containing the resource has already been brought online.

VALIDATE

The VALIDATE method is called when a resource is created, and also when administrative action updates the properties of the resource or its containing resource group. VALIDATE 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.

When VALIDATE is called as the result of a resource being created, all system-defined, extension, and resource group properties are passed as parameters to VALIDATE. When VALIDATE is called as the result of an update to the resource, only the properties being updated are passed. You can use scha_resource_get and scha_resourcegroup_get to retrieve the properties of the resource not being updated.

If the VALIDATE method is implemented as a script, use logger(1) to write messages to the system log. If the VALIDATE method is implemented as a C program, use syslog(3c) to write messages to the system log.

UPDATE

The UPDATE 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 resource group. It is called on nodes where the resource is online. This method is intended to use the scha_resource_get and scha_resourcegroup_get access methods to read property values that can affect an active resource and adjust the running resource accordingly.

PRENET_START

An auxiliary to the START method, the PRENET_START method is intended to do start-up actions that are needed before the related network address is configured up. It is called on nodes where the START method is to be called. It is invoked after network addresses in the same resource group have been plumbed but before the addresses have been configured up and before the START method for the resource is called. The PRENET_START method is called before both the START method for the resource, and before the PRENET_START method of any other resource that depends on the resource.

PRENET_START failure has the same affect as START failure.

POSTNET_STOP

An auxiliary to the STOP method, the POSTNET_STOP method is intended to do shutdown actions that are needed after the related network address is configured down. It is called on nodes where the STOP method has been called. It 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, but before the network addresses have been unplumbed. The POSTNET_STOP method is called after both the STOP method for the resource and after the POSTNET_STOP method of any other resource that depends on the resource.

POSTNET_STOP failure has the same affect as STOP failure.

MONITOR_START

The MONITOR_START method is called after the resource is started, on the same node where the resource is started. It is intended to start a monitor for the resource. MONITOR_START may be called to restart monitoring that has been suspended.

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

MONITOR_STOP

The MONITOR_STOP method is called before the resource is stopped, on the same node where the resource is running. It is intended to stop a monitor for the resource. MONITOR_STOP may be called to suspend monitoring while the system disrupts global resources used by the resource. It is also called when monitoring is disabled by administrative action.

MONITOR_CHECK

The MONITOR_CHECK method is called before the resource group containing the resource is relocated to a new node as the result of a scha_control(3HA) or scha_control(1HA) request from a fault monitor. It may be called on any node that is a potential new master for the resource group. The MONITOR_CHECK method is intended to assess whether a node 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.

MONITOR_CHECK failure vetoes the relocation of the resource group to the node where the callback was invoked.

0

Successful completion. Communicates to the cluster RGM facility that the method succeeded.

non-0

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 on method failure. A resource type implementation may define different non-0 exit codes to communicate error information to the administrator by way of the cluster log.

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

Environment variables set for callback method execution are as follows:

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

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

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

logger(1), scha_cmds(1HA), scrgadm(1M), syslog(3c), scha_calls(3HA), scha_control(3HA), rt_reg(4), signal(3c), attributes(5)