voldisk(8) System Manager's Manual voldisk(8)
NAME
voldisk - Defines and manages Logical Storage Manager disks
SYNOPSIS
/sbin/voldisk [-f] init accessname [attribute...]
/sbin/voldisk [-f] define accessname [attribute...]
/sbin/voldisk offline accessname...
/sbin/voldisk online accessname...
/sbin/voldisk [-a] online
/sbin/voldisk rm accessname...
/sbin/voldisk [-g diskgroup] [-qs] list [disk...]
/sbin/voldisk clearimport accessname...
/sbin/voldisk [-g diskgroup] check disk...
/sbin/voldisk [-g diskgroup] set disk [attribute...]
/sbin/voldisk moddb accessname [attribute...]
OPTIONS
The following options are recognized: Forces an operation that would normally fail. Specifies all online disks that are not currently in
an imported disk group. Specifies the disk group for the operation. Suppresses the listing of output field labels. Specifies the listing
of detailed information from the disk header, including the disk ID, host ID, disk group ID and disk group name.
DESCRIPTION
The voldisk utility performs basic administrative operations on disks. Operations include initializing and replacing disks, as well as
taking care of some bookkeeping necessary for the disk model presented by the Logical Storage Manager.
The voldisk operations that take an accessname argument accept only disk access names, which are system-specific names that relate to disk
addresses. On Tru64 UNIX systems, disk access names are usually of the form dsknp, where dsk is the device mnemonic for disk devices, n is
the sequence number of the disk, and p is the partition identifier (in the range a to h). 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/disk directory.
The voldisk 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 distinguish disk media names that are used in more than one disk group.
Physical disks in the Logical Storage 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 without affecting correct
operation.
The Logical Storage Manager maintains known disk device address information in a set of disk access records, which are stored in the rootdg
disk group configuration. The names of these records are 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. All voldisk operations except init and define
require specification of defined disk access records.
Private Region Data Structures
Physical disks contain public regions, which are used for allocating subdisks. They can also contain private regions, which are used for
storing private Logical Storage Manager information. Private regions are structured regions, and are maintained entirely by the Logical
Storage 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 0 of the private region. The alternate copy is stored
within the first 256 sectors. If the primary copy is unreadable or unusable, the Logical Storage 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 ta-
ble of contents blocks define disk group configuration copy locations, log copy locations, and reserved regions carved from the pub-
lic 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 contains 0, 1, or 2 disk group configuration copies, depending on the number specified when the disk was initialized using
the voldisk 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 sim-
ple read failures. Disk group log copies
A disk contains 0, 1, or 2 disk group log copies. 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 Logical Storage 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 can-
not be used until the host ID is cleared with the clearimport operation.
Disk Types
On Tru64 UNIX systems, three disk types are provided with the base Logical Storage Manager: nopriv, simple, and sliced. The default is sim-
ple for a disk access name that specifies a partition (dsknp), and sliced for a disk access name that specifies the entire disk (dskn).
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 nopriv disks, so they are not self-identifying, and the Logical Storage Manager cannot
track their movement on a SCSI chain or between controllers.
The nopriv disk type is mainly used for encapsulation of existing data, or for defining special devices that you wish to use with the Logi-
cal Storage Manager, but that cannot store private regions (for example, RAM disks).
Initializing a nopriv device with voldisk 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.
The disk label fstype tag for a nopriv partition is LSMnopriv.
Note
Do not use the type=nopriv attribute to initialize a new disk with no configuration database. Instead, use the nconfig=0 attribute setting.
A simple disk has both a public and a private region, which are stored on a single disk partition, with the public region following the
private region.
The disk label fstype tag for a simple partition is LSMsimp.
A sliced disk has both a public and a private region, which are stored on different disk partitions.
The disk label for a sliced disk has the fstype field set to LSMpubl for the partition with the public region and LSMpriv for the partition
with the private region.
Autoconfigured Disks
On Tru64 UNIX systems, the Logical Storage Manager can get a list of known disk device addresses from the operating system and automati-
cally configure some device addresses into the rootdg disk group when vold is started. Autoconfigured disks are always configured as type
sliced, with default attributes.
Autoconfigured devices can be removed, if necessary, using voldisk rm. Then, explicitly-defined devices can be defined to override any
autoconfigured devices. When the system reboots, no autoconfigured disk devices will be added to the rootdg disk group that would share a
disk with an explicitly configured disk device.
Autoconfigured devices can be disabled and reenabled using the offline and online operations. However, the offline state is not stored per-
sistently. 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 autoconfigured device, and use voldisk define to create an explicitly-configured device.
KEYWORDS AND ATTRIBUTES
The behavior of the voldisk utility depends upon the keyword specified as the first operand. Any attribute operands override default values
assigned for various disk attributes. Supported keywords and attributes are: Initializes regions of a disk used by the Logical Storage Man-
ager. This involves installing a disk header and writing an empty configuration on the disk. The accessname operand identifies the disk.
Normally, this command fails 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 voldisk init operation creates a disk access record for a disk (if one does not already exist), and sets its state to online. If
the root configuration is disabled when a disk is initialized, the disk header is initialized, but the disk is not added to the per-
manent list of known disks until the root configuration is enabled.
Attributes that can be used with voldisk init are: Specifies the disk device access type, which is a system-specific name identify-
ing a class of strategies for accessing disks and for managing private and public regions. For Tru64 UNIX, the valid disk_type names
are: nopriv, simple, and sliced. See the Disk Types section for details. Specifies that the device will be left in the offline
state, initially. This is used only if this operation is defining a new disk access record. For the nopriv device type, this
attribute specifies 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 is computed.
For the simple or sliced device type, this attribute specifies the length of the public region. If this is not specified, the length
of the private region is computed from available disk label information. If no such information is available, a public region length
must be specified. The default public region length is adjusted to account for the private region, or for any specified public or
private region offsets. Specifies the offset from the beginning of the partition containing the public region to the beginning of
the public region. This can be used if it is necessary to skip over some region reserved by the operating system.
This attribute defaults to 0 for the nopriv type and 16 for the sliced type. For the simple type, the default is the first block
past the end of the private region. 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 volume start operation interprets volatile plexes as requiring a complete revive from
other plexes in the same volume.
This attribute can be used only for the nopriv device type. Defines the partition to use for the public partition. The value of num
can be 0-7 (corresponding to partitions a-h). This attribute can be used only for the sliced device type. Defines the partition to
use for the private partition. The value of num can be 0-7 (corresponding to partitions a-h). This attribute can be used only for
the sliced device type.
The following attributes can be used with voldisk init only for the simple or sliced device type: Specifies the offset from the
beginning of the partition containing the private region to the beginning of the private region. This defaults to 16 for a simple
disk on the a or c partition, and to 0 for all other disks. Specifies the length of the private region. If this is not specified, a
default is chosen. For the sliced type, the default is computed from available disk label information. For the simple type, the
default size is 4096 blocks. With the sliced type, if no partition information is available, a private region length must be speci-
fied in this command. Specifies the number of configuration copies to store on the disk. The number of configuration copies will be
the same as the number of log regions. This defaults to 1. The nconfig attribute can be set to 0 to specify that no configuration
copies be stored on the disk. A setting of 1 is reasonable for disk groups that contain three or more disks. This allows either more
configuration records or a smaller reserved private region. Specifies the size of the reserved space for each copy of the configu-
ration stored on the disk. The default size is based on the size of the private area and the number of configuration copies
requested, along with some free space for uses other than the configuration copies. Specifies the size of the reserved space 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. Defines a disk access record without initializing the disk. The Logical Storage Manager cannot scan a disk
unless a disk access record is defined for the disk. Thus, to see what is on a new disk or to move a disk with a valid disk group
from one system to another, you must first use voldisk define to make the disk accessible. Then you can use voldisk list to see what
is on the disk, or voldg import to import a disk group that is on the disk.
Normally, a define operation fails if the specified disk device is invalid (for example, if the disk is currently nonexistent). The
-f option can be used to force the definition of an unusable disk. This can be useful in situations such as preparing the disk
device for use after a reboot. For example, if you intend to add a new controller and move some existing disks to the new con-
troller, you may need to define the new disk device addresses, even though they will not be usable until you shutdown and reconfig-
ure your disks.
Attributes that can be used with voldisk define are: See the init keyword description for details. Specifies that the disk be cre-
ated in the offline state. See the init keyword description for details. See the init keyword description for details. See the
init keyword description for details. Sets the disk ID to the newdiskid value in the disk access record for the nopriv disk. See
the init keyword description for details. See the init keyword description for details. See the init keyword description for
details. Declares 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 placed offline if the disk is not currently accessible, and if accessing the disk has a negative impact on the sys-
tem. 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. Clears the offline state for a disk device. This reenables 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.
The -a can be specified to place on line all online disks that are not currently in an imported disk group. This can be used to
force the volume manager to rescan all disk headers, or to adapt to changes in a disk's partitioning. Removes the specified disk
access records, by disk access name. Lists detailed disk information on the specified disks.
If no disk arguments are specified, a one-line summary is printed for all disk access records known to the system.
If disk arguments are specified, a full description of the contents of the disk header and of the table of contents is printed for
each named disk.
If no disk arguments are specified, but a disk group is specified with -g, voldisk lists only those disks added to the specified
disk group.
If the -s option is specified, important information from the disk header is listed. 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, no header is printed describing output fields. This option has no effect with the long formats gener-
ated with -s or with accessname arguments. 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. Validates the usability of the given disks. A disk is
considered usable if the Logical Storage 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 to be unusable, 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.
Note
Since a nopriv disk does not contain a disk header, a failed nopriv disk may continue to be considered okay and usable after using
this option. Changes 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 not currently implemented for any of the existing disk types. Changes the number of configuration copies
and log copies for the disk device specified by the accessname argument.
The size of the private region is fixed. If there are two copies of the configuration database on a disk, each is limited to half
the space in the private region. By decreasing the number of configuration copies and log copies on a disk, the space available for
the remaining configuration database on that disk will be increased.
The nconfig attribute can be used with voldisk moddb. See the init keyword description for details.
Refer to the Logical Storage Manager manual for more information about when to use this option.
SEE ALSO
volintro(8), vold(8), voldg(8), volume(8)
voldisk(8)