voldisk(8)voldisk(8)NAMEvoldisk - 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
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,
you can specify a disk group 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 mov‐
able, 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 opera‐
tion.
The Logical Storage Manager maintains known disk device address infor‐
mation 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 informa‐
tion, and disk group association information. Two copies are
created so that one copy can be lost (due to I/O failures) with‐
out 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 Man‐
ager 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 unus‐
able, 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). The default
number of copies is 1. 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 recov‐
ering from simple 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) fail‐
ures, 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. By
default, the same disks that store one or more configuration
copies also store the same number of log copies.
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 reini‐
tialized.
Within disk groups, disk group configuration and log copies are criti‐
cal 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 cannot be used
until you clear the host ID with the clearimport operation.
Disk Types
On Tru64 UNIX systems, three disk types are provided with the base Log‐
ical Storage Manager: nopriv, simple, and sliced. The default is simple
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 pri‐
vate 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 Logical
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.
Note
Do not use the type=nopriv attribute to initialize a new disk with no
configuration database. Instead, initialize a sliced or simple disk and
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 pri‐
vate region.
A sliced disk has both a public and a private region, which are stored
on different disk partitions.
The disk label fstype tags for the various LSM disk types are: LSMpubl
for the public region of a sliced disk LSMpriv for the private region
of a sliced disk LSMsimp for a simple disk (public and private regions
are contained within the same partition) LSMnoprv for a nopriv disk
(maps to an encapsulated disk or disk partition)
Autoconfigured Disks
On Tru64 UNIX systems, the Logical Storage Manager can get a list of
known disk device addresses from the operating system. Any disks marked
for use by LSM are automatically configured into LSM when vold is
started. Disks that are not configured for LSM use appear as type
sliced, with a status of UNKNOWN.
If LSM disks are not associated with a disk group, you can remove them
from LSM use, if necessary, using voldisk rm. The next invocation of
voldisk list displays those devices as UNKNOWN, the same as if they had
never been in use by LSM. If you reinitialize a disk for LSM use, the
next invocation of voldisk list reflects its changed status as an LSM
disk. Disks are listed as either in use by LSM or unknown, but not
both.
You can disable and reenable LSM disks using the offline and online
operations. However, the offline state is not stored persistently
unless there is an explicit device record in the configuration data‐
base. If you need to persistently offline a device at a particular
address, you must convert the address to use an explicit device record.
To do this, remove the autoconfigured device (with voldisk rm), 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
for use by the Logical Storage Manager. 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 overrides this and
forces initialization of the disk. You cannot initialize a disk
that is a member of an imported disk group.
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 permanent list of known disks until the root con‐
figuration is enabled.
You can apply the following disk attributes with voldisk init:
Specifies the disk device access type, which is a system-spe‐
cific name identifying 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, in 512-byte blocks. 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, in 512-byte blocks. If this is
not specified, the length of the public 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 in blocks from the beginning of the parti‐
tion containing the public region to the beginning of the public
region. Use this attribute if it is necessary to skip over some
region reserved by the operating system. This attribute does
not apply to nopriv disks. For simple disks, use the privoffset
attribute.
This attribute defaults to 0. For sliced disks, an offset of 16
blocks or greater is a reasonable value. If the disk is a hard‐
ware stripe set, you can use a different offset to maintain
stripe alignment. 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 inter‐
prets volatile plexes as requiring a complete resynchronization
from other plexes in the same volume.
This attribute applies only to 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
applies only to 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 applies only
to the sliced device type.
You can apply the following attributes with voldisk init only
for the simple or sliced device types: Specifies the offset in
blocks from the beginning of the partition containing the pri‐
vate region to the beginning of the private region. The default
is 0.
For a simple disk that occupies a partition that begins at block
0 (for example, when you initialize the disk specifying the a or
c partition), you should set the privoffset to 16 blocks. For a
simple disk that occupies a partition that does not begin at
block 0 (for example, when you initialize the disk specifying
the b or d partition), the default of 0 is appropriate.
By default, the private region of a sliced disk is at the end of
the disk (the h partition) and needs no offset. Therefore the
privoffset default of 0 is appropriate. Specifies the length of
the private region in blocks. If this is not specified, the
default of 4096 blocks is used. For a sliced disk, if no parti‐
tion information is available, a private region length must be
specified in this command. Specifies the number of configura‐
tion copies to store on the disk. The number of configuration
copies will be the same as the number of log regions. The
default is 1, but you can set the attribute 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 in blocks of the
reserved space for each copy of the configuration 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 in blocks of the reserved space in the pri‐
vate 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 con‐
figuration 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 Man‐
ager 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 one
or more disks that comprise a valid disk group from one system
to another, you must first use voldisk define to make the disks
accessible. Then you can use voldisk list to see what is on the
disks, or voldg import to import a disk group that is on those
disks.
Normally, a define operation fails if the specified disk device
is invalid (for example, if the disk is currently nonexistent).
The -f option forces 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 controller,
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.
You can define the following disk attributes with voldisk
define: See the init keyword description for details. Specifies
that the disk be created in the offline state. See the init
keyword description for details. See the init keyword descrip‐
tion 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 when searching for
particular disk IDs, or for the set of disks in a particular
disk group. You cannot place disks offline if they 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 could have a negative
impact on the system. For example, disk drivers on a few operat‐
ing 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 off‐
line state for a disk device. This reenables checking of the
disk when searching for disk IDs, or for members of a disk
group. Use this attribute for disks that are already in the
online state, provided that they are not in imported disk
groups. All internal information for a disk that is already in
the online state is regenerated from the disk's private region.
The -a places on line all online disks that are not currently in
an imported disk group. Use this option to force the volume man‐
ager 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 con‐
tents 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 speci‐
fied with -g, voldisk lists only those disks belonging to the
specified disk group.
If the -s option is specified, information from the disk header
is listed, including 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). With -s, the output format is
the same whether or not accessname arguments are specified.
If the -q option is specified, no header is printed describing
output fields. This option has no effect with the long formats
generated 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 does not apply 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, the check
keyword might incorrectly report a failed nopriv disk as okay
and usable. Changes some attributes for a disk. The attributes
are either simple names (used to turn an attribute on or off),
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. Used with nconfig=count to change the
number of configuration copies and log copies for the disk
device specified by the accessname argument. See the init key‐
word description for details on the nconfig attribute.
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 avail‐
able for the remaining configuration database on that disk will
be increased.
Refer to the Logical Storage Manager manual for more information
about when to use this option.
SEE ALSOvolintro(8), vold(8), voldg(8), volume(8)voldisk(8)