Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

### rt_callbacks

- callback interface for management of services as Oracle Solaris 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] [-X prop{nodeid}=val]

## Description

The callback interface for Oracle Solaris 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.

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.

  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.

`-x` prop`=`val

  Specifies the value of a resource extension property for the local node.

  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.

`-X` prop{nodeid}`=`val

  Specifies the value of a resource per-node extension property for a specified node.

  prop

    The name of a resource extension property. An extension property is defined by the resource-type implementation. This extension property is declared as a per-node property in the parameters table of the resource-type registration file.

  node

    An integer node ID. This specifies the node on which the per-node property value is set.

  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 joins or rejoins the cluster when it is booted or rebooted. This method is called on nodes that are specified by the `Init_nodes` resource-type property. Similar to `INIT`, this method is intended to initialize the resource on nodes 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 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 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. 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 that is a potential new master for the resource group. The `MONITOR_CHECK` method assesses 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.

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

`MONITOR_START`

  This method is called after the resource is started, on the same node 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 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. 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 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. 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 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. Otherwise, the RGM sets the resource's state to `START_FAILED`.

`START`

  This method is invoked on a cluster node when the resource group that contains the resource is brought online on that node. 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.

  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. Otherwise, the RGM sets the resource's state to `START_FAILED`.

`STOP`

  This method is invoked on a cluster node when the resource group that contains the resource is brought offline on that node. 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. 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 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 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 and a failure exit status code is generated, the creation or update is canceled.

  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. You can use the `scha_resource_get` and `scha_resourcegroup_get` commands to retrieve the properties of the resource that are not being updated.

  Resource dependency properties are passed in two different `-r` options on the `VALIDATE` command line. One `-r` option lists only the resource names, and represents the dependencies which are applicable on the local node. The other `-r` option includes the entire dependency list with qualifiers such as `{LOCAL_NODE}`. The property names `Resource_dependencies`, `Resource_dependencies_offline_restart`, `Resource_dependencies_restart`, and `Resource_dependencies_weak` provide the dependency names without qualifiers for the local node. The corresponding property names `Resource_dependencies_Q`, `Resource_dependencies_Q_offline_restart`, `Resource_dependencies_Q_restart`, and `Resource_dependencies_Q_weak` provide the same lists of dependencies with qualifiers.

  For example, you set the following:

      # clresource set -p Resource_dependencies=r1@node1,r2@node2,r3{local_node},r4

  On node1, the following arguments are passed to the `VALIDATE` method:

      ... -r Resource_dependencies=r1,r3,r4

      -r Resource_dependencies_Q=r1@node1,r2@node2,r3{local_node},r4 ...

  On node2, the value of the `Resource_dependencies` property will be `r2,r3,r4`, while the value of the `Resource_dependencies_Q` property is the same on all nodes. Similarly, the property names `Resource_dependencies_Q_weak`, `Resource_dependencies_Q_restart`, and `Resource_dependencies_Q_offline_restart` correspond to the dependency properties `Resource_dependencies_weak`, `Resource_dependencies_restart`, and `Resource_dependencies_offline_restart`, respectively.

  If you do not explicitly set the `Network_resources_used` property, its value is derived from the four `Resource_dependencies` properties and contains all network address resources appearing in any of those four properties. The derived value of the `Network_resources_used` property on each node reflects any per-node dependencies and might differ from one node to another.

  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 Oracle Solaris 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 first sent a `SIGTERM` signal. If the `SIGTERM` signal fails to stop the method execution within ten seconds, 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 | `ha-cluster/developer/api`
Interface Stability | Evolving

## See Also

`clresourcegroup`(1CL), `clresourcetype`(1CL), `scha_cmds`(1HA), `scha_control`(1HA), `scha_resource_get`(1HA), `scha_resourcegroup_get`(1HA), `signal`(3C), `stdio`(3C), `scha_calls`(3HA), `scha_control`(3HA), `rt_reg`(4), `attributes`(5)

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |