 |
Index for Section 8 |
|
 |
Alphabetical listing for V |
|
volume(8)
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:
-g diskgroup
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.
-U usetype
Force the operation to be performed by the usage-type utility for this
usage type. B
-V 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.
-f 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.
-o useopt
Pass in usage-type-specific options to the operation. By convention,
the following usage-type-specific options should be implemented by all
usage types:
bg 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.
plexfork[=count]
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).
noattach
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.
slow[=iodelay]
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).
iosize=size
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.
verbose
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:
init
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.
rdpol
Set the read policy for a volume based on the policy operand. These are
the recognized read policies:
round
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.
prefer
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
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.
start
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.
startall
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.
stop
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.
stopall
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.
resync
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.
maint
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.
set 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
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.
norecov
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:
init
These are the recognized uses of the volume init operation:
volume init clean volume [ plex ]
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.
volume init active 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.
volume init enable volume
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.
volume init zero volume
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.
start
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.
stop
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.
maint
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.
set The attributes that can be changed are:
len=number
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.
logtype=type
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.
loglen=size
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)).
startopts=volume_options
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
/etc/vol/type/usetype/volume
The utility that performs volume operations for a particular volume
usage type.
/dev/vol/group/volume
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.
/dev/rvol/group/volume
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.
/dev/plex/group/plex
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)