volume(8)volume(8)NAMEvolume - Performs Logical Storage Manager operations on volumes
SYNOPSIS
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] init
init_type volume [arg...]
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] rdpol policy
volume [plex]
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] start vol‐
ume...
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] startall
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] stop vol‐
ume...
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] stopall
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] resync vol‐
ume...
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] maint vol‐
ume...
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] set
attribute=value... [--] volume...
The following additional volume operation applies only to the raid5
usage type: /sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt]
recover volume [subdisk]...
OPTIONS
The following options are recognized: Specifies the disk group for the
operation. The disk group can be specified either by name or by disk
group ID. If no disk group is specified, the rootdg disk group is
implied. See voldg(8) for more information on disk groups. Forces the
operation to be performed by the usage-type utility for this usage
type. Displays a list of utilities that would be called from volume,
along with the arguments that would be passed. The -V option performs a
“mock run” so the utilities are not actually called, and no changes are
made to the volume configuration database. Forces an operation in some
situations where the operation has questionable semantics. For example,
use -f to reduce the length of a volume with volume set, to stop a vol‐
ume that is currently open or mounted as a file system, or to attempt
to start a volume that has no plexes with valid data. Passes in usage-
type-specific options to the operation.
The following -o options apply to all usage types: Performs any
extended recovery operations in background processes after the
volume and one or more plexes have been enabled. A volume that
is started or whose length is changed successfully with this
option is usable immediately after the operation completes,
although recovery operations may affect performance of the vol‐
ume for an extended period of time. Forces an operation that is
not normally performed as part of the operational model of the
Logical Storage Manager and may have adverse effects on data.
This is the same as -f. Performs up to the specified number of
plex recovery operations simultaneously. If no count is speci‐
fied, a suitable small number is used (normally 10). Does not
perform any plex recovery operations when starting a volume, but
simply enables the volume and any plexes. This may leave some
stale plexes, and may leave a mirrored volume in a special read-
writeback (NEEDSYNC) recover state that performs limited plex
recovery for each read to the volume. Reduces the system per‐
formance impact of plex recovery operations and volume length
changes. Startup recovery and length change consistency opera‐
tions are usually a set of short operations on small regions of
the volume (normally from 16KB to 256KB). This option inserts a
delay between the recovery of each such region. You can set the
delay (in milliseconds), or use the default (normally 250 mil‐
liseconds). Performs recovery operations in regions with the
length specified by size, which is a standard LSM 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 typi‐
cally 256KB. Prints a message for each volume that is success‐
fully started. Without this option, messages appear only for
volumes that fail to start.
The gen usage type supports the following additional -o option:
Prevents the start operation from recovering plexes through the
volplex utility. Instead, all STALE and ACTIVE plexes are simply
treated as equivalent to CLEAN plexes, and are thus enabled
without being made consistent. This is useful for volumes whose
contents are recreated for each use, for example a swap area or
the /tmp file system. In the case of /tmp, the model assumes
that newfs is used to create an empty file system after the vol‐
ume has been started.
The raid5 usage type supports the following additional -o
options: Sets the checkpoint size for a volume. A complete
resynchronization of a volume via VOL_R5_RESYNC ioctls can take
a long time. It is conceivable in some circumstances that the
operation could be stopped before it completes (such as by a
system crash). To avoid having to restart the synchronization
from the beginning of the volume (after a certain amount of the
volume has been synchronized), a transaction is issued to record
the offset to which the resynchronization has completed. This
size is called the checkpoint length and can be set using the
checkpt option. The default checkpoint length is 64MB. Prevents
the start operation from undergoing some recovery operations.
Any valid RAID5 logs are replayed; however, no parity resynchro‐
nizations or subdisk recoveries are performed. Allows access to
certain volumes earlier in the starting process than is normally
allowed by the operating process of RAID5 volumes. This can have
adverse effects on the data, and can also result in the RAID5
volume becoming unusable after a system crash or a power fail‐
ure. Allows the delayrecover option to be ignored if the volume
must undergo parity resynchronizations or subdisk recoveries
before the volume can be enabled.
DESCRIPTION
The volume utility performs Logical Storage Manager operations on vol‐
umes. The first operand is a keyword that determines the specific
operation to perform. The remaining operands specify configuration
records to which the operation applies.
Each operation can be applied to only one disk group at a time, due to
internal implementation constraints. Any volume operands are used to
determine a default disk group, according to the standard disk group
selection rules described in volintro(8). A specific disk group can be
selected with -g diskgroup.
The recognized operation keywords are: Initializes a volume. This can
be applied to volumes that were created by volmake and that have not
yet been initialized, or volumes that have been set to the uninitial‐
ized state with volmend fix empty. The action to perform is specified
by the init_type operand, which is usage-type-dependent. The volume op‐
erand determines which usage type to use for performing the operation.
For usage-type-specific information on this operation, see the
sections FSGEN AND GEN USAGE TYPES and RAID5 USAGE TYPE. Sets
the read policy for a volume based on the policy operand. (This
keyword is not supported for the raid5 usage type.) These are
the recognized read policies: Uses a round-robin read order
among the enabled, readable plexes associated with the volume.
No plex operand should be specified for the round read-policy
type. Reads preferentially from the plex named by the plex op‐
erand. If the plex is enabled, readable, and associated with the
volume, any read operation on the volume results in a read from
that plex if all blocks requested in the read are contained in
the plex. The plex operand is required for the prefer read-pol‐
icy type. Selects a default policy based on plex associations
to the volume. For a volume that contains one enabled, striped
plex, the default is to prefer that plex. For any other set of
plex associations, the default is to use a round-robin policy.
No plex operand should be specified for the select read-policy
type. Enables disabled or detached volumes named by the volume
operands. The process of enabling a volume is a highly usage-
type-dependent operation and may result in transfers of data
between plexes associated with the volume.
If the start operation is applied to an uninitialized volume
(for example, a volume just created by volmake), a default ini‐
tialization is used to initialize and enable the volume.
If the volume is not started normally because failures and disk
removals have left all associated plexes with invalid data, you
can use the -f option to try to start the volume, anyway. For
example, you can force the volume to start after replacing disks
to enable the volume so that its contents can be restored from
backup or reinitialized.
For usage-type-specific information on this operation, see the
sections FSGEN AND GEN USAGE TYPES and RAID5 USAGE TYPE.
Attempts to start all volumes that are disabled. If a -U usetype
option is specified, this operation attempts to start all dis‐
abled volumes with the indicated usage type. This operation
doesnot start uninitialized volumes. By default, all volumes in
the rootdg disk group are started. A different disk group can be
specified with the -g option. Disables the enabled or detached
volumes named by the volume operands.
The stop operation provides an interface to the usage type of a
volume for shutting down operations on a volume in a clean man‐
ner. The specific method for cleanly stopping a volume, and the
precise meaning of “clean” are both highly usage-type-dependent.
By convention, you can use -f to forcibly stop a volume that is
in use, forcing I/O failures to be returned for any further vol‐
ume device operations.
For usage-type-specific information on this operation, see the
sections FSGEN AND GEN USAGE TYPES and RAID5 USAGE TYPE.
Attempts to stop all volumes that are enabled. If a -U usetype
option is specified, this operation attempts to stop all dis‐
abled volumes with the indicated usage type. By default, all
volumes in the rootdg disk group are stopped. A different disk
group can be specified with the -g option. Examines all volumes
named by the volume operands and performs any synchronization
operations that are required. The exact procedure for this oper‐
ation is usage-type specific. See the sections FSGEN AND GEN
USAGE TYPES and RAID5 USAGE TYPE for details. This keyword is
supported only for the raid5 usage type.
Use this option to initiate a recovery of subdisks containing
invalid data. If subdisks are specified and are stale, they are
recovered in the order specified. This is done by setting the
stale and write-only flags on the subdisks and issuing
VOL_R5_RECOVER ioctls to regenerate the data. After a success‐
ful recovery, the subdisk is marked as non-stale and read-write.
If no subdisk arguments are specified, the subdisks of the RAID5
plex of the volume are checked to see if they are stale or have
invalid contents. If any are found, they are recovered as
described above. Detaches each volume named by the volume oper‐
ands. When a volume is detached, normal read and write opera‐
tions to the volume fail, although most volume ioctl operations
can still be used.
For further usage-type-specific information on this operation,
see the section FSGEN AND GEN USAGE TYPES. Changes volume char‐
acteristics specified by entering arguments immediately after
the set keyword in the form attribute=value. The volumes
affected by the operation follow these operands; thus the
attribute list must end with an operand that does not contain an
equal sign.
To allow for volume names that contain an equal sign, you can
use an operand of -- to terminate the attribute list. Each usage
type represented by the list of volume operands is called once,
with the set of all volumes with that usage type.
An attribute argument of the form len=number is interpreted (if
at all) as requesting a change in the length of a volume,
regardless of the volume's usage type. The number value is
interpreted as a standard length number (see volintro(8)).
The set of all other attribute=value attribute arguments that
are recognized depends upon the volume usage type. See the sec‐
tions FSGEN AND GEN USAGE TYPES and RAID5 USAGE TYPE for
details.
FSGEN AND GEN USAGE TYPES
Limitations and extensions for the fsgen and gen usage types consist of
the following: The fsgen and gen usage types recognize the following
init_type operands for the volume init operation: Sets the state for
the specified plex to CLEAN, and sets all other plexes to STALE. The
volume start operation can then be used to recover the volume from the
CLEAN plex. This operation requires that the volume not be enabled.
If the specified volume has only one plex, the plex argument is
not required as it defaults to that plex. If specified, the plex
argument must represent a plex that is associated with the vol‐
ume. Sets the state for all plexes associated with volume to
ACTIVE and enables the volume and its plexes. This is used to
initialize a single or multiple-plex volume where all plexes are
known to have identical contents. Enables the volume and its
plexes but leaves the volume uninitialized. This operation can
be used only for non-enabled volumes. It is used to temporarily
enable a volume so that data can be loaded onto it to make it
consistent. Once the data has been loaded, init active should
be used to fully enable the volume. init active could be used,
for example, if a complete image of the volume is to be loaded
from a tape. Writes zero blocks to all plexes in the volume, up
to the length of the volume. After the writes complete, the
state of each plex is set to ACTIVE and the volume and its
plexes are enabled. init zero volume could be used, for exam‐
ple, before running newfs to put a file system on the volume.
If this operation is interrupted by a signal, an attempt is made
to restore all affected records to their original state, or to a
state that is roughly equivalent to their original state. If
this attempt is interrupted, such as through another signal, the
user many need to perform some cleanup. A set of commands to
perform this cleanup are written to the standard error before
the volume utility exits. Starting an uninitialized gen or
fsgen volume enables the volume and its plexes, sets the plexes
to the ACTIVE state, and recovers the plexes to ensure that each
plex has the same contents. If the volume has only one plex, the
volume is immediately set to the ACTIVE state; otherwise, the
volume is set to the SYNC state and a special read/write-back
mode is used to recover regions of the volume on every read
operation. The volume is read from beginning to end to make all
plexes consistent, then the volume is set to the ACTIVE state.
Starting a volume with no active dirty region logging involves
enabling all CLEAN and ACTIVE plexes and putting them in the
ACTIVE state. If an I/O failure was logged against the plex, or
if a disk replacement caused a plex to become stale, the plex is
considered STALE. If any of the subdisks for the plex reside on
a removed or inaccessible disk, the plex is ignored for the pur‐
poses of starting the volume.
If two or more plexes were enabled, and if the volume was active
at the time the system went down, the state for the volume is
set to SYNC and a special read/write-back recovery mode is used
to recover consistency of the volume, segment-by-segment, on
every read. A process is then started (in the background with
the -o bg option) to recover consistency for the entire length
of the volume.
If any plexes were considered STALE, those plexes are attached
by calling volplex att. The number of concurrent plex attach
operations are limited based on the rules for -o plexfork.
Recovery of plexes with a dirty region log uses the same rules
as for volumes without a valid dirty region log, except that
recovery of non-stale plexes is done by scanning the contents of
the dirty region log and recovering consistency for those
regions listed in the log as requiring recovery.
In addition to enabling the volume and managing the recovery of
plex consistency, starting a volume clears any transient opera‐
tions that were being applied to a volume before the system was
rebooted. Starting a volume dissociates and removes temporary
plexes or subdisks, and dissociates plexes that were being
attached if the attach operation did not complete. Snapshot
plexes created by volassist are also removed.
If the volume is unstartable because there are no valid, non-
stale plexes and the -f flag is then specified, all STALE plexes
that do not contain unusable subdisks (subdisks on failed or
removed disks) are changed to ACTIVE. The volume is then started
and synchronized from those plexes. Stopping an fsgen or gen
volume disables the volume and its associated plexes. In addi‐
tion, the utility state for each ACTIVE plex is changed as fol‐
lows: If the plex is detached or disabled, the state for the
plex is set to STALE. If all plexes are set to STALE, the volume
cannot be started until volmend is used to change the state of
one or more plexes to CLEAN or ACTIVE. A plex normally becomes
detached as a result of an I/O error on the plex, or a disk
failure or replacement. I/O failures will not normally detach
the last remaining enabled plex in a volume, so disk removal
operations are the only normal operational method of making a
volume unstartable. If the plex is volatile, that is, one of
the subdisks in the plex is defined on a disk with the volatile
attribute (see voldisk(8)), the plex state is set to STALE. If
the volume is enabled and the plex is also enabled, the plex
state is set to CLEAN. If the volume is detached and the plex
is enabled, the plex state is left as ACTIVE. A volume can be
left detached, with remaining valid plexes, only as a result of
calling volume maint to detach an enabled volume.
Normally, the stop operation fails if any extended operations
are using the volume or any of its associated plexes. Such oper‐
ations are detected as a nonempty value for the tutil0 field in
a volume or plex record. If the -f option is specified, the stop
operation ignores volume and plex tutil0 fields.
The -f option must also be used to forcibly stop a volume that
is open or mounted as a file system. In this case, a warning
message is still written to the standard error, but the stop
operation is not otherwise affected. Stopping an open or mounted
volume is not normally advisable. Volumes that have possibly
differing plex contents are resynchronized to contain consistent
data. Any such volumes that are in the NEEDSYNC state are recov‐
ered using a read/write-back recovery mode and then put into the
ACTIVE state.
Plexes in the SYNC state may already be under recovery and the
volume command will take no action to recover them unless the
command was invoked with the -o force option. The -f option is
required to detach an enabled volume. Also, a warning is written
to the standard error for volumes that are open or mounted. The
attributes that can be set for fsgen and gen volumes are:
Changes the length of each volume specified by the volume oper‐
ands to number sectors. The number parameter is a standard Logi‐
cal Storage Manager length number (see volintro(8)). Decreasing
the length of a volume requires use of -f.
If the volume is enabled, the number of enabled, read-write
plexes that would remain complete after the length change are
counted. The operation fails if this number would become zero,
but the number of sparse plexes would become greater than 1.
Changing the length of a volume with one enabled plex beyond the
length of the plex requires use of the -f option.
If the volume is not enabled, the number of CLEAN and ACTIVE
plexes that would remain complete after the length change are
counted, then the algorithm mentioned previously is used for
determining whether the operation is allowed or requires use of
-f.
To ensure that the new region of the volume is consistent across
all plexes of the volume, the volume is put into a SYNC state
and read/write-back mode, and a read loop is then performed
against the volume. Once this loop has completed, the volume is
put back into the ACTIVE state. Sets the type of logging to be
used on the volume. This change can be applied only to volumes
that are stopped and that have no ACTIVE plexes. Allowed log
types are drl (logs the regions involved in all volume writes),
none (never does logging), and undef (never does logging). If
the logging type is set to undef, a future volsd aslog or vol‐
plex att operation will change it to drl. See the sections FSGEN
AND GEN USAGE TYPES and RAID5 USAGE TYPE of the volsd(8) and
volplex(8) reference pages for more information. Sets the size
for logs used with the volume. The size value is a standard Log‐
ical Storage Manager length number (see volintro(8)). Stops the
FPA logging process on the named volume(s). Use this option to
stop logging on the primary and/or secondary volumes in cases
where you decide not to reattach a migrant plex back to its pri‐
mary volume. Sets options that are applied to the volume every
time the volume is started, independently of options specified
with the volume start command. This is a set of comma-separated
options of the same form used with the -o option. Only the
delayrecover, norecov, and verbose options can be applied to
volumes in this manner. Unrecognized or inappropriate options
are ignored. The resync operation examines the named volumes.
Volumes that have possibly differing plex contents are resyn‐
chronized to contain consistent data. Any such volumes that are
in the NEEDSYNC state are recovered using a read/write-back
recovery mode and then put into the ACTIVE state.
Plexes in the SYNC state may already be under recovery and the
volume command will take no action to recover them unless the
command was invoked with the -o force option.
RAID5 USAGE TYPE
Limitations and extensions for the raid5 usage type consist of the fol‐
lowing: The raid5 usage type recognizes the following init_type oper‐
ands for the volume init operation: Zeroes the RAID5 log plexes, if
any, and makes the volume available for use. The parity in the volume
is marked as stale, though no parity resynchronization is performed;
the volume is left with a state of NEEDSYNC. Writes zeros to the RAID5
log plexes, if any, and writes zeros to the entire length of the vol‐
ume. This is achieved by issuing the VOL_R5_ZERO ioctl for the entire
altitude of the volume. The volume is left in the ACTIVE state. Start‐
ing an uninitialized volume (one with a state of EMPTY) zeroes any
RAID5 log plexes and then resynchronizes the parity of the volume by
issuing VOL_R5_RESYNC ioctls. All subdisks are marked as non-stale and
read-write. The volume and RAID5 plex are then enabled and marked as
ACTIVE, and all valid RAID5 log plexes are marked as LOG. If any RAID5
log plex proves to be invalid (such as having its NODAREC flag set) its
state is set to BADLOG.
Starting a volume that has been shut down cleanly or is not
marked as dirty enables the RAID5 plex and RAID5 log plexes and
sets the volume kernel state to detached, to zero the RAID5 log
plexes for the volume, if any. Once this is completed, all valid
RAID5 log plexes are set to LOG and the volume is enabled and
put in the ACTIVE state.
Starting a volume that was not shut down cleanly requires that
the parity be resynchronized. If the volume has valid RAID5 log
plexes, the volume is first detached and has its state set to
REPLAY, and all log plexes and the RAID5 plex are enabled. If
there are any valid RAID5 log plexes, their contents are read
and their data is written to the appropriate regions of the
RAID5 plex. If reading the RAID5 logs fails, the logs are marked
as invalid and the parity is resynchronized as if there were no
logs. Once the replay is complete, the RAID5 logs are enabled
and the volume is enabled and its state is set to ACTIVE.
If the volume needs resynchronization and no valid log plexes
exist, the parity must be fully resynchronized. The volume is
enabled and its state is set to RESYNC, and the RAID5 plex is
enabled. If usable RAID5 plexes are available, but contain
invalid data, they are zeroed. The parity is then resynchronized
by issuing VOL_R5_RESYNC ioctls for the entire length of the
volume. Once this is completed, the volume's state is set to
ACTIVE. Any usable RAID5 logs are enabled and set to the LOG
state.
If a volume requires full resynchronization (that is, has no
usable logs) and the RAID5 plex has stale or unusable subdisks,
the volume is unusable and the start operation fails. This can
be overridden by using the -f flag or the -o force option. In
this case, any stale subdisks are marked as non-stale and a full
resynchronization is performed; however, this may result in some
invalid data being introduced into the volume. If multiple sub‐
disks at the same altitude in the RAID5 plex are unusable (such
as because they have their NODEVICE flag set), the volume is
unusable and cannot be overridden.
Once any parity resynchronization has been completed, any sub‐
disks still marked as stale are recovered. This is done by mark‐
ing the subdisk as stale and write-only and issuing
VOL_R5_RECOVER ioctls to regenerate the data on the stale sub‐
disks. The subdisk is then marked as non-stale and read-write.
If the -o delayrecover option is specified, the only recoveries
that are performed are log replays. If the volume requires a
parity resynchronization, it is enabled and left in the NEEDSYNC
state, and its parity is marked as stale. No subdisk recoveries
are performed, and the stale subdisks are marked as stale.
Normally, if a volume has no RAID5 logs, it will not be enabled
with a stale subdisk or an unusable subdisk, because if the sys‐
tem crashed or the power failed while the volume was in use, the
parity could become stale and the volume would be unusable. This
behavior can be overridden by specifying the -o unsafe option,
which will cause the volume to be enabled during the above situ‐
ations. As the name suggests, this is considered unsafe because
doing so could cause data loss.
If only the -o delayrecover option is specified to start a vol‐
ume with a stale subdisk or an unusable subdisk, the start oper‐
ation faisl. In this case, the delayrecover option can be
ignored by also specifying the -o syncstartok option. Stopping
a raid5 volume disables the volume and its associated plexes. If
the volume is in the SYNC state, it is changed to the NEEDSYNC
state so that recovery will be performed at the next start. Any
invalid or detached RAID5 logs are set to the BADLOG state so
that they will not be used during the next start.
Normally, the stop operation fails if any extended operations
are using the volume or any of its plexes. Such operations are
detected as a non-empty value for the tutil0 field in a volume
or plex record. If the -f option is specified, the stop opera‐
tion ignores volume and plex tutil0 fields. The resync opera‐
tion examines the named volumes to see if they are enabled and
if the parity in any part of a volume is stale; this is normally
indicated by a volume state of NEEDSYNC. If so, the volume is
placed in the SYNC state and VOL_R5_RESYNC ioctls are issued to
resynchronize the parity in those regions. Upon completion, the
volume is placed in the ACTIVE state. The attributes that can
be set for raid5 volumes are: Changes the length of the volumes
specified to number sectors. The number parameter is a standard
Logical Storage Manager length specification (see volintro(8)).
Decreasing the length of a volume requires the -f option.
The volume length cannot be increased such that the RAID5 plex
is sparse with respect to the new volume length; this would make
the volume unusable.
To ensure that the new region of the volume is consistent, the
new region of the volume (from the old length to the new length)
is filled with zeros by issuing VOL_R5_ZERO ioctls before the
length is reset. Sets the size of the RAID5 log for the volume.
This cannot be set if the volume has no logs. If the length is
being increased, the operation will not be allowed if it would
cause any of the RAID5 log plexes to become sparse with respect
to the new length. Sets options that are applied to the volume
every time the volume is started, independently of options spec‐
ified with the volume start command. This is a set of comma-sep‐
arated options of the same form used with the -o option. Unrec‐
ognized or inappropriate options are ignored.
EXIT CODES
The volume utility exits with a nonzero status if the attempted opera‐
tion fails. A nonzero exit code is not a complete indicator of the
problems encountered, but rather denotes the first condition that pre‐
vented further execution of the utility.
See volintro(8) for a list of standard exit codes.
FILES
The utility that performs volume operations for a particular volume
usage type. The device node that can be used for mounting a file sys‐
tem created on the volume named volume in the disk group named group.
Volumes in group rootdg are also directly under the /dev/vol directory.
The device node that can be used for issuing raw I/O requests and also
for issuing ioctl requests to the volume named volume in disk group
named group. Volumes in group rootdg are also directly under the
/dev/rvol directory.
SEE ALSOvolintro(8), volassist(8), volinfo(8), volmend(8), volplex(8), volre‐
cover(8)volume(8)
