volume(8) System Manager's Manual volume(8)
NAME
volume - 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 volume...
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] startall
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] stop volume...
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] stopall
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] resync volume...
/sbin/volume [-Vf] [-g diskgroup] [-U usetype] [-o useopt] maint volume...
/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, the -f may be used to reduce the length of a volume with volume set, to stop a volume 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 revive 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 will be
usable immediately after the operation completes, although recovery operations may affect performance of the volume 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 revive operations simul-
taneously. If no count is specified, a suitable small number is used (normally 10). Does not perform any plex revive 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 performance impact of plex recovery operations and volume length changes. Startup recovery and length change con-
sistency operations 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. A specific delay can be specified with iodelay as a number of millisec-
onds, or else a default is chosen (normally 250 milliseconds). 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 com-
plete sooner, but with greater impact on other processes using the volume. The default I/O size is typically 256KB. Prints a mes-
sage for each volume that is successfully 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 vol-
plex utility. Instead, all STALE and ACTIVE plexes are simply treated as equivalent to CLEAN plexes, and are thus enabled without
being made consistent. This can be used for volumes whose contents are recreated for each use.
An example of a possible use for this attribute is a swap area and the /tmp file system. In the case of /tmp, the model assumes that
newfs is used to create an empty file system after the volume has been started.
The raid5 usage type supports the following additional -o options: Sets the checkpoint size for a volume. A complete resynchroniza-
tion of a volume via VOL_R5_RESYNC ioctls can take an extended amount of 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 will
still be replayed; however, no parity resynchronizations or subdisk recoveries will be 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 failure. Allows the delayre-
cover 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 volumes. The first operand is a keyword that determines the specific
operation to perform. The remaining operands specify configuration records 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 volume operands will be
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: Performs an initialization action on 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 uninitialized state with volmend fix empty. The
action to perform is specified by the init_type operand, which is usage-type-dependent. The volume operand 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. 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 operand. 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 op-
erand is required for the prefer read-policy 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 vol-
umes 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 initializa-
tion will be 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, the -f
option can be used to try to start the volume, anyway. This can be used after replacing disks to enable the volume so that its con-
tents 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 disabled volumes with
the indicated usage type. This operation will not 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 manner.
The specific method for cleanly stopping a volume, and the precise meaning of "clean" are both highly usage-type-dependent. By con-
vention, -f can be used to force stopping of a volume that is in use, forcing I/O failures to be returned for any further volume
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 disabled 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 operation 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.
The recover operation can be used 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 successful 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 operands. When
a volume is detached, normal read and write operations 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 specific volume
characteristics. The changes to be made are given by arguments immediately after the set keyword of the form attribute=value. The
set of volumes affected by the operation is given after these operands; thus the attribute list ends with an operand that does not
contain an equal sign.
To allow for volume names that contain an equal sign, an operand of -- can be used 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 expected to be 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 sections
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 follow-
ing 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 volume. 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 com-
plete 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 vol-
ume. 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 example, 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 imme-
diately set to the ACTIVE state; otherwise, the volume is set to the SYNC state and a special read/write-back mode is set to recover
regions of the volume on every read operation. The volume is then 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 purposes of start-
ing 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 opera-
tions 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 operations
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) will be changed to ACTIVE. The volume will then be started
and synchronized from those plexes. Stopping an fsgen or gen volume disables the volume and its associated plexes. In addition, the
utility state for each ACTIVE plex is changed as follows: 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 opera-
tional 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 operations
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 given to force the stopping of 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 will be re-synchronized to contain consistent data.
Any such volumes that are in the NEEDSYNC state will be 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. 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 changed are: Changes the length of each volume
specified by the volume operands to number sectors. The number parameter is a standard Logical 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 volplex 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 Logical Storage Manager length number
(see volintro(8)). 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. At the present
time, 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 will be
resynchronized to contain consistent data. Any such volumes that are in the NEEDSYNC state will be 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 following: 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 volume. 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. Starting 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 com-
pleted, 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 will fail. 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 subdisks 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 subdisks still marked as stale are recovered. This is done by marking the
subdisk as stale and write-only and issuing VOL_R5_RECOVER ioctls to regenerate the data on the stale subdisks. The subdisk is then
marked as non-stale and read-write.
If the -o delayrecover option is specified, the only recoveries that will be 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. Any subdisk recoveries
that are needed are not 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 system
crashed or the power failed while the volume was in use, the parity could become stale and the volume would be unusable. This behav-
ior can be overridden by specifying the -o unsafe option, which will cause the volume to be enabled during the above situations. 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 volume with a stale subdisk or an unusable subdisk, the start operation
will fail. In this case, the delayrecover option can be ignored by also specifying the -o syncstartok option. Stopping a raid5 vol-
ume 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 will fail 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 operation
ignores volume and plex tutil0 fields. The resync operation 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 be number sec-
tors. 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 specified with the volume start command. This is a set of comma-separated options of the
same form used with the -o option. Unrecognized or inappropriate options are ignored.
EXIT CODES
The volume 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 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 direc-
tory. 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 ALSO
volintro(8), volassist(8), volinfo(8), volmend(8), volplex(8), volrecover(8)
volume(8)