Man page of volume
Section: Maintenance Commands (8)
Return to Main Contents
volume - Perform Logical Storage Manager (LSM) operations on volumes
/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 options are recognized:
Specify the disk group for the operation. The disk group
can be specified either by name or by disk group ID. See
information on disk groups.
Force the operation to be performed by the usage-type utility
for this usage type. B
Write a list of utilities that would be called from
volume, along with the arguments that would be passed. The
option performs a ``mock run'' so the utilities are not actually
called, and no changes are made to the volume configuration database.
Force an operation in some situations where the operation
has questionable semantics. For example,
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.
Pass in usage-type-specific options to the operation. By
convention, the following usage-type-specific options should be implemented
by all usage types:
Perform 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.
Perform up to the specified number of plex revive operations
simultaneously. If no
is specified, then
a suitable small number is used (normally 10).
Do not perform any plex revive operations when starting a
volume. Simply enable 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.
Reduce the system performance impact of plex recovery operations
and volume length changes. Startup recovery and length change consistency
operations are usually a set of short operations on small regions of the volume
(normally from 16K bytes to 128K bytes). This option inserts a delay between
the recovery of each such region. A specific delay can be specified with
as a number of milliseconds, or else a default is chosen
(normally 250 milliseconds).
Perform recovery operations in regions with the length specified
size, which is a standard Logical Storage Manager
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 32 kilobytes.
Print a message for each volume that is successfully started.
Without this option, messages appear only for volumes that fail to start.
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
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
The recognized operation keywords are:
Perform an initialization action on a volume. This can be
applied to volumes that were created by
have not yet been initialized, or volumes that have been set to the uninitialized
volmend fix empty. The action to perform is
specified by the
operand, which is usage-type-dependent.
operand determines which usage type
to use for performing the operation.
Set the read policy for a volume based on the
operand. These are the recognized read policies:
Use a round-robin read order among the enabled, readable plexes
associated with the volume. No
be specified for the
Read preferentially from the plex named by the
operand. If the plex is enabled, readable, and associated
with the volume, then 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.
operand is required for the
Select 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
should be specified for the
Enable disabled or detached volumes named by the
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.
operation is applied to an uninitialized
volume (for example, a volume just created by
a default initialization will be used to initialize and enable the volume.
If the volume is not normally started because failures and disk removals
have left all associated plexes with invalid data, the
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 contents can be restored
from backup or reinitialized.
Attempt to start all volumes that are disabled. If a
option is specified, then attempt
to start all disabled volumes with the indicated usage type. This operation
will not start uninitialized volumes. By default, start all volumes in the
disk group. A different disk group can be specified with
Disable the enabled or detached volumes named by the
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 convention,
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.
Attempt to stop all volumes that are enabled. If a
option is specified, then attempt
to stop all disabled volumes with the indicated usage type. By default, stop
all volumes in the
disk group. A different disk
group can be specified with the
Examine all volumes named by the
operands. Volumes that have possibly differing plex contents will be re-synchronized
to contain consistent data. Any such volumes that are in the
state will be recovered using a read/write-back recovery mode and
then put into the
Plexes in the
state may already be under recovery
and the volume command will take no action to recover them unless the command
was invoked with the
Detach each volume named by the
operands and make the plex devices associated with those volumes accessible
to regular system utilities. When a volume is detached, normal read and write
operations to the volume fail, although most volume ioctl operations can still
be used. Normal reads and writes can be used on the plex devices for the
associated plexes. This operation could be used, for example, before using
utility to decide which of several associated
plexes should be used for reviving other plexes in a volume.
Change specific volume characteristics. The changes to be
made are given by arguments immediately after the
of the form
attribute=value. The set of volumes affected by the operation are 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.
The set of
attribute arguments that are recognized depends upon the
volume usage-type. However, an attribute argument of the form
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
value is interpreted
as a standard length number (see
FSGEN AND GEN USAGE TYPES
provide the same semantics for all operations of the
utility. However, some options are provided only by the
In addition to the standard
options required for
all usage types, the
types provide the following additional options:
Force 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
This can only be used with the
type. Prevent the
operation from recovering plexes
utility. Instead, all
plexes are simply treated as equivalent
plexes, and are thus enabled without being made
consistent. This can be used for volumes whose contents are recreated for
An example of a possible use for this attribute is a swap area and the
file system. In the case of
/tmp, the model
is used to create an empty file system
after the volume has been started.
Limitations and extensions for the
usage types consist of the following:
These are the recognized uses of the
Set the state for the specified plex to
and set all other plexes to
operation can then be used to recover the volume from the
plex. This operation requires that the volume not be enabled.
If the specified volume has only one plex, then the
argument is not required as it defaults to that plex. If specified,
argument must represent a plex that
is associated with the volume.
Set the state for all plexes associated with
and enable 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.
Enable the volume and its plexes but leave 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,
should be used
to fully enable the volume.
could be used,
for example, if a complete image of the volume is to be loaded from a tape.
Write 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
and the volume and its plexes are enabled.
could be used, for example,
to put a file system on
If this operation is interrupted by a signal, then 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, then the user many need to perform some cleanup.
A set of commands to perform this cleanup are written to the standard error
Starting an uninitialized
volume enables the volume and its plexes, sets the plexes
state, and recovers the plexes to ensure
that each plex has the same contents. If the volume has only one plex, then
the volume is immediately set to the
the volume is set to the
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
Starting a volume with no active block change log involves enabling
plexes and putting
them in the
state. If an I/O failure was logged
against the plex, or if a disk replacement caused a plex to become stale,
then the plex is considered
STALE. If any of the subdisks
for the plex reside on a removed or inaccessible disk, then the plex is ignored
for the purposes of starting the volume.
If two or more plexes were enabled, and if the volume was active at
the time the system went down, then the state for the volume is set to
and a special read/write-back recovery mode is used to recover
consistency of the volume, segment-by-segment, on every read. A process (in
the background with the
option) to recover consistency
for the entire length of the volume is then started.
If any plexes were considered
STALE, then those plexes
are attached by calling
volplex att. The number of concurrent
plex attach operations are limited based on the rules for-o
Recovery of plexes with a block change log uses the same rules as for
volumes without a valid block change log, except that recovery of non-stale
plexes is done in the foreground before the volume can be used, by scanning
the contents of the block change log and recovering consistency for those
blocks 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
are also removed.
If the volume is unstartable because there are no valid, non-stale plexes
flag is then specified, all
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.
volume disables the volume and its associated plexes. In addition, the utility
state for each
plex is changed as follows:
If the plex is detached or disabled, set the state for the
STALE. If all plexes are set to
STALE, then the volume cannot be started until
is used to change the state of one or more plexes to
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
If the plex is volatile, i.e., one of the subdisks in the
plex is defined on a disk with the volatile attribute (see
then set the plex state to
If the volume is enabled and the plex is also enabled, then
set the plex state to
If the volume is detached and the plex is enabled, then the
plex state is left as
ACTIVE. A volume can be left detached,
with remaining valid plexes, only as a result of calling
to detach an enabled volume.
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
a volume or plex record. If the
option is specified, then
operation ignores volume and plex
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
operation is not otherwise affected. Stopping an open or mounted volume is
not normally advisable.
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:
Change the length of each volume specified by the
operands to be
is a standard Logical Storage Manager
length number (see
volintro(8)). Decreasing the length of a volume requires
If the volume is enabled, then count the number of enabled, read-write
plexes that would remain complete after the length change. 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
If the volume is not enabled, count the number of
plexes that would remain complete after the
length change, then use the algorithm mentioned above for determining whether
the operation is allowed or requires use of
In order to ensure that the new region of the volume is consistent across
all plexes of the volume, the volume is put into a
state and read/write-back mode, and a read loop is now performed against the
volume. Once this loop has completed, the volume is put back into the
Set 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
plexes. Allowed log types are
the blocks involved in all volume writes),
does logging), and
(never does logging). If the
logging type is set to
undef, then a future
operation will change it
blkno. See the
Set the size for logs used with the volume. If the logging
blkno, then this value must be 1 sector. Future
logging types may allow larger log sizes. The size value is a standard Logical
Storage Manager length number (see
Set options that are applied to the volume every time the
volume is started, independently of options specified with the
command. This is a set of comma-separated options of the
same form used with the
option letter. At the present
time, only the
options can be applied to volumes in this manner. Unrecognized or inappropriate
options are ignored.
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.
for a list of standard exit codes.
The utility that performs
for a particular volume usage type.
The device node that can be used for mounting a file system
created on the volume named
in the disk
group. Volumes in group
are also directly under the
The device node that can be used for issuing raw I/O requests
and also for issuing ioctl requests to the volume named
in disk group named
are also directly under the
The device node for accessing a plex named
in disk group named
group. A plex
device is accessible only if it is not disabled and if it is associated with
a volume that is not disabled. Plexes in group
are also directly under the
- FSGEN AND GEN USAGE TYPES
- EXIT CODES
- SEE ALSO
This document was created by
using the manual pages.
Time: 02:40:37 GMT, October 02, 2010