volume - Performs Logical Storage Manager 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 additional volume operation applies only to
the raid5 usage type: /sbin/volume [-Vf] [-g diskgroup]
[-U usetype] [-o useopt] recover volume [subdisk]...
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 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 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 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 recovery operations
simultaneously. If no count is specified, 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 readwriteback
(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 consistency
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. You can set the delay
(in milliseconds), or use the default (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 complete sooner, but with greater
impact on other processes using the volume. The
default I/O size is typically 256KB. Prints a message
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 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 volume 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 resynchronizations 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 failure. Allows
the delayrecover option to be ignored if the volume
must undergo parity resynchronizations or subdisk
recoveries before the volume can be enabled.
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 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 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. (This keyword
is not supported for the raid5 usage type.) These
are the recognized read policies: Uses a roundrobin
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 operand 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 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 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
disabled 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 manner. The specific method
for cleanly stopping a volume, and the precise
meaning of "clean" are both highly usage-typedependent.
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 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.
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 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 volume characteristics 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 sections FSGEN AND GEN
USAGE TYPES and RAID5 USAGE TYPE for details.
FSGEN AND GEN USAGE TYPES [Toc] [Back] 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 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 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 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 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 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,
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 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) 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 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 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 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 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 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 set for
fsgen and gen volumes 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)). 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 primary 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 resynchronized
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.
Limitations and extensions for the raid5 usage type consist
of the following: The raid5 usage type recognizes the
following init_type operands 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 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 nonstale
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 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 system 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 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 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
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 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 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.
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.
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.
volintro(8), volassist(8), volinfo(8), volmend(8), volplex(8), volrecover(8)
volume(8)
[ Back ] |
