NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | FILES | ATTRIBUTES | SEE ALSO
cc [flags…]-I/usr/cluster/include file -L/usr/cluster/lib -l scha #include <scha.h>scha_err_t scha_control(const char *tag, const char *rgname, const char *rname);
The scha_control(3HA) function provides an interface to request the restart or relocation of a resource group or resource that is under the control of the Resource Group Manager (RGM) cluster facility. The command is intended to be used in resource monitors.
The tag argument indicates whether the request is to restart or relocate the resource or group. It should be a string value defined by one of the following macros that is defined in <scha_tags.h>:
Request that the resource group named by the rgname argument be brought offline, then online again, without forcing relocation to a different node. The request may ultimately result in relocating the resource group if a resource in the group fails to restart. A resource monitor using this option to restart a resource group can use the NUM_RG_RESTARTS query of scha_resource_get to keep count of recent restart attempts.
Request that the resource named by the rname argument be brought offline and online again on the local node, without stopping any other resources in the resource group. The resource is stopped and restarted by applying the following sequence of methods to it on the local node:
MONITOR_STOP STOP START MONITOR_START |
If the resource's type does not declare a MONITOR_STOP and MONITOR_START method, only the STOP and START methods are invoked to perform the restart.The resource's type must declare a START and STOP method. If the resource's type does not declare both a START and STOP method, scha_control fails with error code 13 (SCHA_ERR_RT).
If a method invocation fails while restarting the resource, the RGM might either set an error state, relocate the resource group, or reboot the node, depending on the setting of the Failover_mode property of the resource. For additional information, see the Failover_mode property in r_properties(5).
A resource monitor using this option to restart a resource can use the NUM_RESOURCE_RESTARTS query of scha_resource_get(3HA) to keep count of recent restart attempts.
The RESOURCE_RESTART function should be used with care by resource types that have PRENET_START and/or POSTNET_STOP methods. Only the MONITOR_STOP, STOP, START, and MONITOR_START methods will be applied to the resource. Network address resources on which this resource implicitly depends will not be restarted and will remain online.
Request that the resource restart counter for the resource named by the rname argument be incremented on the local node, without actually restarting the resource.
A resource monitor that restarts a resource directly without calling scha_control with the RESOURCE_RESTART option, (for example, using pmfadm(1M)), can use this option to notify the RGM that the resource has been restarted. This will be reflected in subsequent scha_resource_get(3HA) NUM_RESOURCE_RESTARTS queries.
If the resource's type fails to declare the Retry_interval standard property, the RESOURCE_IS_RESTARTED option of scha_control is not permitted and scha_control returns error code 13 (SCHA_ERR_RT).
Requests that the resource group named by the rgname argument be brought offline on the local node, and online again on a different node of the RGM's choosing. Note that, if the resource group is currently online on two or more nodes and there are no additional available nodes on which to bring the resource group online, it can be taken offline on the local node without being brought online elsewhere. The request might be rejected depending on the result of various checks. For example, a node might be rejected as a host because the group was brought offline due to an SCHA_GIVEOVER request on that node within the interval specified by the Pingpong_interval property.
The MONITOR_CHECK method is called before the resource group that contains 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.
The MONITOR_CHECK method 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.
Perform all the same validity checks that would be done for an SCHA_RESTART of the resource group named by the rgname argument, but do not actually restart the resource group.
Perform all the same validity checks that would be done for an SCHA_GIVEOVER of the resource group named by the rgname argument, but do not actually relocate the resource group.
The SCHA_CHECK_RESTART and SCHA_CHECK_GIVEOVER options are intended to be used by resource monitors that take direct action upon resources, for example, killing and restarting processes, rather than invoking scha_control() to perform a giveover or restart. If the check fails, the monitor should sleep and restart its probes rather than invoke its failover actions. See ERRORS.
The rgname argument is the name of the resource group that is to be restarted or relocated. If the group is not online on the node where the request is made, the request will be rejected.
The rname argument is the name of a resource in the resource group. Presumably this is the resource whose monitor is making the scha_control(3HA) request. If the named resource is not in the resource group the request will be rejected.
The exit code of the command indicates whether the requested action was rejected. If the request is accepted, the function does not return until the resource group or resource has completed going offline and back online. The fault monitor that called scha_control(3HA) might be stopped as a result of the resource group going offline and so might never receive the return status of a successful request.
The scha_control() function returns the following:
The function succeeded.
The function failed.
Function succeeded.
Request rejected: checks on relocation failed.
See scha_calls(3HA) for a description of other error codes.
Normally, a fault monitor that receives an error code from scha_control() should sleep for awhile and then restart its probes, since some error conditions, for example, failover of a global device service causing disk resources to become temporarily unavailable, will resolve themselves after awhile. Once the error condition has resolved, the resource itself might become healthy again, or if not, then a subsequent scha_control() request might succeed.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE |
ATTRIBUTE VALUE |
---|---|
Availability |
SUNWscdev |
Interface Stability |
Evolving |
rt_callbacks(1HA), scha_control(1HA), scha_calls(3HA), scha_resource_get(3HA), scha_strerror(3HA), attributes(5)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | FILES | ATTRIBUTES | SEE ALSO