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 clears error flags on resource groups.

You can run the scswitch utility from any node in a Sun Cluster configuration. If a device group is offline, you can use scswitch to bring the device group online 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 of 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 or -n)

Enables or disables the specified resources.

take offline (-F)

Takes the specified resource groups or device groups offline on all nodes.

set maintenance mode (-m)

Takes the specified disk device groups offline from the cluster for maintenance. The resulting state survives reboots. If a disk device group is currently being accessed, then this action fails and the specified disk device groups are not taken offline from the cluster. 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.

evacuate or switch all (-S)

Attempts 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. All evacuated groups are not necessarily 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, issues an error message, and exits with a nonzero exit code.

restart (-R)

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

unmanage or manage (-u or -o)

Takes the specified resource-grps to (-u) the unmanaged state or takes the specified unmanaged resource-grps out of (-o) the unmanaged state.

The -o option brings the resource group under Resource Group Manager (RGM) management so that the RGM attempts to bring the resource group online.

set primaries (-z)

Causes 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 that are configured with multiple primaries). This option is also used to take resource groups offline and to bring disk device groups back online after being in maintenance mode.

bring online (-Z)

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

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

-c

Clears 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 (you cannot 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, as a last resort, execute a kill(1) command on the associated processes.

-e or -n

Enables (-e) or disables (-n) the specified resources.

If any resource dependencies exist in the resource group, then the resource cannot be disabled unless all resources that 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

Takes 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 unported 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

Specifies 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

Specifies 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

Specifies 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 or -o

Specifies the "change resource group 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

Specifies 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

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

The following options can be combined with the previous nine options as follows:

-D

Specifies the name of one or more device-groups.

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

You need solaris.cluster.device.admin RBAC authorization to use this command option with -F, -m, and -z (in conjunction with -h). 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.

-f

Specifies the error flag-name.

This option is only legal with the -c option.

The only error flag currently supported is STOP_FAILED.

You need solaris.cluster.resource.admin RBAC authorization to use this command option with -c. 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.

-g

Specifies the name of one or more resource-grps.

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

You need solaris.cluster.resource.admin RBAC authorization to use this command option with -F, -o, -R (in conjunction with -h), -u, -z (in conjunction with -h), or -Z. 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.

-h

Specifies the names of one or more cluster nodes.

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

When used with the -c, -R, or -z 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.

You need solaris.cluster.resource.admin RBAC authorization to use this command option with -c, -R (in conjunction with -g), -S, and -z (in conjunction with -g). In addition, you need solaris.cluster.device.admin RBAC authorization to use this command option with -z (in conjunction with -D). 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.

-j

Specifies the names of one or more resources.

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

You need solaris.cluster.resource.admin RBAC authorization to use this command option with -c, -e, or -n. 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.

-M

Enables (-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 legal only with the -e and -n options.

You need solaris.cluster.resource.admin RBAC authorization to use this command option with -e and -n. 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.

This command blocks until its intended maintenance work is completely finished.

The following exit values are returned:

0

The command completed successfully.

nonzero

An error has occurred. scswitch writes an error message to standard output.

If scswitch exits nonzero with the error message cluster is reconfiguring, the requested operation might have completed successfully, despite the error status. If you doubt the result, 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.

Some operations are not permitted on resource types whose RT_System property is TRUE. Similarly, some operations are not permitted on a resource group (and its resources) whose RG_System property is TRUE. See rg_properties(5) for more information.

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

kill(1), attributes(5), rg_properties(5)

Sun Cluster Data Services Installation Guide

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.