 |
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
The following options are recognized:
-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 mnenomic 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 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). 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.
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 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 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.
The disk label fstype tag for a nopriv partition is LSMnopriv.
Note
Do not use the type=nopriv attribute for the purpose of initializing 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 automatically 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 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 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:
init
Initializes regions of a disk used 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 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 permanent list of
known disks until the root configuration is enabled.
Attributes that can be used with voldisk init are:
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. 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.
puboffset=offset or offset=offset
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.
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 revive from other plexes in the same volume.
This attribute can be used only for 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
can be used only for 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
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:
privoffset=offset
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.
privlen=length
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
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. 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.
configlen=length
Specifies the size 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 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
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 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.
Attributes that can be used with voldisk define are:
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 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.
online
Clears 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.
The -a can be specified to 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.
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 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 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 cannot be applied 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, a failed nopriv
disk may continue to be considered okay and usable after using this
option.
set 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 currently unimplemented for any of the
existing disk types.
moddb
Changes the number of configuration copies and log copies for the disk
device specified by the accessname argument.
By decreasing the number of configuration copies and log copies on a
disk, the size of the 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)
|
Index for
Section 8 |
|
|
Alphabetical
listing for V |
|
 |
Top of
page |
|