volsd(8) System Manager's Manual volsd(8)
NAME
volsd - Perform Logical Storage Manager operations on subdisks
SYNOPSIS
/sbin/volsd [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] [-l offset] assoc plex subdisk...
/sbin/volsd [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] [-l[column/] offset] assoc plex subdisk[:[column/] offset]...
/sbin/volsd [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] aslog plex subdisk
/sbin/volsd [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] [-p plex] dis subdisk...
/sbin/volsd [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] [-p plex] [-s size] split subdisk newsd [newsd2]
/sbin/volsd [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] [-p plex] join sd1 sd2... newsd
/sbin/volsd [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] [-p plex] mv oldsd newsd [newsd...]
OPTIONS
The following options are recognized: Specifies the disk group for the operation, either by disk group ID or by disk group name. By
default, the disk group is chosen based on the name operands. Limits the operation to apply to this usage type. Attempts to affect vol-
umes with a different usage type will fail. Passes in usage-type-specific options to the operation. A certain set of operations are
expected to be implemented by all usage types: Reduces the system performance impact of copy operations. Copy operations are usually a set
of short copy operations on small regions of the volume (normally from 16 kilobytes to 256 kilobytes). This option inserts a delay between
the recovery of each such region. A specific delay can be specified with iodelay as a number of milliseconds, or a default is chosen (nor-
mally 250 milliseconds). Performs copy operations in regions with the length specified by size, which is a standard Logical Storage Man-
ager length number (see volintro(8)). Specifying a larger number typically causes the operation to complete sooner, but with greater impact
on other processes using the volume. The default I/O size is typically 256 kilobytes. Removes the subdisks after successful completion of
a volsd dis operation. Removes the source subdisk after successful completion of volsd mv. Writes a list of utilities that would be
called from volsd, along with the arguments that would be passed. The -V performs a ``mock run'' so the utilities are not actually called.
Specifies the size for the subdisk split operation. This option takes a standard Logical Storage Manager length number (see volintro(8)).
Specifies the offset of a subdisk within a plex address space for the volsd assoc operation. For striped plexes, a column number may be
optionally specified. If one number is given for striped plexes, the number is interpreted as a column number and the subdisk is associ-
ated at the end of the column. The offset is a standard Logical Storage Manager length number (see volintro(8)). Requires that a named
plex be associated with this volume, or that a named subdisk (source subdisk for volsd split, join, and mv) be associated with a plex that
is associated with this volume. Requires that a named subdisk (source subdisk for volsd split, join, and mv) be associated with this plex.
Forces an operation that the Logical Storage Manager considers potentially dangerous or of questionable use. This permits a limited set of
operations that would otherwise be disallowed. Some operations may be disallowed even with this flag.
DESCRIPTION
The volsd utility performs Logical Storage Manager operations on subdisks and on plex-and-subdisk combinations. The first operand is a
keyword that determines the specific operation to perform. The remaining operands specify the configuration objects to which the operation
is to be applied.
Each operation can be applied to only one disk group at a time, due to internal implementation constraints. Any plex or subdisk name oper-
ands will be used to determine a default disk group, according to the standard disk group selection rules described in volintro(8). A spe-
cific disk group can be selected with -g diskgroup.
If a volsd operation is interrupted by a signal, an attempt is made to restore the disk group configuration to a state that is roughly
equivalent to its original state. If this attempt is interrupted, such as through another signal, the user may need to perform some
cleanup. The specific cleanup actions that are needed are written to the standard error before volsd exits.
KEYWORDS
These are the recognized operation keywords: Associates each named subdisk operand with the specified plex. The first form applies to con-
catenated plexes (plexes with a layout of concat). The offset within the plex for the association can be specified with -l, which takes a
standard Logical Storage Manager length number (see volintro(8)). If no offset is specified, the default is to associate the subdisk at the
end of the plex, thus extending the length of the plex by the length of the new subdisk.
For striped plexes, a column number for the subdisk association may be specified. The offset is interpreted as the column offset for
the subdisk. If only one number is specified with -l for striped plexes, the number is interpreted as a column number and the sub-
disk is associated at the end of the column.
The column or column/offset at which a subdisk is to be associated can also be specified as part of the subdisk name in the same
manner as subdisks associations are specified for plex creations in volmake (see volmake(4)). When specifying multiple subdisks, if
no column or column/offset is specified for a subdisk, it is associated after the previous subdisk.
A subdisk cannot be associated to overlap with an another associated subdisk in the same plex.
If the named plex is associated with a volume, the rules for performing the operation depend upon the usage type of the volume. A
subdisk cannot be associated to a plex if the putil0 field for the subdisk is not empty. Creating a subdisk with the putil0 field
set to a non-empty value is a sufficient means of ensuring that no Logical Storage Manager operation will write to the region of
disk blocks allocated to the subdisk because the subdisk cannot be associated through any means to a plex, and because subdisks can-
not be used directly to read from or write to a disk. Associates the named subdisk with the named plex as a log area for the plex.
At most, one log subdisk can be associated with a plex at any given time. Currently, log subdisks can be used only with the dirty
region logging feature, as defined by the DRL volume logging type. If the named plex is associated with a volume, the rules for
performing the operation depend upon the usage type of the volume. A subdisk cannot be associated if the putil0 field is set on the
subdisk, just as with volsd assoc. Dissociates each specified subdisk from the plex that it is associated with. If a subdisk is
associated (through its plex) with a volume, the rules for performing the operation depend upon the usage type of the volume.
Subdisk dissociation can be used as part of tearing down a plex, or as part of reorganization of disk space usage. Typically, the
subdisk is no longer needed after dissociation. To support this type of use, -o rm can be specified to remove the named subdisks
after successful dissociation. Splits the subdisk subdisk into two subdisks that reside on the same section of the same device, and
that have contiguous or striped plex associations (if the named subdisk is associated). The first of the two resultant subdisks
will have a length of size, and the second will take up the remainder of the space used by the original subdisk. If both newsd and
newsd2 are specified, the resultant subdisks are newsd and newsd2. If no newsd2 operand was specified, the resultant subdisks are
named subdisk and newsd.
If the named subdisk is associated with an associated plex, the rules for performing the operation depend upon the usage type of the
volume. Log subdisks cannot be split. Joins the subdisks named by the sd operands to form a new subdisk named newsd. The sd oper-
ands must specify subdisks that represent contiguous sections of the same device, and of the same plex (if they are associated).
For a striped plex, the sd operands must be in the same column. At least two sd operands are required. At the end of the operation,
the sd configuration objects are removed. The newsd operand can have the same name as one of the sd operands, or it can have a dif-
ferent name.
If the sd operands are associated with an associated plex, the rules for performing the operation depend upon the usage type of the
volume. Moves the contents of oldsd onto the new subdisks and replaces oldsd with the new subdisks for any associations. If multi-
ple new subdisks are specified, they are associated starting where the old subdisk began and placed consecutively with no space
between them. The operation requires that oldsd be associated with an associated plex and that all new subdisks be dissociated. The
operation can be used on a subdisk that is used by an active volume, and will ensure that data is copied and associations are
changed without loss or corruption of data. The rules for performing the operation depend upon the usage type of the volume.
Moving a subdisk is the normal means of reorganizing disk space. For example, move regions of disk used by one volume to another
disk to reduce contention on the original disk. Typically, once the operation completes, the original subdisk is no longer needed
and can be removed. To support this use of the operation, -o rm can be specified to remove oldsd after successful completion of the
operation.
FSGEN AND GEN USAGE TYPES
The fsgen and gen usage types provide identical semantics for all operations of the volsd utility.
In addition to the standard -o options required for all usage types, the fsgen and gen usage types provide the following additional option:
Forces an operation that the Logical Storage Manager considers potentially dangerous or of questionable use. This applies to attempts to
dissociate subdisks (making a plex sparse) and to attempts to move subdisks onto subdisks that have a different size. This flag is the
same as -f.
Limitations and extensions for the fsgen and gen usage types consist of the following: If the named plex is enabled, and is associated with
an enabled plex, the named plex must be ACTIVE or EMPTY. Subdisks can be associated with a non-enabled plex only if the utility state of
the plex is EMPTY, STALE, or OFFLINE, or if the plex is CLEAN and no other plexes associated with the volume are CLEAN or ACTIVE.
If the subdisk is associated with a non-enabled plex, or if it is associated with the only enabled, read-write plex in a volume, the
operation completes without copying any data onto the subdisk. If the subdisk is associated with an enabled plex in a mirrored vol-
ume, the operation may have to copy data from the volume onto the new subdisk before the operation can complete. If a log subdisk
is associated with a plex that is associated with a volume that has a logging type of UNDEF, the logging type of the volume is con-
verted to DRL. Logging of volume changes is not enabled until there are at least two read-write mode plexes attached to the volume.
Dissociating a subdisk requires use of -f if it would cause an enabled plex in an enabled volume to become sparse relative to the
volume. Even with -f, it is not possible to make two plexes sparse if no complete, enabled, read-write plexes would remain associ-
ated. For disabled volumes, a similar check is made with respect to ACTIVE and CLEAN plexes. The fsgen and gen usage types apply
no additional restrictions and add no extensions to the split and join operations. If the total size of the destination subdisks
differs from that of the source subdisk, the -f option must be specified. The operation still fails if the total size of the desti-
nation subdisks is larger than the source subdisk and if the address range of any destination subdisk would conflict with another
subdisk that is associated with the plex. The total size of the destination subdisks cannot be larger than the source subdisk if
the kernel state of the volume or plex is detached.
The operation fails if the total size of the destination subdisks is smaller than the source subdisk and the operation would cause
the total number of complete, enabled, read-mode plexes in the volume to drop to zero, while leaving more than one sparse, enabled,
read-write plex.
RAID5 USAGE TYPE
In addition to the standard -o options required for all usage types, the raid5 usage type provides the following additional options: Forces
an operation that the Logical Storage Manager considers potentially dangerous or of questionable use. This applies to attempts to move a
subdisk in a RAID5 plex if the volume the plex is associated with does not have a log plex. This flag is the same as -f.
The raid5 usage type supports the following keywords: Associates the named subdisks with the named RAID5 plex. If plex is enabled and is
associated with an enabled volume, any data that maps onto the subdisk will be regenerated from the other columns of the RAID5 plex. This
is done by marking the subdisk as stale and writeonly, regenerating the data via VOL_R5_RECOVER ioctls, and then turning off the stale and
writeonly flags.
If the RAID5 plex is not associated or the RAID5 volume is not ENABLED, the subdisk is associated and marked as stale. The subdisk's
contents will be recovered when the volume is started.
The assoc operation may not be used on a log plex. Dissociates the named subdisks from the named RAID5 plex. If removing the sub-
disk would make the volume unusable (because other subdisks in other columns at the same altitude are unusable or missing) and the
volume is not disabled and EMPTY, the operation is not allowed. If the volume is disabled and non-EMPTY the operation requires use
of -f.
The dis operation may not be used on a log plex. The raid5 usage type applies no additional restrictions and adds no extensions to
the split and join operations. These operations may not be used on a log plex. If the old subdisk is associated with a RAID5 plex
that is associated to a RAID5 volume, the volume must be enabled for the move operation to complete. The mv operation is not allowed
if the volume has stale parity or has missing or stale subdisks at the same altitude as the subdisk being replaced.
The mv operation first dissociates the old subdisk and then associates the new subdisk in its place. It then recovers the data using
VOL_R5_RECOVER ioctls, as is done for the assoc operation. If the RAID5 volume has no valid logs, the operation requires use of -f.
This is necessary because if a crash were to occur while the data on the new subdisks was being recovered, the parity could become
stale while some of the new subdisks are marked stale, thus rendering the volume unusable.
The mv operation may be used on a log plex. Similar rules as those defined for the fsgen and gen usage type plexes apply to log
plexes. The force or -f must be used to make a log plex sparse.
Note that there is no aslog operation for the raid5 usage type. Logging is done on a plex level and therefore volsd aslog is not needed.
Log plexes can be associated with RAID5 volumes using the volplex att command.
EXIT CODES
The volsd utility exits with a nonzero status if the attempted operation fails. A nonzero exit code is not a complete indicator of the
problems encountered, but rather denotes the first condition that prevented further execution of the utility. See volintro(8) for a list
of standard exit codes.
FILES
The utility that performs volsd operations for a particular volume usage type.
SEE ALSO
volintro(8), volplex(8), volsd(8), volume(8)
volsd(8)