vxdisk(1M)

Synopsis

Description

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 normally of the form c#b# t#d#s #, which define a controller number (c#), a SCSI target ID (t#), a SCSI logical unit number, and a partition number (s#). If the partition number is not specified, s0 is assumed (this represents the whole disk). If any other partition is required, it should be specified (as in c0b0t1d0s4). Special devices, such as internal RAM disks, may use different forms for disk access names. Disk access names relate directly to device node names in the /dev/dsk and /dev/rdsk directories.

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 (e.g., 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.

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. Supported operations are:

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, a volatile RAM disk that may not require the storage of any private data, or a hard disk without separate partitions. If the disk access name is of the form c# t#d# s2 or c#t #d#, the disk type defaults to sliced; otherwise, the disk type defaults to simple.

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 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 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.

A disk should be offlined 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 few 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, then 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, or to adapt to changes in a disk's partitioning.

vxdisk rm

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

vxdisk list

List detailed disk information on the specified disks. If no disk arguments are specified, then print a 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.

vxdisk clearimport

Clear 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 check

Validate the usability of the given 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 found not to be usable, then it is detached from its disk group and all subdisks stored on the disk become invalid until the physical disk is replaced or the disk media record is reassigned to a different physical disk.

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 partition, 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 rmregion

Free a region of space that is allocated in the private or public partition for a particular use. Space that is freed from the public partition 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.

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

Disk types

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 (i.e., 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.

Sliced and simple disks

Two disk types are provided that support disk private regions: simple and sliced. The simple type presumes that the public and private regions are stored on the same disk partition, with the public region following the private region. The sliced type presumes that the public and private regions are stored on different disk partitions.

For the sliced type, if the disk access name ends in s0, then the the public and private regions default to disk partitions with the tags 14 and 15, respectively. If the disk access name ends in s followed by some octal digit other than 0 or 1, the public region defaults to the named partition, and the private region defaults to the immediately following partition. For example, with an access name of c0b0t1d0s4, the public region defaults to partition e and the private region defaults to partition f. For an accessname of c0b0t1d0s1, the public region defaults to partition 1 and the private region defaults to partition 1.

Attributes that can be defined with vxdisk-define for simple or sliced types are:

pubslice=number or slice=number

Define the partition number to use for the public partition. This can be used only with the sliced type.

privslice=number

Define the partition number to use for the private partition. This can be used only with the sliced type.

privoffset=offset

Specify the offset from the beginning of the partition containing the private region to the beginning of the private region. This defaults to zero for both simple and sliced types.

---

NOTE:It is strongly advised that this option never be used unless absolutely necessary. Most information for disks can be determined from the disk header stored at the beginning of the private region. The private region offset cannot be determined from the disk. As a result, specifying a private region offset adds an undesirable dependence between a disk access record and a specific physical disk.

---

In addition to the above attributes, vxdisk-init takes the following attributes:

publen=length or len=length

Specify the length of the public region. If this is not specified, then the length of the private region is computed from available partition table 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.

puboffset=offset or offset=offset

Specify the offset from the beginning of the partition containing the public region to the beginning of the public region. For the sliced type, this defaults to one. For the simple type, this defaults to the first block past the end of the private region.

privlen=length

Specify the length of the private region. If this is not specified, then a default is chosen. For the sliced type, the default is computed from available partition table information. For the simple type, the default size is 1024 blocks. With the sliced type, if no partition information is available, a private region length must be specified in this command.

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. Refer to the vxdg(1M) nconfig parameter for more information.

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.

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.

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.

Auto-configured disks

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.

References