 |
Index for
Section 8 |
|
 |
Alphabetical
listing for V |
|
 |
Bottom of
page |
|
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
-f Forces an operation that would normally fail.
-a Specifies all online disks that are not currently in an imported disk
group.
-g diskgroup
Specifies the disk group for the operation.
-q Suppresses the listing of output field labels.
-s 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 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 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 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 recovering 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) 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. 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
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 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 Logical
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 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 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 private 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 database. 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:
init
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 configuration is enabled.
You can apply the following disk attributes with voldisk init:
type=disk_type
Specifies 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 Tru64 UNIX, the valid
disk_type names are: nopriv, simple, and sliced. See the Disk Types
section for details.
offline
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.
publen=length or len=length
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.
puboffset=offset or offset=offset
Specifies the offset in blocks from the beginning of the partition
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 hardware
stripe set, you can use a different offset to maintain stripe
alignment.
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 volume start operation interprets volatile plexes as
requiring a complete resynchronization from other plexes in the
same volume.
This attribute applies only to the nopriv device type.
pubslice=num or slice=num
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.
privslice=num
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:
privoffset=offset
Specifies the offset in blocks from the beginning of the partition
containing the private 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.
privlen=length
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 partition information is available, a private region
length must be specified in this command.
nconfig=count
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. 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.
configlen=length
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.
loglen=length
Specifies the size in blocks 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.
define
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 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 reconfigure your disks.
You can define the following disk attributes with voldisk define:
type=disk_type
See the init keyword description for details.
offline
Specifies that the disk be created in the offline state.
publen=length or len=length
See the init keyword description for details.
puboffset=offset or offset=offset
See the init keyword description for details.
volatile
See the init keyword description for details.
diskid=newdiskid
Sets the disk ID to the newdiskid value in the disk access record
for the nopriv disk.
pubslice=num or slice=num
See the init keyword description for details.
privslice=num
See the init keyword description for details.
privoffset=offset
See the init keyword description for details.
offline
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 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.
online
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.
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 manager to
rescan all disk headers, or to adapt to changes in a disk's
partitioning.
rm Removes the specified disk access records, by disk access name.
list
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 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.
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 does not apply to disks that are in imported disk
groups.
check
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.
set 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.
moddb
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 keyword 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 available 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 ALSO
volintro(8), vold(8), voldg(8), volume(8)
|
Index for
Section 8 |
|
|
Alphabetical
listing for V |
|
 |
Top of
page |
|