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

Sun Cluster Reference Manual for Solaris OS

scha_control(1HA)

NAME

scha_control– request resource group control

SYNOPSIS

scha_control

-O

optag

-G

group

-R

resource

DESCRIPTION

The scha_control command requests the restart or relocation of a resource group that is under the control of the Resource Group Manager (RGM) cluster facility. This command is intended to be used in shell script implementations of resource monitors. It provides the same functionality as the scha_control(3HA) C function.

The exit code of the command indicates whether the requested action was rejected. If the request is accepted, the command does not return until the resource group or resource has completed going offline and back online. The fault monitor that called scha_control(1HA) might be stopped as a result of the group going offline and so might never receive the return status of a successful request.

You need solaris.cluster.resource.admin RBAC authorization to use this command. See rbac(5).

You must also be able to assume a role to which the Sun Cluster Commands rights profile has been assigned to use this command. Authorized users can issue privileged Sun Cluster commands on the command line from the pfsh(1), pfcsh(1), or pfksh(1) profile shell. A profile shell is a special kind of shell that enables you to access privileged Sun Cluster commands that are assigned to the Sun Cluster Commands rights profile. A profile shell is launched when you run su(1M) to assume a role. You can also use pfexec(1) to issue privileged Sun Cluster commands.

OPTIONS

The following options are supported:

-G group

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 is rejected.

-O optag

Requests optag options.

Note –

optag options, such as CHECK_GIVEOVER and CHECK_RESTART, are not case sensitive. You can use any combination of uppercase and lowercase letters when you specify optag options.

The following optag values are supported:

CHECK_GIVEOVER

Performs all the same validity checks that would be done for a GIVEOVER of the resource group named by the -G option, but does not actually relocate the resource group.

CHECK_RESTART

Performs all the same validity checks that would be done for a RESTART of the resource group named by the -G option, but does not actually restart the resource group.

GIVEOVER

Requests that the resource group named by the -G option 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 a GIVEOVER request on that node within the interval specified by the PINGPONG_INTERVAL property.

If the cluster administrator configures the RG_Affinities properties of one or more resource groups, and you issue a scha_control GIVEOVER request on one resource group, more than one resource group might be relocated as a result. The RG_Affinities property is described in rg_properties(5).

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.

IGNORE_FAILED_START

Requests that, if the currently executing Prenet_start or Start method fails, the resource group is not to fail over, regardless of the setting of the Failover_mode property.

In other words, this optag value overrides the recovery action that is normally taken for a resource for which the Failover_Mode property is set to SOFT or HARD when that resource fails to start. Normally, the resource group fails over to a different node. Instead, the resource behaves as if Failover_Mode is set to NONE. The resource enters the START_FAILED state, and the resource group ends up in the ONLINE_FAULTED state, if no other errors occur.

This optag value is meaningful only when it is called from a Start or Prenet_start method that subsequently exits with a nonzero status or times out. This optag value is valid only for the current invocation of the Start or Prenet_start method. scha_control should be called with this optag value in a situation in which the Start method has determined that the resource cannot start successfully on another node. If this optag value is called by any other method, the error SCHA_ERR_INVAL is returned. This optag value prevents the “ping pong” failover of the resource group that would otherwise occur.

RESOURCE_IS_RESTARTED

Requests that the resource restart counter for the resource named by the -R option be incremented on the local node, without actually restarting the resource.

A resource monitor that restarts a resource directly without calling the RESOURCE_RESTART option of scha_control (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 NUM_RESOURCE_RESTARTS queries of scha_resource_get(1HA).

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 exit 13 (SCHA_ERR_RT).

RESOURCE_RESTART

Requests that the resource named by the -R option 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, then only the STOP and START methods are invoked to perform the restart. If the resource's type does not declare both a START and STOP method, scha_control fails with exit code 13 (SCHA_ERR_RT).

If a method invocation fails while restarting the resource, the RGM might 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(1HA) to keep count of recent restart attempts.

The RESOURCE_RESTART function should be used with care by resource types that have PRENET_START, POSTNET_STOP, or both 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.

RESTART

Requests that the resource group that is named by the -G option be brought offline, then online again, without forcing relocation to a different node. The request might 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(1HA) to keep count of recent restart attempts.

The CHECK_GIVEOVER and CHECK_RESTART optag values are intended to be used by resource monitors that take direct action upon resources (for example, killing and restarting processes, or rebooting nodes) rather than invoking scha_control to perform a giveover or restart. If the check fails, the monitor should sleep for awhile and restart its probes rather than invoke its restart or failover actions. For more information, see scha_control(3HA).

-R resource

Is the name of a resource in the resource group, presumably the resource whose monitor is making the scha_control(1HA) request. If the named resource is not in the resource group, the request is rejected.

EXIT STATUS

The following exit values are returned:

0

The command completed successfully.

nonzero

An error occurred.

Failure error codes are described in scha_calls(3HA).

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	`SUNWscdev`
Interface Stability	Stable