Content-type: text/html
Man page of volume
volume
Section: Maintenance Commands (8)
Index
Return to Main Contents
NAME
volume - Perform Logical Storage Manager (LSM) 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...
OPTIONS
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
voldg(8)
for more
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
-V
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,
-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.
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
count
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
iodelay
as a number of milliseconds, or else a default is chosen
(normally 250 milliseconds).
Perform recovery operations in regions with the length specified
by
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.
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:
Perform 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.
Set the read policy for a volume based on the
policy
operand. These are the recognized read policies:
Use 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.
Read preferentially from the plex named by the
plex
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.
The
plex
operand is required for the
prefer
read-policy type.
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
plex
operand
should be specified for the
select
read-policy type.
Enable 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 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
-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 contents can be restored
from backup or reinitialized.
Attempt to start all volumes that are disabled. If a
-U
usetype
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
rootdg
disk group. A different disk group can be specified with
the
-g
option.
Disable 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 convention,
-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.
Attempt to stop all volumes that are enabled. If a
-o
usetype
option is specified, then attempt
to stop all disabled volumes with the indicated usage type. By default, stop
all volumes in the
rootdg
disk group. A different disk
group can be specified with the
-g
option.
Examine all volumes named by the
volume
operands. 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.
Detach each volume named by the
volume
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
the
fsck
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
set
keyword
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=value
attribute arguments that are recognized depends upon the
volume usage-type. However, 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)).
FSGEN AND GEN USAGE TYPES
The
fsgen
and
gen
usage types
provide the same semantics for all operations of the
volume
utility. However, some options are provided only by the
gen
usage type.
In addition to the standard
-o
options required for
all usage types, the
fsgen
and
gen
usage
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
-f.
This can only be used with the
gen
usage
type. Prevent 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 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.
Limitations and extensions for the
fsgen
and
gen
usage types consist of the following:
These are the recognized uses of the
volume init
operation:
Set the state for the specified plex to
CLEAN,
and set 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, then the
plex
argument is not required as it defaults to that plex. If specified,
then the
plex
argument must represent a plex that
is associated with the volume.
Set the state for all plexes associated with
volume
to
ACTIVE
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,
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.
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
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, 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
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, then
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 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 block change log 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,
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
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 (in
the background with the
-o bg
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
plexfork.
-
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
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, set the state for the
plex to
STALE. If all plexes are set to
STALE, then 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, i.e., one of the subdisks in the
plex is defined on a disk with the volatile attribute (see
voldisk(8)),
then set the plex state to
STALE.
If the volume is enabled and the plex is also enabled, then
set the plex state to
CLEAN.
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
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, then
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.
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:
Change the length of each volume specified by the
volume
operands to be
number
sectors.
The
number
is a standard Logical Storage Manager
length number (see
volintro(8)). Decreasing the length of a volume requires
-f.
-
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
-f
option.
-
If the volume is not enabled, count the number of
CLEAN
and
ACTIVE
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
-f.
-
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
SYNC
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
ACTIVE
state.
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
ACTIVE
plexes. Allowed log types are
blkno
(logs
the blocks involved in all volume writes),
none
(never
does logging), and
undef
(never does logging). If the
logging type is set to
undef, then a future
volsd
aslog
or
volplex att
operation will change it
to
blkno. See the
fsgen
and
gen
sections of
volsd(8)
and
volplex(8)
for more
information.
Set the size for logs used with the volume. If the logging
type is
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
volintro(8)).
Set 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 letter. At the present
time, only the
noattach
and
verbose
options can be applied to volumes in this manner. 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 system
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.
The device node for accessing a plex named
plex
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
rootdg
are also directly under the
/dev/plex
directory.
SEE ALSO
volintro(8),
volassist(8),
volinfo(8),
volmend(8),
volplex(8),
volrecover(8)
Index
- NAME
-
- SYNOPSIS
-
- OPTIONS
-
- DESCRIPTION
-
- FSGEN AND GEN USAGE TYPES
-
- EXIT CODES
-
- FILES
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 02:40:37 GMT, October 02, 2010