vxdisk(1M)

NAME

vxdisk — define and manage Volume Manager disks

SYNOPSIS

vxdisk [-g diskgroup] addregion region_type disk offset length

vxdisk [-g diskgroup] check disk ...

vxdisk clearimport accessname ...

vxdisk [-f ] define accessname [attribute ...]

vxdisk [-f ] init accessname [attribute ...]

vxdisk [-g diskgroup] [-o alldgs] [-qs] list [disk ...]

vxdisk offline accessname ...

vxdisk -a online

vxdisk online accessname ...

vxdisk rm accessname ...

vxdisk [-g diskgroup] rmregion region_type disk offset [length]

vxdisk [-g diskgroup] set disk [attribute ...]

DESCRIPTION

The vxdisk utility performs basic administrative operations on disks. Operations include initializing and replacing disks, as well as taking care of some book-keeping necessary for the disk model presented by the Volume Manager.

accessname refers to the disk access name, while disk represents the disk media name. vxdisk accesses disks based on disk access names, which are system-specific names that relate to disk addresses. Disk access names are in the form c#t#d#, which define a controller number (c#), a SCSI target ID (t#), and a SCSI logical unit number (d#). Disk access names relate directly to device node names in the /dev/dsk and /dev/rdsk directories.

Operations that take an accessname argument (see the SYNOPSIS section) accept only disk access names, as defined in the previous paragraph. Operations that take a disk argument can take disk access names or disk media names (for example, disk01). For such operations, a disk group can be specified with -g to disambiguate disk media names that are used in more than one disk group.

Physical disks in the Volume Manager are presumed to be movable, and are usually identified by a unique disk ID stored on the physical disk, rather than by a disk device node. This allows disks to be moved to different SCSI target IDs or to different controllers without affecting correct operation.

The Volume Manager maintains known disk device address information in a set of disk access records, which are stored in the rootdg disk group configuration. These records are named based on the disk access name. These disk access records are normally used solely to identify which physical disks exist, based on disk IDs stored on the disks themselves. Operations for vxdisk other than init and define require specification of defined disk access records.

Physical disks contain public regions, which are used for allocating subdisks. They can also contain private regions, which are used for storing private Volume Manager information. Private regions are structured regions, and are maintained entirely by the Volume Manager. Private regions contain the following structures:

Disk Header: Each private region contains exactly two copies of a disk header, which defines the unique disk ID, disk geometry information, and disk group association information. Two copies are created so that one copy can be lost (due to I/O failures) without causing use of the disk to be lost. The primary copy of the disk header is stored in block zero of the private region. The alternate copy is stored within the first 256 sectors. If the primary copy is unreadable or unusable, the Volume Manager will search the first 256 sectors of the private region for the alternate copy.
Table of Contents: A linked list of blocks, pointed to by the disk header, that define additional structures in the private and public regions. The table of contents blocks define disk group configuration copy locations, log copy locations, and reserved regions carved from the public region. Each link block in the table of contents is replicated at the beginning and end of the private region. If the primary copy of any one link block is unreadable or unusable, the alternate copy of that link is used.
Configuration Copies: A disk normally contains one disk group configuration copy, according to the number specified when the disk was initialized using the vxdisk init operation (explained later). When a disk is added to a disk group, the disk group's persistent configuration records are written to each copy. For disks that are not associated with a disk group, the space allocated for configuration copies is unused. Each disk group requires at least one usable configuration copy. Preferably there should be at least four copies, allocated between at least two disks. This allows one disk to be lost totally, while still preserving sufficient redundancy for recovering from simple read failures.
Disk Group Log Copies: A disk normally contains one disk group log copy. The number of log copies is set to the same as the number of configuration copies for the disk (as explained in the Configuration copies section above). These logs are written by the kernel when certain types of actions are performed: transaction commits, plex detaches resulting from I/O failures, total dirty region log (DRL) failures, the first write to a volume, and volume close. After a crash or a clean reboot, this log information is used to recover the state of a disk group just prior to the crash or reboot. Each disk group requires at least one usable disk group log copy. As with configuration copies, it is preferable to have at least four log copies, allocated between at least two disks.

For a single disk, the disk header and the table of contents blocks are critical data structures. At least one copy of the disk header, and at least one copy of each table of contents block, must be readable and usable, or else the disk itself is unusable and will have to be reinitialized.

Within disk groups, disk group configuration and log copies are critical data structures. At least one complete configuration copy and log copy must be readable and usable, or the disk group is unusable and will have to be reinitialized from scratch.

All disk group association information is stored in the disk header within private regions. This information consists of a disk group name, disk group unique ID, and a host ID. When the system boots, the Volume Manager scans for disks that are stamped with the system's host ID. Each represented disk group is imported automatically. Disks with a non-matching host ID are not imported automatically, and cannot be used until the host ID is cleared with the clearimport operation.

The behavior of the vxdisk utility depends upon the keyword specified as the first operand.

KEYWORDS

vxdisk addregion

Add a new entry to the table of contents in a disk's private region. The new entry defines a region of disk that is relative to the public region, and that is reserved for a particular use. The offset and length operations indicate the location and extent of the region. Currently, the only region type that can be defined is:

reserve: Mask out a region of disk that should be reserved for non Volume Manager purposes. This could be used, for example, to mask out a boot file system that cannot be used for subdisk allocation, or to mask out a region containing blocks that are used for bad-block or bad-track replacement.

Adding a region will fail if a subdisk or region is already allocated over the requested region.

The addregion functionality is currently unimplemented for any of the existing disk types.

vxdisk check

Determines the usability of the specified disks. A disk is considered usable if the Volume Manager can write and read back at least one of the disk headers that are stored on the disk. If a disk in a disk group is unusable, the Volume Manager detaches it from its disk group, and all subdisks stored on the disk become invalid. The subdisks remain invalid until the unusable disk is replaced or the disk media record is reassigned to a different physical disk.

For shared disks, Volume Manger detaches an unusable disk only if the disk group's detach policy is set to global. If the disk group detach policy is local, the disk is not detached. However, if hosts in the cluster do not indicate that a disk is usable, the disk is detached from the entire cluster. See vxedit(1M) for more information on setting disk group detach policies.

vxdisk clearimport

Clears the host-specific import information stored on the indicated disks, and in the configurations stored on those disks. This command may be necessary in cases where import information stored for a disk group becomes unusable, due to host failures, or due to a disk group being moved from one machine to another.

This operation cannot be applied to disks that are in imported disk groups.

vxdisk define

Define a disk access record, but do not initialize it. In order for the Volume Manager to scan a disk, a disk access record must be defined for it. Thus, if you want to see what is on a new disk or you want to move a disk with a valid disk group from one system to another, you will need to use vxdisk define to make it accessible first. You can use vxdisk list to see what is on the disk, or vxdg import to import a disk group that is on the disk.

Attributes can be specified to define the access characteristics of the disk device. Some attributes that can be set are:

type=disk_type

The disk device access type. See the init operation definition for more details.

The various disk types support additional attributes for the define operation. See the definition for each disk type, in the Disk Types section.

offline

If specified, the disk will be created in the offline state.

Normally, a define operation will fail if the specified disk device is invalid, such as because no such disk currently exists. The -f option can be used to force definition of an unusable disk. This can be useful if, for example, the disk device could be used after a reboot. For example, if you intend to add a new controller and intend to move some existing disks to the new controller, you may need to define the new disk device addresses, even though they will not be usable until you shutdown and reconfigure your disks.

vxdisk init

Initialize regions of a disk used by the Volume Manager. This involves installing a disk header and writing an empty configuration on the disk. The accessname operand identifies the disk. Normally, this command will fail if the disk already contains an apparently valid disk header. The -f option can be used to override this and to force initialization of the disk. A disk that is a member of an imported disk group cannot be initialized.

The vxdisk init operation creates a disk access record for a disk (if one does not already exist), and sets its state to online. Disks can be initialized when the root configuration is disabled, in which case the disk header will be initialized, but the disk will not be added to the permanent list of known disks until the root configuration is enabled.

Any attribute operands override default values assigned for various disk attributes. Some attributes that can be set are:

type=disk_type

The disk device access type, which is a system-specific name identifying a class of strategies for accessing disks and for managing private and public regions. For example, disk types could indicate network disks or a volatile RAM disk that may not require the storage of any private data.

The various disk types support additional attributes for the init operation. See the definition for each disk in the Disk Types section.

offline

The device will be left in the offline state, initially. This is used only if this operation is defining a new disk access record.

vxdisk list

List path type and states along with the detailed information on the specified disks. The state will be listed as enabled or disabled. If no disk arguments are specified, then print an one-line summary for all disk access records known to the system. If disk arguments are specified, then print a full description of the contents of the disk header and of the table of contents for each named disk. If no disk arguments are specified, but a disk group is specified with -g, then list only those disks added to the specified disk group.

If the -s option is specified, then list important information from the disk header. With -s, the output format is the same whether or not accessname arguments are specified. The information printed with -s includes the disk ID, the host ID (if the disk is or was imported), and the disk group ID and disk group name (if the disk is a member of a disk group).

If the -q option is specified, then no header is printed describing output fields. This option has no effect with the long formats generated with -s or with accessname arguments.

When -o alldgs is specified without -s and -g, a one line summary shows all disk to disk group associations. The disk group column shows imported disk groups as normal and shows all other disk groups in parentheses.

vxdisk offline

Declare the disk devices named by the accessname arguments to be in the offline state. This disables checking of the disk in searching for particular disk IDs, or for the set of disks in a particular disk group. This operation cannot be applied to disks that are members of an imported disk group.

Take a disk offline if the disk is not currently accessible, and if accessing the disk has a negative impact on the system. For example, disk drivers on a some operating systems can cause system panics or hangs if an attempt is made to access disks that are not accessible. In other operating systems, attempts to access inaccessible drives may take several seconds or minutes before returning a failure.

vxdisk online

Clear the offline state for a disk device. This re-enables checking of the disk when searching for disk IDs, or for members of a disk group. This can be used for disks that are already in the online state, provided that they are not in imported disk groups. All internal information for an already online state disk is regenerated from the disk's private region.

If -a is specified, re-online all online disks that are not currently in an imported disk group. This can be used to force the Volume Manager to re-scan all disk headers.

vxdisk rm

Remove the specified disk access records, by disk access name.

vxdisk rmregion

Free a region of space that is allocated in the private or public region for a particular use. Space that is freed from the public region becomes usable for subdisk creation. The arguments to rmregion must match the arguments used when adding the region with vxdisk addregion except for the optional length argument which can be excluded for the remove.

The rmregion functionality is currently unimplemented for any of the existing disk types.

vxdisk set

Change some set of attributes for a disk. The attributes are either simple names (used to turn on an on/off attribute), or can be of the form attrname=value, to indicate a value for a particular attribute.

Disk Types

Two disk types are provided with the base VERITAS Volume Manager. Additional types may be added for use with particular operating systems. The default is a simple type.

nopriv Disks

The simplest disk type is nopriv, which defines a disk that has no private region, and that consists only of space for allocating subdisks. Configuration and log copies cannot be stored on such disks, and such disks do not support reserved regions defined with vxdisk addregion. Because nopriv disks are not self identifying, the Volume Manager cannot track the movement of such disks on a SCSI chain or between controllers.

nopriv devices are most useful for defining special devices (such as volatile RAM disks) that you wish to use with the Volume Manager, but that can't store private regions. A RAM disk cannot store a meaningful private region, because data written to a RAM disk may not survive a reboot.

Initializing a nopriv device with vxdisk init creates a disk access record in the rootdg configuration, but does not write to the disk. The disk ID for nopriv devices is stored in the disk access record in the rootdg configuration.

Attributes that can be used with the vxdisk init and define operations for the nopriv device type are:

publen=length or len=length: The usable length of the device. This is required if there is no system-defined procedure for determining the disk length; otherwise, a suitable default will be computed.
puboffset=offset or offset=offset: The offset within the device for the start of the usable region. This defaults to 1. This can be used if it is necessary to skip over some region reserved by the operating system. If an offset is specified, then the default disk length is adjusted accordingly.
volatile: If this attribute is specified, the disk is considered to have volatile contents (that is, the disk contents are not expected to remain consistent across a system reboot). Subdisks and plexes defined on disks with the volatile attribute will inherit that attribute. The vxvol start operation interprets volatile plexes as requiring a complete revive from other plexes in the same volume.

The vxdisk define operation, with the nopriv device type, takes the same attributes as the init operation. In addition, define takes the following attribute:

diskid=newdiskid: This attribute will set the disk ID to the newdiskid value in the disk access record for the nopriv disk.

Simple Disks

The simple type presumes that the public and private regions are stored on the same disk, with the public region following the private region.

Attributes that can be defined with vxdisk define for simple are:

configlen=length: The size to reserve for each copy of the configuration stored on the disk. The default size will be based on the size of the private area and the number of configuration copies requested, and will leave some space free for uses other than the configuration copies.
loglen=length: The size to reserve in the private region for each log region. This size limits the number of kernel-initiated detach operations that can be logged against the disk group. The default is about 15% of the size of the configuration copies. It is advised that the log sizes be kept as 15% of the configuration copy size.
nconfig=count: The number of configuration copies to store on the disk. This defaults to 1. This can be set to 0 to indicate that no configurations will be stored on the disk. The Volume Manager will automatically enable and disable the config copy. It will maintain a level of redundancy in configuration copies that will allow the configuration to be recovered from the loss of multiple disks. See the vxdg nconfig parameter for more information.
nlogs=count: The number of log regions to allocate on the disk. Logs regions are used for storing any plex detaches that happen within the disk group. This number defaults to 1. The Volume Manager will automatically enable and disable the config copy. It will maintain a level of redundancy in configuration copies that will allow the configuration to be recovered from the loss of multiple disks. Refer to the vxdg(1M) nlog parameter for more information.
publen=length or len=length: Specify the length of the public region. If not specified, the length of the public region is computed from available system-specific disk size information. If no such information is available, a public region length must be specified in this command. The default public region length is adjusted to account for the private region, or for any specified public or private region offsets.
privlen=length: Specify the length of the private region. If this is not specified, then a default is chosen. For the simple type, the default size is 1024 blocks.

Auto-Configured Disks

On some systems, the Volume Manager can ask the operating system for a list of known disk device addresses. On such systems, some device addresses will be auto-configured into the rootdg disk group when vxconfigd is started. Auto-configured disks will always be of type simple, with default attributes.

Auto-configured devices can be removed, if necessary, using vxdisk rm. When removed, explicitly defined devices can be defined to override any auto-configured devices. When the system reboots, no auto-configured disk devices will be added to the rootdg disk group that would share a disk with an explicitly configured disk device.

Auto-configured devices can be disabled and reenabled using the offline and online operations. However, the offline state is not stored persistently. If you need to persistently offline a device at a particular address, you will need to convert the address to use an explicit device record. To do this, remove the auto-configured device, and use vxdisk define to create an explicitly configured device.

EXAMPLES

This example sets the powerfail timeout on the disk01.

vxdisk set disk01 pfto=seconds 

The set functionality is currently unimplemented for any of the existing disk types.