scswitch(1M)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | EXIT STATUS | ATTRIBUTES | SEE ALSO | NOTES

NAME

scswitch– perform ownership and state change of resource groups and disk device groups in Sun Cluster configurations

SYNOPSIS

scswitch -c -h node[,...] -j resource[,...] -f flag-name
scswitch {-e| -n} [-M] -j resource[,...]
scswitch -F {-g resource-grp[,...]| -D device-group| }
scswitch -m -D device-group[,...]
scswitch -S -h from-node
scswitch -R -h node[,...] -g resource-grp[,...]
scswitch {-u| -o} -g resource-grp[,...]
scswitch -z -g resource-grp[,...] -h node[,...]
scswitch -z -D device-group[,...] -h node
scswitch -Z [-g resource-grp]

DESCRIPTION

The scswitch utility moves resource groups or disk device groups to new primary nodes. It also evacuates all resource groups and disk device groups from a node by moving ownership elsewhere, brings resource groups or disk device groups offline and online, enables or disables resources, switches resource groups to or from an unmanaged state, or to clears error flags on resource groups.

You can run the the scswitch utility from any node in a Sun Cluster configuration. If a device group is offline, it can be brought online by a scswitch utility onto any host in the node list. However, once the device group is online, a switchover to a spare node is not permitted. Only one invocation of scswitch at a time is permitted.

Do not attempt to kill an scswitch operation that is already underway.

There are nine forms fo the scswitch utility, each specified by a different option. See SYNOPSIS and OPTIONS.

change error flag (-c)

Clears the specified error flag-name on one or more resources on the specified nodes.

enable or disable (-e | -n)

Enable or disable the specified resources

set maintenance mode (-m)

Take the specified disk device groups offline from the cluster for maintenance. The resulting state survives reboots. If the disk device group is currently being accessed, then this action fails. Disk device groups are brought back online by using the -z option. Only explicit calls to scswitch can bring a disk device group out of maintenance mode.

manage (-o)

Take the specified unmanaged resource-grps out of the unmanaged state. This option brings the resource group under Resource Group Manager (RGM) management so that the RGM attempts to bring the resource group online.

evacuate or switch all (-S)

Attempt to switch over all resource groups and disk device groups from the specified from-node to a new set of primaries. The system attempts to select new primaries based on configured preferences for each group. It is not necessarily the case that all evacuated groups are remastered by the same primary. If one or more resource groups or disk device groups cannot be evacuated from the specified from-node, the command fails by issuing an error message and exiting with a non-zero exit code

restart (-R)

Take the specified resource groups offline and then back online on the specified primary nodes of the resource groups.

unmanage (-u)

Take the specified resource-grps to the unmanaged state.

set primaries (-z)

Cause the orderly transfer of one or more resource groups or disk device groups from one primary node in a Sun Cluster configuration to another node in the configuration (or to multiple nodes for resource groups configured with multiple primaries). It is also used to take resource groups offline and to bring disk device groups back online after being in maintenance.

bring online (-Z)

Bring the specified resource-grps online on the default list of primaries.

OPTIONS

The nine forms of the scswitch command are specified by the following options:

-c

Clear the -f flag-name on the specified set of resources on the specified nodes. For the current release of Sun Cluster software, the -c option is only implemented for the STOP_FAILED error flag. Clearing the STOP_FAILED error flag places the resource into the offline state on the specified nodes.

If the STOP method fails on a resource and the Failover_mode property of the resource is set to HARD, the RGM halts or reboots the node to force the resource (and all other resources mastered by that node) offline.

If the STOP method fails on a resource and the Failover_mode property is set to SOFT or NONE, the individual resource goes into the STOP_FAILED state and the resource group is placed into the ERROR_STOP_FAILED state. A resource group in the ERROR_STOP_FAILED state on any node cannot be brought online on any node, nor can it be edited (add or delete resources or change resource group properties or resource properties). You must clear the STOP_FAILED state by performing the procedure documented in the Sun Cluster 3.0 Data Services Installation Guide.

Make sure that both the resource and its monitor are stopped on the specified node before you clear the STOP_FAILED flag. If necessary, execute a kill(1) command on the associated processes.

-e|-n

Enable" (-e) or disable (-n) the specified resources.

If any resource dependencies exist in the resource group, then the resource cannot be disabled unless all resources which depend on it have been disabled. Conversely, a resource cannot be enabled until all of the resources on which it depends have been enabled. Once you have enabled a resource, it goes online or offline, depending on whether its resource group is online or offline. A disabled resource is immediately brought offline from all of its current masters and remains offline regardless of the state of its resource group.

-F

Take the specified resource-grps (-g) or device-groups (-D) offline on all nodes.

When the -F option takes a disk device group offline, the associated VxVM disk group or Solstice DiskSuite diskset is deported or released by the primary node. Before a disk device group can be taken offline, all access to its devices must be stopped and all dependent file systems must be unmounted. You must start an offline disk device group by issuing an explicit scswitch call, by accessing a device within the group, or by mounting a file system that depends on the group.

-m

Specify the set maintenance mode form of the scswitch utility.

The -m option takes the specified device-groups offline from the cluster for maintenance. Before a disk device group can be placed in maintenance mode, all access to its devices must be stopped and all dependent file systems must be unmounted. Disk device groups are brought back online by using the -z option.

-R

Specify the restart form of the command. The -R option moves the resource groups offline and then back online on the specified primary nodes. The resource groups must already be mastered by all of the specified nodes.

-S

Specify the evacuate or switch all form of the scswitch utility.

The -S option switches all resource groups and disk device groups off the specified node. If not all groups owned by the given node can be successfully evacuated to a new set of primaries, the command exits with an error. If the primary ownership of a group cannot be changed to one of the other nodes, primary ownership for that group is retained by the original node.

-u|-o

Specify the change RG state form of the scswitch utility.

The -u option takes the specified managed resource-grps to the unmanaged state. As a precondition of the -u option, all resources belonging to the indicated resource groups must first be disabled.

The -o option takes the specified unmanaged resource-grps to the managed state. Once a resource group is in the managed state, the RGM attempts to bring the resource group online.

-z

Specify a change in mastery of a resource group or a disk device group.

When used with the -g option, the -z option brings the specified resource-grps online on the nodes specified by the -h option and takes them offline on all other cluster nodes. If the node list specified with the -h option is the empty set, "", then the -z option takes the resource groups specified by the -g option offline from all of their current masters. If one of the listed resource-grps is not capable of being mastered by node, an error is reported and no resource-grps are switched over. All nodes specified by the -h option must be current members of the cluster and must be potential primaries of all of the resource groups specified by the -g option. The number of nodes specified by the -h option must not exceed the setting of the Maximum_primaries property of any of the resource groups specified by the -g option.

When used with the -D option, the -z option switches one or more specified device-groups to the specified node. Only one primary node name can be specified for a disk device group's switchover. When multiple device-groups are specified, the -D option switches the device-groups in the order specified. If the -z -D operation encounters an error, the operation stops and no further switches are performed.

-Z

Enable all resources of the specified resource-grp and their monitors, move the resource group into the managed state, and bring the resource group online on all the default primaries. When the -g option is not specified, scswitch utility attempts to bring all resource groups online.

The following options can combined with the previous nine options. Refer to the SYNOPSIS section for additional details about which of these options are legal with which forms of the scswitch utility.

-D

Specify the name of one or more device-groups.

This option is only legal with the -z, -F, and -m options.

-f

Use with the -c option to specify the error flag-name.

The only error flag currently supported is STOP_FAILED.

-g

Specify the name of one or more resource-grps.

This option is only legal with the -z, -F, -R, -u, -o, and -Z options.

-h

Specify the names of one or more cluster nodes.

This option is only legal with the -z, -S, -R, and -c options.

When used with the -z, -R, or -c option, the -h option specifies the target server (or list of servers in the case of resource groups configured with multiple primaries).

When used with the -S option, the -h option specifies the original server. A comma-delimited list of nodes can be specified after the -h option for resource-grps or device-groups that are configured with multiple primaries. In this case, if any of the listed primaries cannot master resource-grp or device-group, then the resource group or disk device group is not switched over.

-j

Specify the names of one or more resources.

This option is only legal with the -e, -n, and -c options.

-M

Enable (-e) or disables (-n) monitoring for the specified resources. When you disable a resource, you need not disable monitoring on it, because both the resource and its monitor are kept offline.

This option is only legal with the -e and -n options.

EXAMPLES

---

Example 1 Switching Over a Resource Group




The following command switches over resource-grp-2 to be mastered by node1:

node1# scswitch –z –h node1 –g resource-grp-2

---

---

Example 2 Switching Over a Resource Group Configured to Have Multiple Primaries




The following command switches over resource-grp-3, a resource group configured to have multiple primaries, to be mastered by node1,node2,node3:

node1# scswitch –z –h node1,node2,node3 –g resource-grp-3

---

---

Example 3 Switching Over All Resource Groups and Disk Device Groups




The following command switches over all resource groups and disk device groups from node1 to a new set of primaries:

node1# scswitch –S –h node1

---

---

Example 4 Restarting Some Resource Groups




The following command restarts some resource groups on the specified nodes:

node1# scswitch –R –h node1,node2 –g resource-grp-1,resource-grp-2

---

---

Example 5 Disabling Some Resources




The following command disables some resources:

node1# scswitch –n –j resource-1,resource-2

---

---

Example 6 Enabling a Resource




The following command enables a resource:

node1# scswitch –e –j resource-1

---

---

Example 7 Taking Resource Groups to the Unmanaged State




The following command takes resource groups to the unmanaged state:

node1# scswitch –u –g resource-grp-1,resource-grp-2

---

---

Example 8 Taking Resource Groups to the Offline State




The following command take resource groups to the offline state:

node1# scswitch –o –g resource-grp-1,resource-grp-2

---

---

Example 9 Switching Over a Device Group




The follwoing command switches over device-group-1 to be mastered by node2.

node1# scswitch –z –h node2 –D device-group-1

---

---

Example 10 Putting into Maintenance Mode




The following command puts device-group-1 into maintenance mode:

node1# scswitch –m –D device-group-1

---

EXIT STATUS

This command blocks until its intended work is completely attempted.

The following exit values are returned:

0

Successful completion.

non-zero

An error has occurred. Writes an error message to standard output.

If scswitch exits non-zero with the error message cluster is reconfiguring, it is possible that the requested operation completed successfully, despite the error status. If the result is in doubt, you can execute scswitch again with the same arguments after the reconfiguration is complete.

If you invoke the scswitch utility on multiple resource groups and multiple errors occur, the exit value only reflects one of the errors. To avoid this possibility, invoke scswitch on just one resource group at a time.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcsu
Interface Stability	Evolving

SEE ALSO

kill(1), attributes(5)

Sun Cluster 3.0 Data Services Installation Guide

NOTES

If you take resource groups offline by using the -z or -F options with the -g option, the offline state of the resource group will not survive node reboots. In other words, if a node dies or joins the cluster, the resource group might come online on some node, even if you previously switched it offline. You can avoid this by first disabling the resources of the group, or by setting the Desired_primaries property of the group to zero.

Sun Cluster 3.1  Last Revised 23 Apr 2002

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | EXIT STATUS | ATTRIBUTES | SEE ALSO | NOTES