Go to main content

Reference for Oracle Solaris Cluster 4.4

Exit Print View

Updated: August 2018
 
 

clquorum (8CL)

Name

clquorum, clq - manage Oracle Solaris Cluster quorum devices and properties

Synopsis

/usr/cluster/bin/clquorum -V
/usr/cluster/bin/clquorum subcommand -?
/usr/cluster/bin/clquorum subcommand [options] -v devicename[…]
/usr/cluster/bin/clquorum add [-a] [-t type] [-p name=value[,…]] 
devicename[…]
/usr/cluster/bin/clquorum add -i {- | clconfigfile} [-t type] 
[-p name=value[,…]] {+ | devicename[…]}
/usr/cluster/bin/clquorum disable [-t type[,…]] {+ | devicename...}
/usr/cluster/bin/clquorum enable [-t type[,…]] {+ | devicename[…]}
/usr/cluster/bin/clquorum export [-o {- | clconfigfile}] [-t type[,…]] 
{+ | devicename[…]}
/usr/cluster/bin/clquorum list [-t type[,…]] [-n node[,…]] 
[+ | devicename[…]]
/usr/cluster/bin/clquorum remove -F [-t type[,…]] {+ | devicename[…]}
/usr/cluster/bin/clquorum reset 
/usr/cluster/bin/clquorum show [-t type[,…]] [-n node[,…]] 
[+ | devicename[…]]
/usr/cluster/bin/clquorum status [-t type[,…]] [-n node[,…]] 
[+ | devicename[…]]

Description

The clquorum command manages cluster quorum devices and cluster quorum properties. The clq command is the short form of the clquorum command. The clquorum command and the clq command are identical. You can use either form of the command.

The general form of this command is as follows:

clquorum [subcommand] [options] [operands]

You can omit subcommand only if options specifies the –? option or the –V option.

Each option of this command has a long form and a short form. Both forms of each option are provided with the description of the option in the OPTIONS section of this man page.

Quorum devices are necessary to protect the cluster from split-brain and amnesia situations. (For information about split-brain and amnesia situations, see the section on quorum and quorum devices in the Oracle Solaris Cluster Concepts Guide.) Each quorum device must be connected, either by a SCSI cable or through an IP network, to at least two nodes.

A quorum device can be a shared SCSI storage device, a shared NAS storage device (Oracle ZFS Storage Appliance), or a quorum server. If the quorum device stores user data, you do not affect this data if you add or remove such a device as a quorum device. However, if you are using replicated storage devices, the quorum device must be on an unreplicated volume.

Both nodes and quorum devices participate in cluster quorum formation, unless the nodes and quorum devices are in the maintenance state. If a node or a quorum device is in the maintenance state, its vote count is always zero and it does not participate in quorum formation.

You can use the clquorum command to perform the following tasks:

  • Add a quorum device to the Oracle Solaris Cluster configuration

  • Remove a quorum device from the Oracle Solaris Cluster configuration

  • Manage quorum properties

SUBCOMMANDS

The following subcommands are supported:

add

Adds the specified shared device as a quorum device.

You can use this subcommand only in the global zone.

Each quorum device must be connected to at least two nodes in the cluster. The quorum device is added with connection paths in the cluster configuration to every node to which the device is connected. Later, if the connection between the quorum device and the cluster nodes changes, you must update the paths. Update the paths by removing the quorum device and then adding it back to the configuration. This situation could arise if you add more nodes that are connected to the quorum device or if you disconnect the quorum device from one or more nodes. For more information about quorum administration, see Chapter 6, Administering Quorum in Administering an Oracle Solaris Cluster 4.4 Configuration.

Quorum devices have several types. See the –t option in the OPTIONS section for a complete description. The shared_disk type is the default type.

Users other than the root role role require solaris.cluster.modify authorization. See rbac(7).

See also the description of the remove subcommand.

disable

Puts a quorum device or node in the quorum maintenance state.

You can use this subcommand only in the global zone.

In the maintenance state, a shared device or node has a vote count of zero. This shared device or node no longer participates in quorum formation. In addition, for a node that is in the maintenance state, any quorum devices that are connected to the node have their vote counts decremented by one.

This feature is useful when you need to shut down a node or a device for an extended period of time for maintenance. After a node boots back into the cluster, the node removes itself from maintenance mode unless the installmode is set.

You must shut down a node before you can put the node in the maintenance state.

Users other than the root role role require solaris.cluster.modify authorization. See rbac(7).

See also the description of the enable subcommand.

enable

Removes a quorum device or a node from the quorum maintenance state.

You can use this subcommand only in the global zone.

The enable subcommand removes a quorum device or node from maintenance mode. The subcommand resets the configured quorum vote count of a quorum device or node to the default. The shared device or node can then participate in quorum formation.

After resetting a quorum device, the vote count for the quorum device is changed to N-1. In this calculation, N is the number of nodes with nonzero vote counts that are connected to the device. After resetting a node, the vote count is reset to its default. Then the quorum devices that are connected to the node have their vote counts incremented by one.

Unless the install mode setting installmode is enabled, the quorum configuration for each node is automatically enabled at boot time.

Users other than the root role role require solaris.cluster.modify authorization. See rbac(7).

See also the description of the disable subcommand.

export

Exports the configuration information for the cluster quorum.

You can use this subcommand only in the global zone.

If you specify a file by using the –o option, the configuration information is written to that file. If you do not specify a file, the information is written to standard output (stdout ).

The export subcommand does not modify any cluster configuration data.

Users other than the root role role require solaris.cluster.read authorization. See rbac(7).

list

Displays the names of quorum devices that are configured in the cluster.

You can use all forms of this subcommand in the global zone. In a zone cluster, you can use this subcommand only with the –? or –V option or without any option.

If you do not specify options, the list subcommand displays all the quorum devices that are configured in the cluster. If you specify the –t option, the subcommand displays only quorum devices of the specified type. If you specify the –n option, the subcommand displays the names of all quorum devices that are connected to any of the specified nodes.

Users other than the root role role require solaris.cluster.read authorization. See rbac(7).

remove

Removes the specified quorum device or devices from the Oracle Solaris Cluster quorum configuration.

You can use this subcommand only in the global zone.

Use the force option, –F, with this subcommand to remove the last quorum device of a two-node cluster. The remove subcommand will not remove the last quorum device of a two-node cluster if the –F option is not specified.

The remove subcommand does not disconnect and remove the physical device. The subcommand also does not affect the user data on the device, if any data exists. The last quorum device in a two-node cluster cannot be removed, unless the installmode is enabled.

You can remove only a quorum device. You cannot use this subcommand to remove cluster nodes.

Users other than the root role role require solaris.cluster.modify authorization. See rbac(7).

See also the description of the add subcommand.

reset

Resets the entire quorum configuration to the default vote count settings.

You can use this subcommand only in the global zone.

If installmode is enabled, the mode is cleared by resetting. installmode cannot be reset on a two-node cluster unless at least one quorum device has been successfully configured.

Users other than the root role role require solaris.cluster.modify authorization. See rbac(7).

See also the –p option in cluster(8CL) for the description of the installmode property.

show

Displays the properties of quorum devices.

You can use this subcommand only in the global zone.

If you do not specify options, the show subcommand displays the properties of all the quorum devices in the cluster.

If you specify the type by using the –t option, the subcommand displays properties of devices of that type only. See – t in OPTIONS.

If you specify nodes by using the –n option, this subcommand displays the properties of the quorum devices that are connected to any of the specified nodes.

Users other than the root role role require solaris.cluster.read authorization. See rbac(7).

status

Checks and displays the current status and vote counts of quorum devices.

You can use all forms of this subcommand in the global zone. In a zone cluster, you can use this subcommand only with the –? or –V option or without any option.

You can use this subcommand in the global zone to immediately check the status of quorum devices that are connected to the specified node. For quorum devices that are not connected to the node, this subcommand displays the status that was true during the previous cluster reconfiguration.

If you do not specify options, the status subcommand displays information about all the quorum devices in the cluster.

If you specify the type by using the –t option, the subcommand displays information about devices of that type only. See –t in OPTIONS.

If you specify nodes by using the –n option, this subcommand displays the properties of the quorum devices that are connected to any of the specified nodes.

Users other than the root role role require solaris.cluster.read authorization. See rbac(7).

Options

The following options are supported:

–?
-–help

Displays help information. When this option is used, no other processing is performed.

You can specify this option without a subcommand or with a subcommand.

If you specify this option without a subcommand, the list of subcommands of this command is displayed.

If you specify this option with a subcommand, the usage options for the subcommand are displayed.

–a
–-autoconfig

For a two-node cluster that uses shared disks, automatically chooses and configures one quorum device if no quorum devices are configured.

All shared disks in the cluster must be qualified to be a quorum device. The autoconfig subcommand does not check whether an available device is qualified to be a quorum device. The autoconfig subcommand checks only for shared disks.

Users other than the root role role require solaris.cluster.modify authorization. See the rbac(7) man page.

–F

Forces the removal of the specified quorum device.

The force option is available only with the remove subcommand. The force option makes it possible to remove the last quorum device of a two-node cluster, or to remove a failed quorum device. When you use this option with the remove subcommand, the quorum subsystem does not touch the quorum device during the removal process.

–i clconfigfile
-–input=clconfigfile
-–input clconfigfile

Specifies configuration information that is to be used for managing the quorum devices. This information must conform to the format that is defined in the clconfiguration(7CL) man page.

When –i is used with a subcommand along with other command-line options, the arguments of the command-line options overwrite the settings in the configuration file.

–n node-name
-–node=node-name
-–node node-name

Specifies the node name to which the quorum devices are connected. This option is used in the list, status, and show subcommands to limit the information that is displayed to those quorum devices that are connected to the specified nodes.

You can specify either a node name or a node ID for the node-name.

–o {- | clconfigfile}
-–output={- | clconfigfile}
-–output {- | clconfigfile}

Writes quorum-device configuration information to a file or to the standard output (stdout). The format of this configuration information conforms to the format that is described in the clconfiguration(7CL) man page. To specify the standard output, specify - instead of a file name.

–p name=value[,…]
-–property=name=value[,…]
-–property name=value[,…]

Specifies properties of a quorum device that are specific to a device type. You use this option with the add subcommand. See the description of the –t option for a list and a description of these properties.

–t device-type
-–type=device-type
-–typedevice-type

Specifies the quorum device type. When this option is specified, the operands must be of the specified type.

For the add, export, and remove subcommands, the current supported quorum device types are as follows:

  • Shared local disks, specified by shared_disk, which can be SCSI-2, SCSI-3, or software quorum (SCSI disks with fencing disabled)

  • A quorum server process that runs on the Oracle Solaris Cluster Quorum Server machine, specified by quorum_server

The default type is shared_disk.

The add subcommand does not accept –t node as a quorum type.

For the enable, disable, list, show, and status subcommands, you can specify the types node, shared_disk, or quorum_server. These different types of quorum devices have the following properties:

node

No specific properties are set for nodes to participate in quorum formation.

This type is used only with the enable, disable, list, status, and show subcommands. It cannot be used to add a quorum device of type node.

quorum_server

The quorum_server type of quorum device has the following properties:

qshost=quorum-server-host: Specifies the name of the machine where the quorum server runs. This host can be the IP address of the machine or the hostname on the network. If you specify the hostname, the IP address of the machine must be specified in the /etc/hosts file, the /etc/inet/ipnodes file, or both.

port=port: Specifies the port number used by the quorum server to communicate with the cluster nodes.

Before you can add a quorum server, the quorum server software must be installed on the host machine and the quorum server must be started and running. Refer to the Installing and Configuring an Oracle Solaris Cluster 4.4 Environment for details.

shared_disk

Use this type to configure SCSI-2, SCSI-3, or software quorum devices. No specific properties are set for shared_disk quorum devices. The autoconfig subcommand accepts only this quorum device type.

–V
-–version

Displays the version of the command.

Do not specify this option with other subcommands, options, or operands. The subcommands, options, or operands are ignored. The –V option displays only the version of the command. No other operations are performed.

–v
-–verbose

Displays verbose information to standard output (stdout).

Operands

The following operands are supported:

devicename

For the add, export, and remove subcommands only, the operand is the name of a shared disk (SCSI, quorum server, or NAS quorum device). For the add subcommand, if you do not specify a clconfigurationfile by using –i, you must specify at least one quorum device as the operand.

For the disable, enable, list, status, and show subcommands only, the operand can be the name of a node or of a shared disk (SCSI, quorum server, or NAS quorum device).

In every case, the operand type must match the value of the –t option, if you specify that option.

Use the following values as the devicename operand:

  • For nodes, the operand must be the node name or the node ID.

  • For SCSI quorum devices, the operand must be the device identifier or the full DID path name, for example, d1 or /dev/did/rdsk/d1.

  • For quorum server quorum devices, the operand must specify an identifier for the quorum server or servers. This can be the quorum server instance name, and must be unique across all quorum devices.

+

For the disable, enable, list, status, and show subcommands only, specifies all quorum devices configured for the cluster. If you use the –t option, the plus sign (+) operand specifies all devices of that type.

Exit Status

If the command is successful for all specified operands, it returns zero (CL_NOERR). If an error occurs for an operand, the command processes the next operand in the operand list. The returned exit code always reflects the error that occurred first.

The following exit values can be returned:

0 CL_NOERR

No error

The command that you issued completed successfully.

1 CL_ENOMEM

Not enough swap space

A cluster node ran out of swap memory or ran out of other operating system resources.

3 CL_EINVAL

Invalid argument

You typed the command incorrectly, or the syntax of the cluster configuration information that you supplied with the –i option was incorrect.

6 CL_EACCESS

Permission denied

The object that you specified is inaccessible. You might need the root role or authorization to issue the command. See the rbac(7) man page for more information.

18 CL_EINTERNAL

Internal error was encountered

An internal error indicates a software defect or other defect.

35 CL_EIO

I/O error

A physical input/output error has occurred.

36 CL_ENOENT

No such object

The object that you specified cannot be found for one of the following reasons: (1) The object does not exist. (2) A directory in the path to the configuration file that you attempted to create with the –o option does not exist. (3)The configuration file that you attempted to access with the –i option contains errors.

39 CL_EEXIST

Object exists

The device, device group, cluster interconnect component, node, cluster, resource, resource type, resource group, or private string that you specified already exists.

41 CL_ETYPE

Invalid type

The type that you specified with the –t or –p option does not exist.

Examples

Example 1 Adding a SCSI Quorum Device

The following clquorum command configures a SCSI quorum device that is connected to all the cluster nodes.

# clquorum add /dev/did/rdsk/d4s2

When you use the add subcommand, the shared_disk type is the default. To add a shared_disk quorum device, you do not need to specify -t shared_disk.

Example 2 Adding a Quorum Server

The following clquorum command configures a quorum server, qs1:

# clquorum add -t quorum_server -p qshost=10.11.114.81 -p port=9000 qs1
Example 3 Removing a Quorum Device

The following clquorum command removes the d4 quorum device.

# clquorum remove d4

The command that you use to remove a quorum device is the same, whether your device has a type of shared_disk or quorum_server.

Example 4 Putting a Quorum Device into a Maintenance State

The following clquorum command puts a quorum device, qs1 into a maintenance state and verifies that the device is in a maintenance state.

# clquorum disable qs1
# clquorum status qs1

=== Cluster Quorum ===

--- Quorum Votes by Device ---

Device Name       Present      Possible      Status
-----------       -------      --------      ------
qs1                1            1             Offline
Example 5 Resetting the Quorum Votes of a Quorum Device

The following clquorum command resets the configured quorum vote count of a quorum device, d4, to the default.

# clquorum enable d4
Example 6 Displaying the Configured Quorum Devices in the Cluster

The following clquorum commands display the quorum devices in concise format and verbose format.

# clquorum list
d4
pcow1
pcow2
# clquorum list -v
Quorums               Type
-------               ----
d4                    shared_disk
pcow1                 node
pcow2                 node

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
ha-cluster/system/core
Interface Stability
Evolving

See Also

clconfiguration(7CL), Intro(8CL), cluster(8CL)

Notes

The root role can run all forms of this command.

Any user can run this command with the following options:

  • –? option

  • –V option

To run this command with other subcommands, users other than the root role require authorizations. See the following table.

Subcommand
Authorization
add
solaris.cluster.modify
disable
solaris.cluster.modify
enable
solaris.cluster.modify
export
solaris.cluster.read
list
solaris.cluster.read
remove
solaris.cluster.modify
reset
solaris.cluster.modify
show
solaris.cluster.read
status
solaris.cluster.read