 |
Index for
Section 8 |
|
 |
Alphabetical
listing for V |
|
 |
Bottom of
page |
|
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:
-g diskgroup
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.
-U usetype
Forces the operation to be performed by the usage-type utility for this
usage type.
-V 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.
-f 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.
-o useopt
Passes in usage-type-specific options to the operation.
The following -o options apply to all usage types:
bg 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.
force
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.
plexfork[=count]
Performs up to the specified number of plex recovery operations
simultaneously. If no count is specified, a suitable small number
is used (normally 10).
delayrecover
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 read-writeback (NEEDSYNC) recover state that performs
limited plex recovery for each read to the volume.
slow[=iodelay]
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).
iosize=size
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.
verbose
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:
norecov
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:
checkpt=size
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.
delayrecover
Prevents the start operation from undergoing some recovery
operations. Any valid RAID5 logs are replayed; however, no parity
resynchronizations or subdisk recoveries are performed.
unsafe
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.
syncstartok
Allows the delayrecover 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 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:
init
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.
rdpol
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:
round
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.
prefer
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.
select
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.
start
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.
startall
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.
stop
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 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.
stopall
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.
resync
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.
recover
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.
maint
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.
set 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
Limitations and extensions for the fsgen and gen usage types consist of the
following:
init
The fsgen and gen usage types recognize the following init_type
operands for the volume init operation:
clean volume [plex]
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.
active 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.
enable volume
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.
zero volume
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.
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, 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.
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, 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.
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 set for fsgen and gen volumes are:
len=number
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.
logtype=type
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.
loglen=size
Sets the size for logs used with the volume. The size value is a
standard Logical Storage Manager length number (see volintro(8)).
fpa=off
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.
startopts=volume_options
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.
resync
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.
RAID5 USAGE TYPE
Limitations and extensions for the raid5 usage type consist of the
following:
init
The raid5 usage type recognizes the following init_type operands for
the volume init operation:
active volume
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.
zero volume
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.
start
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 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
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.
stop
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.
resync
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.
set The attributes that can be set for raid5 volumes are:
len=number
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.
loglen=size
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.
startopts=volume_options
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
/sbin/lsm.d/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.
SEE ALSO
volintro(8), volassist(8), volinfo(8), volmend(8), volplex(8),
volrecover(8)
|
Index for
Section 8 |
|
|
Alphabetical
listing for V |
|
 |
Top of
page |
|