volplex(8)volplex(8)NAMEvolplex - Perform Logical Storage Manager 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] 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
OPTIONS
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 per‐
formance impact of copy operations. Copy operations are usually per‐
formed in series on small regions of the volume (normally from 16 kilo‐
bytes to 256 kilobytes). This option inserts a delay between the recov‐
ery 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.
DESCRIPTION
The volplex utility performs Logical Storage Manager operations on
plexes and on volume-and-plex combinations. The first operand is a key‐
word 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.
KEYWORDS
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 asso‐
ciate 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 per‐
forming 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 vol‐
ume. 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 pur‐
poses, 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 disso‐
ciated plex. Dissociates each of the named plexes. Dissociating
a plex breaks the link between the plex and its volume. A disso‐
ciated plex is inaccessible until it is reassociated, either
with volplex att or with volmake. Any checks and synchroniza‐
tions 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 pur‐
pose, 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 pro‐
gram 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 opera‐
tion 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 orig‐
inal 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 com‐
plete. Also, directly converting the plex into a new volume is
more convenient than requiring additional steps.
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 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 argu‐
ments 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 vol‐
ume), 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 corre‐
sponding 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 associ‐
ated 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 con‐
verted 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 vol‐
ume), 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 vol‐
ume. 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 com‐
plete plexes.
RAID 5 USAGE-TYPE
The raid5 usage type provides the following options as arguments to -o
in addition to the required options: Forces an operation that the Logi‐
cal 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. Dissoci‐
ates 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, snap‐
start, or snapshot keywords; these operations are either inappropriate
or impossible to perform within the operational concepts of RAID 5.
EXIT CODES
The volplex utility exits with a nonzero status if the attempted opera‐
tion fails. A nonzero exit code is not a complete indicator of the
problems encountered but rather denotes the first condition that pre‐
vented further execution of the utility. See volintro(8) for a list of
standard exit codes.
EXAMPLES
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 pri‐
mary 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
FILES
The utility that performs volplex operations for a particular volume
usage type. Path to a program used with the fsgen usage type for syn‐
chronizing in-memory file system data with a volume, for the file sys‐
tem 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.
SEE ALSO
Commands: sync(8), volintro(8), volassist(8), voledit(8), volmend(8),
volume(8)volplex(8)
