Skip Navigation Links | |
Exit Print View | |
![]() |
Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 4.0 |
scconf_quorum_dev_netapp_nas(1M)
scconf_quorum_dev_quorum_server(1M)
scconf_transp_jct_etherswitch(1M)
- perform ownership and state change of resource groups and device groups in Oracle Solaris Cluster configurations
scswitch -c -h node[,...] -j resource[,...] -f flag-name
scswitch {-e | -n} [-M] -j resource[,...] [-h node[,...]]
scswitch -F {-g resource-grp[,...] | -D device-group[,...]}
scswitch -m -D device-group[,...]
scswitch -Q [ -g resource-grp[,...]] [-k]
scswitch -R -h node[,...] -g resource-grp[,...]
scswitch -r [-g resource-grp[,...]]
scswitch -S -h node[,...] [-K continue_evac]
scswitch -s [-g resource-grp[,...]] [-k]
scswitch {-u | -o} -g resource-grp[,...]
scswitch -Z [-g resource-grp[,...]]
scswitch -z -D device-group[,...] -h node [,...]
scswitch -z [-g resource-grp[,...]] [-h node [,...]]
Note - Oracle Solaris Cluster software includes an object-oriented command set. Although Oracle Solaris Cluster software still supports the original command set, Oracle Solaris Cluster procedural documentation uses only the object-oriented command set. For more information about the object-oriented command set, see the Intro(1CL) man page.
The scswitch command moves resource groups or device groups, also called disk device groups, to new primary nodes. It also provides options for evacuating all resource groups and device groups from a node by moving ownership elsewhere, bringing resource groups or device groups offline and online, enabling or disabling resources, switching resource groups to or from an Unmanaged state, or clearing error flags on resources.
You can run the scswitch command from any node in an Oracle Solaris 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.
For more information about valid uses of this command, see the descriptions of the individual options. For ease of administration, use this command in the global zone.
The following basic options are supported. Options that you can use with some of these basic options are described in “Additional Options.”
Clears the -f flag-name error flag on the specified set of resources on the specified nodes. For the current release of Oracle Solaris Cluster software, the -c option is only implemented for the Stop_failed resource state. Clearing the Stop_failed resource state places the resource into the offline state on the specified nodes.
If you use this option in the global zone, this option can operate on any resource.
If the Stop method fails on a resource and the Failover_mode property of the resource is set to Hard, the Resource Group Manager (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 a value other than Hard, the individual resource goes into the Stop_failed resource 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 resource state by performing the procedure that is documented in the Oracle Solaris Cluster Data Services Planning and Administration Guide.
![]() | Caution - Make sure that both the resource and its monitor are stopped on the specified node before you clear the Stop_failed resource state. Clearing the Stop_failed resource state without fully killing the resource and its monitor can lead to more than one instance of the resource executing on the cluster simultaneously. If you are using shared storage, this situation can cause data corruption. If necessary, as a last resort, execute a kill(1) command on the associated processes. |
Enables the specified resources.
If you use this option in the global zone, this option can operate on any resource.
Once you have enabled a resource, it goes online or offline depending on whether its resource group is online or offline.
You can specify the -h option with the -e option to enable a resource on only a specified subset of nodes. If you omit the -h option, the specified resources are enabled on all nodes.
Takes offline the specified resource groups (-g) or device groups (-D) on all nodes.
When you specify the -F option with the -D option, you can run the -F option only from the global zone.
When the -F option takes a device group offline, the associated Solaris Volume Manager disk set is deported or released by the primary node. Before a device group can be taken offline, all access to its devices must be stopped, and all dependent file systems must be unmounted. You can start an offline 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.
Takes the specified device groups offline from the cluster for maintenance. The resulting state survives reboots.
You can use this option only in the global zone.
Before a device group can be placed in maintenance mode, all access to its devices must be stopped, and all dependent file systems must be unmounted. If a device group is currently being accessed, the action fails and the specified device groups are not taken offline from the cluster.
Device groups are brought back online by using the -z option. Only explicit calls to the scswitch command can bring a device group out of maintenance mode.
Disables the specified resources.
If you use this option in the global zone, this option can operate on any resource.
A disabled resource that is online on its current masters is immediately brought offline from its current masters. The disabled resource remains offline regardless of the state of its resource group.
You can specify the -h option with the -e option to disable a resource on only a specified subset of nodess. If you omit the -h option, the specified resources are disabled on all nodes.
Takes the specified unmanaged resource groups out of the unmanaged state.
Once a resource group is in the managed state, the RGM attempts to bring the resource group online.
Brings the specified resource groups to a quiescent state.
If you omit the -g option, the -Q option applies to all resource groups.
This option stops the specified resource groups from continuously switching from one node to another in the event of the failure of a Start or Stop method. This form of the scswitch command does not exit until the resource groups have reached a quiescent state in which they are no longer stopping or starting on any node.
If a Monitor_stop, Stop, Postnet_stop, Start, or Prenet_start method fails on any resource in a group while the scswitch -Q command is executing, the resource behaves as if its Failover_mode property was set to None, regardless of its actual setting. Upon failure of one of these methods, the resource moves to an error state (either the Start_failed or Stop_failed resource state) rather than initiating a failover or a reboot of the node.
When the scswitch -Q command exits, the specified resource groups might be online or offline or in the ONLINE_FAULTED or ERROR_STOPPED_FAILED state. You can determine their current state by executing the clresourcegroup status command.
If a node dies during execution of the scswitch -Q command, execution might be interrupted, leaving the resource groups in a non-quiescent state. If execution is interrupted, scswitch -Q returns a nonzero exit code and writes an error message to the standard error. In this case, you can reissue the scswitch -Q command.
You can specify the -k option with the -Q option to hasten the quiescing of the resource groups. If you specify the -k option, it immediately kills all methods that are running on behalf of resources in the affected resource groups. If you do not specify the -k option, methods are allowed to continue running until they exit or exceed their configured timeout.
Takes the specified resource groups offline and then back online on the specified primary nodes.
The specified node must be a current primary node of the resource group.
Resumes the automatic recovery actions on the specified resource group, which were previously suspended by the -s option.
If you omit the -g option, the -r option applies to all resource groups.
A suspended resource group is not automatically restarted or failed over until you explicitly issue the command that resumes automatic recovery. Whether online or offline, suspended data services remain in their current state. You can still manually switch the resource group to a different state on specified nodes. You can also still enable or disable individual resources in the resource group.
For information about how to suspend automatic recovery actions on resource groups, see the description of the -s option.
Switches all resource groups and device groups off the specified node.
When executed in a global zone, this option can evacuate any specified node in the cluster.
The system attempts to select new primaries based on configured preferences for each group. All evacuated groups are not necessarily re-mastered by the same primary. If all groups that are mastered by the specified node cannot be successfully evacuated from the specified node, the command exits with an error.
Resource groups are first taken offline before they are relocated to new primary nodes. An evacuated resource group might remain offline if the system cannot start it on a new primary node.
If the primary ownership of a device group cannot be changed to one of the other nodes, primary ownership for that device group is retained by the original node.
Suspends the automatic recovery actions on and quiesces the specified resource group.
If you omit the -g option, the -s option applies to all resource groups.
A suspended resource group is not automatically started, restarted, or failed over until you explicitly resume monitoring of the resource group with this option. While monitoring of the resource group remains suspended, data services remain online. You can still manually switch the resource group online or offline on specified nodes. You can also still enable or disable individual resources in the resource group.
You might need to suspend the automatic recovery of a resource group to investigate and fix a problem in the cluster. Or, you might need to perform maintenance on resource group services.
You can also specify the -k option to immediately kill all methods that are running on behalf of resources in the affected resource groups. By using the -k option, you can speed the quiescing of the resource groups. If you do not specify the -k option, methods are allowed to continue running until they exit or exceed their configured timeout.
For information about how to resume automatic recovery actions on resource groups, see the description of the -r option.
Puts the specified managed resource groups into the unmanaged state.
As a precondition of the -u option, all resources that belong to the indicated resource groups must first be disabled.
This option does the following:
Enables all resources of the specified resource groups
Moves those resource groups into the managed state
Brings those resource groups online on all the default primaries
If you omit the -g option, the -Z option applies to all resource groups.
When the -g option is not specified, the scswitch command attempts to bring all resource groups online, except resource groups that are suspended.
Requests a change in mastery of the specified resource group or device group.
If you omit the -g option, the -z option applies to all resource groups.
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 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.
When used with only the -g option, the -z option brings the specified resource groups, which must already be managed, online on their most preferred nodes . This form of scswitch does not bring a resource group online in violation of its strong RG_affinities, and it writes a warning message if the affinities of a resource group cannot be satisfied on any node. This option does not enable any resources, enable monitoring on any resources, or take any resource groups out of the unmanaged state, as the -Z option does.
When used with the -g and -h options, the -z option brings the specified resource groups online on the nodes that are specified by the -h option, and it takes them offline on all other cluster nodes . If the node list that is specified with the -h option is empty (-h ""), the -z option takes the resource groups that are specified by the -g option offline from all of their current masters. All nodes that are specified by the -h option must be current members of the cluster and must be potential primaries of all of the resource groups that are specified by the -g option. The number of nodes that are specified by the -h option must not exceed the setting of the Maximum_primaries property of any of the resource groups that are specified by the -g option.
When used alone (scswitch -z). the -z option switches online all managed resource groups that are not suspended in their most preferred nodes.
If you configure the RG_affinities property of one or more resource groups and you issue the scswitch -z -g command (with or without the -h option), additional resource groups other than those that are specified after the -g option might be switched as well. RG_affinities is described in rg_properties(5).
You can combine the following additional options with the previous basic options as follows:
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 role-based access control (RBAC) authorization to use this command option with the -F, -m, or -z option (in conjunction with the -h option). 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, pfcsh, or pfksh 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 to assume a role. You can also use pfexec to issue privileged Oracle Solaris Cluster commands.
Specifies the error flag-name.
This option is only legal with the -c option.
The only error flag that is currently supported is Stop_failed.
You need solaris.cluster.resource.admin RBAC authorization to use this command option with the -c option. 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, pfcsh, or pfksh 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 to assume a role. You can also use pfexec to issue privileged Oracle Solaris Cluster commands.
Specifies the name of one or more resource groups.
This option is legal only with the -F, -o, -Q, -r, -R, -s, -u, -z, and -Z options.
You need solaris.cluster.resource.admin RBAC authorization to use this command option with the following options:
-F option
-o option
-Q option
-R option in conjunction with the -h option
-r option
-s option
-u option
-Z option
-z option in conjunction with the -h option
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, pfcsh, or pfksh 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 to assume a role. You can also use pfexec to issue privileged Oracle Solaris Cluster commands.
Specifies the name of one or more cluster nodes.
This option is only legal with the -c, -e, -n, -R, -S, and -z options.
When used with the -c, -e, -n, -R, or -z options, the -h option accepts a comma-delimited list of nodes.
To specify an empty node list to the -z option, specify two double quotation marks "" as the argument to the -h option.
For resource groups that are configured with multiple primaries, the node names that the -h option lists must all be valid potential primaries of each resource group that the -g option specifies.
If a resource group fails to start successfully on the node that the -h option specifies, the resource group might fail over to a different node. This behavior is determined by the setting of the Failover_mode resource property. See r_properties(5) for more information.
When used with the -S option, the -h option specifies the name of a single node from which to evacuate resource groups and device groups.
You need solaris.cluster.resource.admin RBAC authorization to use this command option with the -c, -R option (in conjunction with the -g option), -S, or -z option (in conjunction with the -g option). In addition, you need solaris.cluster.device.admin RBAC authorization to use this command option with the -z option (in conjunction with the -D option). 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, pfcsh, or pfksh 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 to assume a role. You can also use pfexec to issue privileged Oracle Solaris Cluster commands.
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 the -c, -e, or -n option. 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, pfcsh, or pfksh 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 to assume a role. You can also use pfexec to issue privileged Oracle Solaris Cluster commands.
Specifies the number of seconds to keep resource groups from switching back onto a node after that node has been successfully evacuated.
Resource groups cannot fail over or automatically switch over onto the node while that node is being evacuated, and, after evacuation is completed, for the number of seconds that you specify with this option. You can override the -K timer by switching a resource group onto the evacuated node, using the scswitch -z -g -h command before continue_evac seconds have passed. When such a switch is done, the -K timer is immediately considered to have expired. However, scswitch -z -g or -Z commands without the -h flag will continue to respect the -K timer and will avoid switching any resource groups onto the evacuated node.
This option is legal only with the -S option. You must specify an integer value between 0 and 65535. If you do not specify a value, 60 seconds is used by default.
You need solaris.cluster.resource.admin RBAC authorization to use this command option. 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, pfcsh, or pfksh 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 to assume a role. You can also use pfexec to issue privileged Oracle Solaris Cluster commands.
Immediately kills Resource Group Manager (RGM) resource methods that are running on behalf of resources in the specified resource groups.
You can use this option with the -Q and -s options. If you do not specify the -k option, methods are allowed to continue running until they exit or they exceed their configured timeout.
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 the -e or -n option. 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, pfcsh, or pfksh 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 to assume a role. You can also use pfexec to issue privileged Oracle Solaris Cluster commands.
Example 1 Switching Over a Resource Group
The following command switches over resource-grp-2 to be mastered by schost-1.
schost-1# scswitch –z –h schost-1 –g resource-grp-2
Example 2 Bringing Online a Managed Resource Group Without Enabling Monitoring or Resources
The following command brings resource-grp-2 online if resource-grp-2 is already managed, but does not enable any resources or enable monitoring on any resources that are currently disabled.
schost-1# scswitch –z –g resource-grp-2
Example 3 Switching Over a Resource Group Configured to Have Multiple Primaries
The following command switches over resource-grp-3, a resource group that is configured to have multiple primaries, to be mastered by schost-1,schost-2,schost-3.
schost-1# scswitch –z –h schost-1,schost-2,schost-3 –g resource-grp-3
Example 4 Moving All Resource Groups and Device Groups Off a Node
The following command switches over all resource groups and device groups from schost-1 to a new set of primaries.
schost-1# scswitch –S –h schost-1
Example 5 Moving All Resource Groups and Device Groups Persistently Off a Node
The following command switches over all resource groups and device groups from schost-1 to a new set of primaries. The command also specifies a 120-second wait before resource groups and device groups are permitted to switch back to schost-1.
The use of the -K option in the following command prevents resource groups from automatically switching back to schost-1 after schost-1 is successfully evacuated. An example of when a resource group might attempt to switch back to schost-1 is if the resource group fails to start on its new master. Another example is if a resource group has strong negative affinities configured with the RG_affinities property.
schost-1# scswitch –S –h schost-1 -K 120
Example 6 Disabling Resources
schost-1# scswitch –n –j resource-1,resource-2
Example 7 Enabling a Resource
schost-1# scswitch –e –j resource-1
Example 8 Taking Resource Groups to the Unmanaged State
schost-1# scswitch –u –g resource-grp-1,resource-grp-2
Example 9 Taking Resource Groups Out of the Unmanaged State
schost-1# scswitch –o –g resource-grp-1,resource-grp-2
Example 10 Switching Over a Device Group
The following command switches over device-group-1 to be mastered by schost-2.
schost-1# scswitch –z –h schost-2 –D device-group-1
Example 11 Putting a Device Group Into Maintenance Mode
The following command puts device-group-1 into maintenance mode.
schost-1# scswitch –m –D device-group-1
Example 12 Quiescing Resource Groups
The following command brings resource groups RG1 and RG2 to a quiescent state.
schost-1# scswitch –Q -g RG1,RG2
Example 13 Clearing a Start_failed Resource State by Switching Over a Resource Group
The Start_failed resource state indicates that a Start or Prenet_start method failed or timed out on a resource, but its resource group came online anyway. The resource group comes online even though the resource has been placed in a faulted state and might not be providing service. This state can occur if the resource's Failover_mode property is set to None or to another value that prevents the failover of the resource group.
Unlike the Stop_failed resource state, the Start_failed resource state does not prevent you or the Oracle Solaris Cluster software from performing actions on the resource group. You do not need to issue the scswitch -c command to clear a Start_failed resource state. You only need to execute a command that restarts the resource.
The following command clears a Start_failed resource state that has occurred on a resource in the resource-grp-2 resource group. The command clears this condition by switching the resource group to the schost-2 node.
schost-1# scswitch –z –h schost-2 –g resource-grp-2
Example 14 Clearing a Start_failed Resource State by Restarting a Resource Group
The following command clears a Start_failed resource state that has occurred on a resource in the resource-grp-2 resource group. The command clears this condition by restarting the resource group on the schost-1 node.
For more information about the Start_failed resource state, see the r_properties(5) man page.
schost-1# scswitch –R –h schost-1 –g resource-grp-2
Example 15 Clearing a Start_failed Resource State by Disabling and Enabling a Resource
The following command clears a Start_failed resource state that has occurred on the resource resource-1 by disabling and then re-enabling the resource.
For more information about the Start_failed resource state, see the r_properties(5) man page.
schost-1# scswitch –n –j resource-1 schost-1# scswitch –e –j resource-1
This command blocks until requested actions are completely finished or an error occurs.
The following exit values are returned:
The command completed successfully.
An error has occurred. scswitch writes an error message to the standard error.
If the scswitch command exits with a nonzero exit status and the error message “cluster is reconfiguring” is displayed, the requested operation might have completed successfully, despite the error. If you doubt the result, you can execute the scswitch command again with the same arguments after the reconfiguration is complete.
If the scswitch command exits with a nonzero exit status and the error message “Resource group failed to start on chosen node and may fail over to other node(s)” is displayed, the resource group continues to reconfigure for some time after the scswitch command exits. Additional scswitch or clresourcegroup operations on that resource group fail until the resource group has reached a terminal state such as the Online, Online_faulted, or Offline state on all nodes.
If you invoke the scswitch command on multiple resources or resource groups and multiple errors occur, the exit value might only reflect one of the errors. To avoid this possibility, invoke the scswitch command on just one resource or resource group at a time.
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), pfcsh(1), pfexec(1), pfksh(1), pfsh(1), Intro(1CL), cldevicegroup(1CL), clresourcegroup(1CL), su(1M), attributes(5), rbac(5), r_properties(5), rg_properties(5)
Oracle Solaris Cluster Data Services Planning and Administration Guide
If you take a resource group offline by using the -z or -F option with the -g option, the Offline state of the resource group does not survive node reboots. If a node dies or joins the cluster, or if other resource groups are switching over, the resource group might come online. The resource group comes online on a node even if you previously switched the resource group offline. Even if all of the resources are disabled, the resource group comes online.
To prevent the resource group from coming online automatically, use the -s option to suspend the automatic recovery actions of the resource group. To resume automatic recovery actions, use the -r option.