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

Search Scope:

- This Document
- Entire Library

### 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) 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 Oracle Solaris Cluster Commands rights profile has been assigned to use this command. Authorized users can issue privileged Oracle Solaris 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 Oracle Solaris Cluster commands that are assigned to the Oracle Solaris 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 Oracle Solaris Cluster commands.

## 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 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:

  `CHANGE_STATE_OFFLINE`

    Requests that the proxy resource that is named by the `-R` option be brought offline on the local node. A proxy resource is an Oracle Solaris Cluster resource that imports the state of a resource from another cluster such as Oracle Clusterware. This change in state reflects, in the context of the Oracle Solaris 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, and the resource cannot recover, the monitor brings that resource on that node 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. A proxy resource is an Oracle Solaris Cluster resource that imports the state of a resource from another cluster such as Oracle Clusterware. This change in state reflects, in the context of the Oracle Solaris 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, 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` command or `scha_control()` function call from a fault monitor.

    You can call the `MONITOR_CHECK` method 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. The `scha_control` command 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_DISABLE`

    Disables the resource that is named by the `-R` option on the node on which the `scha_control` command is called.

    If a fault occurs on a “depended-on” resource on a node, and the resource cannot recover, the monitor brings that resource on that node 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, 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 without stopping any other resources in the resource group. The resource is stopped and started by applying the following sequence of methods to it on the local node:

        MONITOR_STOP
        STOP
        START
        MONITOR_START

    If the resource type does not declare a `STOP` and `START` method, the resource is restarted using `POSTNET_STOP` and `PRENET_START` instead:

        MONITOR_STOP
        POSTNET_STOP
        PRENET_START
        MONITOR_START

    If the resource's type does not declare a `MONITOR_STOP` and `MONITOR_START` method, only the `STOP` and `START` methods or the `POSTNET_STOP` and `PRENET_START` methods are invoked to perform the restart.

    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 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, and the resource cannot recover, the monitor brings that resource on that node 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. 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 the `scha_control` command 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` property 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 | `ha-cluster/developer/api`
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)

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