 |
Index for
Section 8 |
|
 |
Alphabetical
listing for V |
|
 |
Bottom of
page |
|
volplex(8)
NAME
volplex - 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
-g diskgroup
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.
-U usetype
Limits the operation to apply to this usage type. Attempts to affect
volumes with a different usage type will fail.
-o useopt
Passes in usage-type-specific options to the operation. The following
operations are implemented by all usage types:
slow[=iodelay]
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).
iosize=size
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.
rm Removes the plexes after successful completion of a plex
dissociation operation. Removes the source plex after successful
completion of a plex move operation.
-v volume
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.
-V 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.
-f 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 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.
KEYWORDS
These are the recognized operation keywords:
att 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.
cp 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.
det 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.
dis 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.
mv 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.
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,
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
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:
force
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.
rerr
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.
werr
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.
mapzero
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.
fpa 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:
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 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.
cp The fsgen and gen usage types do not add any specific restrictions to
the cp operation.
dis and det
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.
mv 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.
RAID 5 USAGE-TYPE
The raid5 usage type provides the following options as arguments to -o in
addition to the required options:
force
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:
att 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.
dis 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.
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.
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:
1. 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
2. Dissociate the migrant plex from the primary volume:
volplex dis myvol-02
3. Create a secondary volume:
volmake vol myvol_backup
4. Attach the migrant data plex to the secondary volume:
volplex att myvol_backup myvol-02
5. Start the secondary volume:
volume start myvol_backup
FILES
/sbin/lsm.d/usetype/volplex
The utility that performs volplex operations for a particular volume
usage type.
/sbin/lsm.d/fsgen/fs.d/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 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)
|
Index for
Section 8 |
|
|
Alphabetical
listing for V |
|
 |
Top of
page |
|