scha_control(1HA) Sun Cluster Commands scha_control(1HA)
NAME
scha_control - request resource and resource group control
SYNOPSIS
scha_control -O optag -G group -R resource [-Z zonename]
DESCRIPTION
The scha_control command requests the restart or relocation of a resource or resource group that is under the control of the Resource Group
Manager (RGM). Use this command in shell script implementations of resource monitors. This command provides the same functionality as the
scha_control(3HA) C function.
The exit code of this command indicates whether the requested action was rejected. If the request is accepted, this command does not return
until the resource group or resource has completed going offline and has come back online. The fault monitor that called scha_control(1HA)
might be stopped as a result of the resource or resource group's going offline. As a result, the fault monitor might never receive the
return status of a successful request.
You need solaris.cluster.resource.admin role-based access control (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 com-
mands.
OPTIONS
The following options are supported:
-G group
The name of the resource group that is to be restarted or relocated or that contains the resource that is to be restarted or relocated.
If the resource group is not online on the node or zone 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 lower-
case letters when you specify optag options.
The following optag values are supported:
CHANGE_STATE_OFFLINE
Requests that the proxy resource that is named by the -R option be brought offline on the local node or zone. A proxy resource is a
Sun Cluster resource that imports the state of a resource from another cluster such as Oracle Cluster Ready Services (CRS), now
known as Oracle clusterware CRS. This change in state reflects, in the context of the Sun Cluster software, the change in state of
the external resource.
When you change the state of a proxy resource with this optag value, methods of the proxy resource are not executed.
If a fault occurs on a "depended-on" resource on a node or zone, and the resource cannot recover, the monitor brings that resource
on that node or zone offline. The monitor brings the resource offline by calling the scha_control command with the
CHANGE_STATE_OFFLINE optag value. The monitor also brings all of the depended-on resource's offline-restart dependents offline by
triggering a restart on them. When the cluster administrator resolves the fault and reenables the depended-on resource, the monitor
brings the depended-on resource's offline-restart dependents back online as well.
CHANGE_STATE_ONLINE
Requests that the proxy resource that is named by the -R option be brought online on the local node or zone. A proxy resource is a
Sun Cluster resource that imports the state of a resource from another cluster such as Oracle Cluster Ready Services (CRS). This
change in state reflects, in the context of the Sun Cluster software, the change in state of the external resource.
When you change the state of a proxy resource with this optag value, methods of the proxy resource are not executed.
CHECK_GIVEOVER
Performs all the same validity checks that would be done for a GIVEOVER of the resource group that is 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 that is named by the -G option, but
does not actually restart the resource group.
GIVEOVER
Requests that the resource group that is named by the -G option be brought offline on the local node or zone, and online again on a
different node or zone of the RGM's choosing. Note that if the resource group is currently online on two or more nodes or zones and
there are no additional available nodes or zones on which to bring the resource group online, it can be taken offline on the local
node or zone without being brought online elsewhere. The request might be rejected depending on the result of various checks. For
example, a node or zone might be rejected as a host because the group was brought offline due to a GIVEOVER request on that node or
zone 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_con-
trol GIVEOVER request on one resource group, more than one resource group might be relocated as a result. The RG_Affinities prop-
erty 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 or zone as the
result of a scha_control command or scha_control() function call from a fault monitor.
You can call the MONITOR_CHECK method on any node or zone that is a potential new master for the resource group. The MONITOR_CHECK
method is intended to assess whether a node or zone is healthy enough to run a resource. The MONITOR_CHECK method must be imple-
mented 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 or zone 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 or
zone. 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. The scha_con-
trol command should be called with this optag value in a situation in which the Start method has determined that the resource can-
not start successfully on another node or zone. 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_DISABLE
Disables the resource that is named by the -R option on the node or zone on which the scha_control command is called.
If a fault occurs on a "depended-on" resource on a node or zone, and the resource cannot recover, the monitor brings that resource
on that node or zone offline. The monitor brings the resource offline by calling the scha_control command with the RESOURCE_DISABLE
optag value. The monitor also brings all of the depended-on resource's offline-restart dependents offline by triggering a restart
on them. When the cluster administrator resolves the fault and reenables the depended-on resource, the monitor brings the
depended-on resource's offline-restart dependents back online as well.
RESOURCE_IS_RESTARTED
Requests that the resource restart counter for the resource that is named by the -R option be incremented on the local node or
zone, 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 incrementing is 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 the scha_control
command is not permitted. Consequently, the scha_control command fails and generates exit status code 13 (SCHA_ERR_RT).
RESOURCE_RESTART
Requests that the resource that is named by the -R option be brought offline and online again on the local node or zone without
stopping any other resources in the resource group. The resource is stopped and started by applying the following sequence of meth-
ods to it on the local node or zone:
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. If the resource's type does not declare both a START and STOP method, the scha_control command fails and gen-
erates exit status 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 or zone, 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 are applied to the resource. Network address resources on which this
resource depends are not restarted and remain online.
If a fault occurs on a "depended-on" resource on a node or zone, and the resource cannot recover, the monitor brings that resource
on that node or zone offline. The monitor brings the resource offline by calling the scha_control command with the RESOURCE_RESTART
optag value. The monitor also brings all of the depended-on resource's offline-restart dependents offline by triggering a restart
on them. When the cluster administrator resolves the fault and reenables the depended-on resource, the monitor brings the
depended-on resource's offline-restart dependents back online as well.
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 or zone. 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 or zones) rather than invoking the scha_control com-
mand 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
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.
The setting of the Failover_mode property of the indicated resource might suppress the requested scha_control action. If Failover_mode
is RESTART_ONLY, all requests except scha_control GIVEOVER and scha_control CHECK_GIVEOVER are permitted. The GIVEOVER and
CHECK_GIVEOVER requests return the SCHA_ERR_CHECKS exit code and the requested giveover action is not executed, producing only a syslog
message.
If the Retry_count and Retry_interval properties are set on the resource, the number of resource restarts is limited to Retry_count
attempts within the Retry_interval. If Failover_mode is LOG_ONLY, any scha_control giveover, restart, or disable request returns the
SCHA_ERR_CHECKS exit code and the requested giveover or restart action is not executed, producing only a syslog message.
-Z zonename
The name of the zone in which a resource group is configured to run.
If the Global_zone 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.
Use the -Z option only for resource types whose Global_zone property is set to TRUE. This option is not needed if the Global_zone prop-
erty is set to FALSE. For more information about the Global_zone property, see the rt_properties(5) man page.
EXIT STATUS
The following exit status codes 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 |
+-----------------------------+-----------------------------+
SEE ALSO
pmfadm(1M), rt_callbacks(1HA), scha_cmds(1HA), scha_resource_get(1HA), scha_calls(3HA), scha_control(3HA), scha_control_zone(3HA),
attributes(5), r_properties(5), rbac(5), rg_properties(5), rt_properties(5)
Sun Cluster 3.2 6 Sep 2006 scha_control(1HA)