 |
Index for Section 8 |
|
 |
Alphabetical listing for V |
|
volplex(8)
NAME
volplex - Perform Logical Storage Manager (LSM) operations on plexes
SYNOPSIS
/sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] att volume
plex...
/sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] det
plex...
/sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] dis
plex...
/sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] cp volume
plex...
/sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] snapstart
volume plex
/sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] snapshot plex
newvolume
/sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] mv
oldplex newplex
OPTIONS
The following options are recognized:
-g diskgroup
Specify the disk group for the operation, either by disk group ID or by
disk group name. By default, the disk group is chosen based on the name
operands.
-U usetype
Limit the operation to apply to this usage type. Attempts to affect
volumes with a different usage type will fail.
-o useopt
Pass in usage-type-specific options to the operation. A certain set of
operations are expected to be implemented by all usage types:
slow[=iodelay]
Reduce the system performance impact of copy operations. Copy
operations are usually a set of short copy operations on small
regions of the volume (normally from 16 kilobytes to 128
kilobytes). 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; otherwise, a default is chosen (normally
250 milliseconds).
iosize=size
Perform copy 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.
rm Remove the plexes after successful completion of a volplex dis
operation. Remove the source plex after successful completion of
volplex mv.
-v volume
Require that the plex named by a plex or oldplex operand be associated
with the named volume. This option can be used as a sanity check, to
ensure that the specified plex is actually the plex desired for the
operation.
-V Write a list of utilities that would be called from volplex, along with
the arguments that would be passed. The -V performs a ``mock run'' so
the utilities are not actually called.
-f Force an operation that the Logical Storage Manager considers
potentially dangerous or of questionable use. This permits a limited
set of operations that would otherwise be disallowed. Some operations
may be disallowed even with this flag.
DESCRIPTION
The volplex utility performs Logical Storage Manager operations on plexes
and on volume-and-plex combinations. The first operand is a keyword that
determines the specific operation to perform. The remaining operands
specify the configuration objects 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 or plex 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 forced with -g diskgroup.
These are the recognized operation keywords:
att Attach each named plex to the named volume. This can be applied to
dissociated plexes, or to non-enabled plexes already associated with
the named volume. If the volume is enabled, then the result of the
successful operation will be to associate the plex (if needed) and to
recover the plex to have the same contents as all other attached plexes
in the volume. The rules for performing the attach depend upon the
usage type of the named volume.
Attaching a plex is the normal means of recovering a plex after a disk
replacement, or after a plex offline.
det Detach each of the named plexes. Detaching a plex leaves the plex
associated with its volume, but prevents normal volume I/O from being
directed to the plex. If the volume is enabled or detached, then the
plex will be accessible directly, through the plex device node in
/dev/plex/groupname/plex. This operation can be applied to plexes that
are enabled or disabled. The rules for performing the detach depend
upon the usage types of the volumes involved. The operation does not
apply to dissociated plexes.
Detaching a plex can be used as a simple means of backing up a volume
that is normally mirrored. With this type of procedure, the detached
plex (which represents a consistent image of the volume exactly at the
time of the detach) is backed up using the plex device, and is then
reattached when the backup operation completes. Some usage types will
perform special synchronization operations to help make the detached
plex consistent with respect to in-memory data, which can help improve
the quality of such backups.
dis Dissociate each of the named plexes. Dissociating a plex breaks the
link between the plex and its volume. A dissociated plex is
inaccessible until it is reassociated, which can be done either with
volplex att or with volmake. Any checks and synchronizations that apply
to the det operation also apply to the dis operation.
Plex dissociation is the normal means of unmirroring a volume, or
reducing the mirror count for a volume. To support this use, -o rm can
be used to dissociate and remove the plex (and its associated subdisks)
in the same operation. This makes the space used by those subdisks
usable for new allocations (such as with volassist or with volmake).
Plex dissociation can also be used for file system backups of volumes
that are normally mirrored. Plex devices are not directly mountable, so
the backup method described for the det operation will not work if the
backup program requires a mounted file system. To support such backup
programs, a plex can be dissociated and can then be allocated to a new
volume, such as with the command:
volmake -U gen vol volumeplex=plex
The created volume can then be started and mounted for use by the
backup program.
cp Copy the named volume to the named plexes. The volume cannot be
enabled, and the named plexes must not be associated. The results of
the operation will be a set of dissociated plexes that are an exact
copy of the volume at the time of completion of the operation. The
rules for performing the attach depend upon the usage type of the named
volume. To improve the quality of the copies, some usage types attempt
to make the detached plex consistent with respect to in-memory data.
This operation can be used to make a copy of a volume, for backup
purposes, without mirroring the volume in advance.
snapstart and snapshot
These two operations form the two parts of a preferred means of copying
a volume to a plex for backup purposes. The snapstart operation
attaches a plex to a volume and, when the operation is complete, leaves
the plex associated as a temporary plex. After the operation completes,
the administrator can convert the plex attached by snapstart into a new
volume using volplex snapshot. To improve the quality of the copies,
some usage types attempt to make the detached plex consistent with
respect to in-memory data.
This method of backup is preferable to using volplex cp because it
allows the administrator to coordinate breaking off the plex from the
original volume at a well-defined point in time. This is important,
since attaching a plex to a volume can take a considerable amount of
time, and it is difficult to know when it will complete. Also, direct
conversion of the plex into a new volume is more convenient than
requiring additional steps.
mv Attach the plex newplex to the volume that oldplex is associated with
and dissociate oldplex. The volume cannot be disabled, and newplex must
name a dissociated plex. The operation ensures seamless replacement of
the dissociated plex without loss of data in the volume and without
significant delays in volume accessibility.
A primary purpose for the plex move operation is to move a plex that is
using a disk to another location. In support of this purpose for the
operation, -o rm can be specified to remove the original plex after
completion of the operation.
For concatenated plexes, the volsd mv operation can be used to move
subdisks off a disk, instead. However, moving subdisks for a striped
plex off a disk requires moving the entire plex. The rules for
performing the move depend upon the usage types of the volume to which
oldplex is associated.
FSGEN AND GEN USAGE-TYPES
The fsgen and gen usage types provide similar, though not identical,
semantics for all operations of the volplex utility. In particular, the
fsgen usage type will attempt to flush in-memory data cached for the file
system residing on the volume. For most file systems, this consists of
calling sync(8) to attempt to flush all in-memory data to disk.
If a volplex operation is interrupted by a signal, then an attempt is made
to restore the disk group configuration to a state that is roughly
equivalent to its original state. If this attempt is interrupted (such as
through another signal) then the user may need to perform some cleanup.
The specific cleanup actions that are needed are written to the standard
error before volplex exits.
The fsgen and gen usage types provide the following options as arguments to
-o in addition to the required options:
force
Force an operation that the Logical Storage Manager considered
potentially dangerous or of questionable use. This applies to attempts
to detach or dissociate the last (complete) plex in a volume, or to
attempts to move a plex to a plex that has a different size. This flag
is the same as -f.
rerr
Ignore volume or plex read errors when copying data onto a plex. A
warning message is written to standard error if a read error occurs,
but the error does not affect success of the operation. This operation
can be used only with the cp operation; the operation is ignored if
used with other operations.
werr
Ignore plex write errors when copying data onto a plex. A warning
message is written to standard error if a write error occurs, but the
error does not affect success of the operation. This operation can be
used only with the cp operation; the operation is ignored if used with
other operations.
mapzero
If a plex is moved to a new plex that has regions that are mapped to a
subdisk in the destination, but are not mapped to a subdisk for any
enabled, readable plex in the volume, then zero out that mapped region
in the destination plex. Without this flag, the mapped region may be
left unchanged from its original contents.
Limitations and extensions for the fsgen and gen usage types consist of
the following:
att If the volume is enabled and one of the named plexes is associated with
the volume, then the plex must be STALE, EMPTY, ACTIVE, or OFFLINE. If
the operation succeeds in attaching a plex, then any I/O fail condition
for the plex is cleared. Also, attaching to an enabled volume requires
that the volume have at least one enabled, read-write plex.
If the volume is not enabled, then the named plexes are associated with
the volume (if not already associated) and are set to the STALE state,
so that the plex will be fully attached by the next volume start or
volume startall operation that applies to the volume.
If the logging type of the volume is UNDEF and an unassociated plex
with a logging subdisk is attached, the volume is automatically
converted to have a logging type of BLKNO. Logging of volume changes is
enabled when two or more attached plexes have associated log subdisks.
An attempt to attach an unassociated plex fails if the putil0 field is
not empty. This makes it possible to prevent use of a plex by using
voledit set to set the putil0 field to a non-empty string. The putil0
field can then be cleared with either voledit set or with volmend clear
putil0.
dis and det
A detach or dissociate of a plex in an enabled volume fails if applied
to a plex that is the last complete, enabled, read-write plex in the
volume and the volume contains two or more non-complete, enabled,
read-write plexes. In other words, a volume cannot be left with two
enabled, non-complete plexes. A complete plex is one that is at least
as long as the volume, and has subdisks mapped to the plex for all
blocks up to the length of the volume. The -f option is required to
reduce a volume to containing one enabled, read-write, non-complete
plex, or to having no enabled, read-write plexes at all.
The det operation changes the state for an ACTIVE or CLEAN plex to
STALE. The next time the volume is started, the plex will be re-
attached automatically.
cp The fsgen and gen usage types do not add any specific restrictions to
the cp operation.
mv If the destination plex has unmapped regions (a range of blocks in the
plex with no backing subdisk) that are not mapped in the source plex,
or if the destination plex is shorter than the source plex, then the -f
option is required. Even with -f, the operation will prevent the plex
from being sparsed such that the volume would be left with two or more
sparse, enabled, read-write plexes, but no complete plexes.
EXIT CODES
The volplex 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/volplex
The utility that performs volmend operations for a particular volume
usage type.
/dev/plex
Directory containing plex devices. Plex devices for the rootdg disk
group are directly under /dev/plex. Plex devices for all disk groups
(including duplicate entries for rootdg) are under subdirectories named
after the disk group.
/etc/vol/type/fsgen/fs/fstype/volsync
Path to a program used with the fsgen usage type for synchronizing in-
memory file system data with a volume, for the file system type fstype.
The program is given arguments of a volume name and one or more plex
names. For the ufs file system types, this is a link to sync.
SEE ALSO
sync(8), volintro(8), volassist(8), voledit(8), volmend(8), volume(8)