| Skip Navigation Links | |
| Exit Print View | |
|
Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 3.3 3/13 |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 3.3 3/13 |
- callback interface for management of services as Oracle Solaris Cluster resources
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]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.
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.
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.
The following options are supported:
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.
Specifies the value of a resource-group property that is passed to a VALIDATE method.
The name of a resource-group property.
The value that is passed to the method when the cluster administrator creates or updates the resource.
Specifies the name of the resource group in which the resource is configured.
Specifies the value of a system-defined resource property that is passed to a VALIDATE method.
The name of a system-defined resource property.
The value that is passed to the method when the cluster administrator creates or updates the resource.
Specifies the name of the resource for which the method is invoked.
Specifies the name of the resource type of the resource.
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.
Specifies the value of a resource extension property for the local node.
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.
The value that is passed to the method when the cluster administrator creates or updates the resource.
Specifies the value of a resource per-node extension property for a specified node.
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.
An integer nodeid. This specifies the node on which the per-node property value is set.
The value that is passed to the method when the cluster administrator creates or updates the resource.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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},r4On 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.
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
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.
The following exit status codes are returned.
The command completed successfully.
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.
See attributes(5) for descriptions of the following attributes:
|
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)
|