 |
Index for Section 8 |
|
 |
Alphabetical listing for V |
|
voldisk(8)
NAME
voldisk - Define and manage Logical Storage Manager (LSM) disks
SYNOPSIS
/sbin/voldisk init accessname [attribute...]
/sbin/voldisk define accessname [attribute...]
/sbin/voldisk moddb accessname [attribute...]
/sbin/voldisk offline accessname...
/sbin/voldisk online accessname...
/sbin/voldisk rm accessname...
/sbin/voldisk list [disk...]
/sbin/voldisk clearimport accessname...
/sbin/voldisk check accessname...
DESCRIPTION
The voldisk utility performs basic administrative operations on disks.
Operations include initializing and replacing disks, as well as taking care
of some book-keeping necessary for the disk model presented by the Logical
Storage Manager.
The voldisk utility accesses disks based on disk access names, which are
system-specific names that relate to disk addresses. For example, SCSI
disk access names are usually of the form rznp, where rz is the device
mnemonic for SCSI devices, n is the SCSI unit number, and p is the
partition identifier (in the range a to h). All disk access names relate
directly to device node names in the /dev directory.
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. 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 voldisk 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 Logical Storage Manager information.
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 losing the ability to use the disk.
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 Logical
Storage Manager will search the first 256 sectors of the private region
for the alternate copy.
Table of contents
The table of contents contains 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 between zero and two disk group configuration
copies, according to 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 normally contains between zero and two 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 block-change-log failures, the first
write to a volume, and volume closes. 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.
The behavior of the voldisk utility depends upon the keyword specified as
the first operand. Supported operations are:
/sbin/voldisk init
Initialize 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 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 voldisk 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 type could
indicate a volatile RAM disk that may not require the storage of
any private data, or could be for a hard disk with free partitions.
The various disk types support additional attributes for the init
operation. See the definition for each disk type, below.
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.
/sbin/voldisk define
Define a disk access record, but do not initialize it. In order for the
Logical Storage 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 voldisk define to make it accessible first. 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.
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, below.
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 useful 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.
/sbin/voldisk moddb
Change the number of configuration copies for the disk device specified
by the accessname argument. By decreasing the number of configuration
copies on a disk, the size of the configuration database on that disk
will be increased. Refer to the Logical Storage Manager manual for more
information about when to use this option.
/sbin/voldisk 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.
/sbin/voldisk 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.
/sbin/voldisk rm
Remove disk access records, by name.
/sbin/voldisk list
List detailed disk information on the specified disks. If no accessname
arguments are specified, then print a one-line summary for all disk
access records known to the system. If accessname 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 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.
/sbin/voldisk 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.
/sbin/voldisk check
Check the status of a disk in LSM. If the disk is online, print the
message Okay. If the disk is offline or inaccessible, print an error
message.
DISK TYPES
Three disk types are provided with the Logical Storage Manager. The default
is a sliced type for disk access names without a partition name, such as
rz3. If a partition name, such as rz3c, is supplied, then the default type
becomes simple.
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 voldisk addregion. Also, such
disks are not self identifying. Because nopriv disks are not self
identifying, the Logical Storage Manager cannot track the movement of such
disks on a SCSI chain or between controllers.
Note
Do not initialize a new disk as a nopriv disk - this disk type is
appropriate only for encapsulation of existing data.
To add a disk with no configuration database, set the nconfig
attribute to 0 when initializing the disk.
nopriv devices are most useful for defining special devices (such as
volatile RAM disks) that you wish to use with the Logical Storage 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 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.
Attributes that can be used with the voldisk 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
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 volume start
operation interprets volatile plexes as requiring a complete revive
from other plexes in the same volume.
The voldisk 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 simple type, the partition is marked with disklabel tag LSMsimp.
For the sliced type, then the public and private regions are in partitions
with disklabel tags LSMpubl and LSMpriv, respectively.
Attributes that can be defined with voldisk 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. 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, voldisk 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 zero. 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 512 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. The number of
configuration copies should be the same as the number of log regions.
This defaults to 1. This can be set to 0 to indicate that no
configurations will be stored on the disk. It is reasonable to set this
to 1 for disk groups that contain three or more disks. This would allow
either more configuration records or a smaller reserved private region.
In disk groups with more than 8 disks, it may be reasonable to set
nconfig to zero for some disks, so that space for configuration copies
is allocated only on some disks. Setting nconfig to zero improves the
performance of LSM configuration updates and reduces the time required
to import a disk group.
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. The number of log
regions should be the same as the number of configuration copies. Logs
regions are used for storing any plex detaches that happen within the
disk group. This number defaults to 1. It may be desirable to reduce
this number to 0 on some disks, if you have disk groups with large
numbers of disks. However, at least one valid log copy (preferably at
least four, two copies each on two drives) must be usable for a disk
group to be usable.
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.
SEE ALSO
volintro(8), vold(8), voldg(8), volume(8)