volplex - Perform Logical Storage Manager operations on
plexes
/sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o
useopt] att volume plex...
/sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o
useopt] cp 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] [-v volume] mv oldplex newplex
/sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o
useopt] snapstart volume plex
/sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o
useopt] snapshot plex newvolume
Specifies 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. Limits the operation
to apply to this usage type. Attempts to affect volumes
with a different usage type will fail. Passes in
usage-type-specific options to the operation. The following
operations are implemented by all usage types: Reduces
the system performance impact of copy operations. Copy
operations are usually performed in series on small
regions of the volume (normally from 16 kilobytes to 256
kilobytes). This option inserts a delay between the recovery
of each such region. You can specify a delay in milliseconds
or use the default (normally 250 milliseconds).
Changes the copy region size to 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 256 kilobytes. Removes the plexes
after successful completion of a plex dissociation operation.
Removes the source plex after successful completion
of a plex move operation. Requires that the plex named by
a plex or oldplex operand be associated with the named
volume. Use this option as a sanity check, to ensure that
the specified plex is actually the plex desired for the
operation. Displays a list of utilities that would be
called from volplex, along with the arguments that would
be passed. The -V option performs a "mock run" so the
utilities are not actually called. Forces 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.
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). To specify a disk group,
use the -g diskgroup option.
These are the recognized operation keywords: Attaches each
named plex to the named volume. You can attach dissociated
plexes or 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 placing a
plex offline. Copies the named volume to the named
plexes. The volume cannot be disabled, and the
named plexes must not already be associated to any
volume. The result of the operation is 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 copy 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.
Use this operation to make a copy of a volume for
backup purposes, without mirroring the volume in
advance. Detaches each of the named plexes.
Detaching a plex preserves its association with the
volume, but prevents normal volume I/O from being
directed to the plex. You can detach plexes that
are enabled or disabled. The rules for performing
the detach depend upon the usage types of the volumes
involved. You cannot detach a dissociated
plex. Dissociates 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, 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 purpose, use the -o rm
option 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. To
support backup programs that require a mounted file
system, you can dissociate a plex and then allocate
the plex to a new volume, as follows:
volmake -U gen vol volume plex=plex
You can then start and mount the new volume for the
backup program to use.
Note
You cannot use this backup procedure for AdvFS.
Attaches the plex newplex to the volume that oldplex
is associated with and dissociates oldplex.
The volume cannot be disabled, and newplex must
name a dissociated plex. The operation ensures
seamless replacement of the old 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,
use the -o rm option to remove the original plex
after completion of the operation. 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, you 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 you 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, directly converting
the plex into a new volume is more convenient
than requiring additional steps.
FSGEN AND GEN USAGE TYPES [Toc] [Back] 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 a file system residing
on the volume. For most file systems, this consists of
calling sync to attempt to flush all in-memory data to
disk.
If a volplex operation is interrupted by a signal, 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 you may need to perform some cleanup. The
specific cleanup actions 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: Forces an operation that the Logical Storage Manager
considers potentially dangerous or of questionable
use. This option is required to detach or dissociate the
last (complete) plex in a volume, to detach or dissociate
an FPA log plex from a primary volume (thereby disabling
FPA logging for the volume), or to move a plex to a plex
of a different size. -o force is the same as -f. Ignores
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. Ignores 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. If you move or copy a
sparse plex (one that has no subdisk behind one or more
regions of the plex) to a new plex that does have subdisks
behind the corresponding sparse regions of the source
plex, this flag zeroes out that mapped region in the destination
plex. Without this flag, the mapped region may be
left unchanged from its original contents. Used with det
to create and attach an FPA logging subdisk (if none
exists) to the named plex and detach the plex from a primary
volume. This option does not apply to detaching or
dissociating a migrant plex from a secondary volume.
Limitations and extensions for the fsgen and gen usage
types consist of the following: 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 log type of the volume is UNDEF and an unassociated
plex with a log subdisk is attached, the
volume is automatically converted to have a log
type of REGION. Volume DRL logging is enabled when
the volume has at least one enabled, associated
plex with an enabled log subdisk and at least two
read-write mode plexes.
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.
To manually create a secondary volume from several
plexes including a migrant plex (a plex detached
from a primary volume), specify the migrant plex
first on the command line (or in a separate
attributes file as input to the volplex att command).
Or create the volume from only the migrant
plex, and then add the other plexes to the volume
in a separate operation. Either of these methods
ensures that FPA logging will be properly enabled
for the volume. The fsgen and gen usage types do
not add any specific restrictions to the cp operation.
Detaching or dissociating a plex in an
enabled volume fails if applied to the last complete,
enabled, read-write plex in the volume and
the volume contains two or more sparse, enabled,
read-write plexes. In other words, a volume cannot
be left with two enabled, sparse 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 remove plexes from a volume such that
it is left with only one enabled, read-write,
sparse plex, or with 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 reattached automatically.
Use the det keyword to detach a migrant plex from a
secondary volume and preserve the FPA log, in
preparation for returning the migrant plex to the
primary volume.
Use volplex det and then volplex dis to dissociate
a migrant plex from a secondary volume and preserve
the FPA log.
Note
The recommended method of managing FPA operations
is through the volassist snapfast and snapback command
keywords.
Use the force option (-f) to remove the last
enabled, complete, read-write plex from a volume,
or to dissociate (with dis) a migrant plex from a
secondary volume, or the FPA log plex from a primary
volume. This disables FPA logging for the
specified volume. If the migrant plex is reattached
to the primary volume, a full resynchronization of
the data occurs and the FPA log is not used,
defeating the purpose of the FPA log.
A migrant plex that is detached or dissociated from
a secondary volume should only be attached to its
original (primary) volume. If either the source or
destination plex (or both) is sparse, the sparse
regions must align (must both occur in the same
respective block addresses within the plexes). If
they do not, or if the destination plex is shorter
than the source plex, 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.
The raid5 usage type provides the following options as
arguments to -o in addition to the required options:
Forces an operation that the Logical Storage Manager considers
potentially dangerous or of questionable use. This
applies to attempts to dissociate the RAID 5 data plex of
a non-EMPTY volume or to remove the last RAID 5 log plex
of a non-EMPTY volume. This flag is the same as -f.
As with other usage types, if a volplex operation is
interrupted by a signal, 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 you may need
to perform some cleanup. The specific cleanup actions
needed are written to the standard error before volplex
exits.
The raid5 usage type supports only the following keywords:
Attaches the named plexes to the named volume. If a plex
has a layout of raid5, the plex will be attached as the
RAID 5 data plex of the volume. To attach a RAID 5 plex to
the volume, the volume must be disabled and be in the
EMPTY state, and the RAID 5 plex will be given a state of
EMPTY. Only one RAID 5 data plex can be attached to a RAID
5 volume.
If a plex has a layout other than raid5, the plex
will be attached as a RAID 5 log plex for the volume.
If the volume has no RAID 5 log plexes, the
log length for the volume will be set to the length
of the smallest log plex being attached. If the
volume already has at least one log plex, another
log plex can be attached only if it is at least as
long as the shortest log plex already attached to
the volume. RAID 5 log plexes cannot be sparse in
respect to the volume's log length; attempts to
attach a sparse log plex will fail.
If the RAID 5 volume is not enabled, log plexes are
attached and marked as STALE. If the RAID 5 volume
is enabled and has no log plexes, attaching a log
plex will cause plexes being attached as log plexes
to be zeroed before they are enabled. Otherwise,
the new log plexes are attached write-only and the
contents of the existing log plexes are copied to
the new log plexes using ATOMIC_COPY ioctls, after
which the logs are enabled. Dissociates the named
plex from the RAID 5 volume to which it is
attached. If the plex is the RAID 5 data plex of
the volume and the volume is not EMPTY, this
requires the -o force option, as any data on the
volume would be lost. If the plex is a log plex for
the volume and will leave the RAID 5 volume with no
usable log plexes, the -o force option is required.
Note that the RAID 5 usage type does not support the det,
cp, mv, snapstart, or snapshot keywords; these operations
are either inappropriate or impossible to perform within
the operational concepts of RAID 5.
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.
The following example shows how to create a secondary volume
(called myvol_backup) using a plex (myvol-02) from an
existing volume (called myvol), with FPA logging. The
existing volume is known as the primary volume while FPA
logging is in effect: Detach a plex from the volume and
enable FPA logging on both the primary volume and the
migrant plex: volplex -o fpa det myvol-02 Dissociate the
migrant plex from the primary volume: volplex dis myvol-02
Create a secondary volume: volmake vol myvol_backup Attach
the migrant data plex to the secondary volume: volplex att
myvol_backup myvol-02 Start the secondary volume: volume
start myvol_backup
The utility that performs volplex operations for a particular
volume usage type. 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 and AdvFS file system types,
this is a link to sync.
Commands: sync(8), volintro(8), volassist(8), voledit(8),
volmend(8), volume(8)
volplex(8)
[ Back ] |
