volplex(1M) Volume Manager Utilities volplex(1M)
NAME
volplex - Performs Volume Manager operations on plexes
SYNOPSIS
volplex [ -U usetype ] [ -o useopt ] [ -V ] att vol plex ...
volplex [ -U usetype ] [ -o useopt ] [ -V ] [ -v vol ] det plex ...
volplex [ -U usetype ] [ -o useopt ] [ -V ] [ -v vol ] dis plex ...
volplex [ -U usetype ] [ -o useopt ] [ -V ] cp vol plex ...
volplex [ -U usetype ] [ -o useopt ] [ -V ] [ -v vol ]
mv oldplex newplex
DESCRIPTION
The volplex utility performs Volume 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.
These are the recognized operation keywords:
att Attach each plex to the volume vol. The action of
attaching is performed by a usage-type utility, as
appropriate for the volume. If the plex is not
associated, then it is first associated with the volume
before being attached. An attached plex actively
participates in I/O activity to the volume. A usage-
type utility may only perform the association if
attaching the plex is inappropriate, for example if the
volume is DISABLED.
det Detach each plex from the volume it is associated with.
To be detached, a plex must be associated with a
volume. For each named plex, the associated volume is
found. The usage-type for this volume is used for
executing a usage-type utility as appropriate for the
volume. If more than one usage-type is represented by
the plex operands, then more than one usage-type
utility is invoked.
A detached plex does not participate in I/O activity to
the volume, but remains associated with the volume.
The semantics of a detached plex are somewhat dependent
upon the usage-type, but in the case of the fsgen and
gen usage-types, a detached plex is reattached by a
volume start operation.
dis Dissociate each plex from the volume it is associated
with. To be dissociated, a plex must be associated
with a volume. For each named plex, the associated
volume is found. The usage-type for this volume is
used for executing a usage-type utility as appropriate
Page 1 (printed 1/21/92)
volplex(1M) Volume Manager Utilities volplex(1M)
for the volume. If more than one usage-type is
represented by the plex operands, then more than one
usage-type utility is invoked. If a plex is attached
to a volume, it is first detached.
When a plex is dissociated, its relationship to the
volume is broken completely. As such, the plex becomes
available for other uses, such as association with a
different volume.
cp Copy the contents of the specified volume onto all of
the named plexes. Prior to copying onto a plex, the
plex must not be associated with any volume. After the
volume contents have been copied to the plex, the plex
is dissociated. The action is carried out by a usage-
type utility as appropriate for the volume.
mv Move the contents of oldplex onto newplex. Also,
detaches and dissociates oldplex from the volume it is
associated with, and associates and attaches newplex to
that volume. The action is carried out by a usage-type
utility as appropriate for the volume to which oldplex
is associated. The mv operation fails if oldplex is
not associated.
NOTE
The volplex command may take as much time to complete as a
dd command.
OPTIONS
The following options are recognized:
-U usetype
Force the operation to be performed by the usage-type
utility for this usage-type.
-o useopt
Give usage-type-specific options to the usage-type-
specific utility.
-v vol
Require that the plex named by a plex or oldplex
operand be associated with the volume named by vol.
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 option performs a ``mock run,'' the utilities
are not actually called, and no changes are made to the
volume configuration database.
Page 2 (printed 1/21/92)
volplex(1M) Volume Manager Utilities volplex(1M)
USAGE TYPE INTERFACE
The usage-type-specific volplex utilities perform the
actions that were requested by the user. Usage-type
utilities are called with the same options and keyword given
to the volplex switchout utility. The list of additional
operands passed to the usage-type utilities vary depending
upon the operation. In all operations described below, if a
usage-type is specified using the -U option letter, then the
utility for that usage-type is called directly, as long as
the operands conform to the operation synopsis.
volplex att and volplex cp
The usage-type for the volume is used. The usage-type
utility is given the vol and all of the plex arguments
in the same order they appear on the command line to
the switchout utility.
volplex det and volplex dis
All of the plex operands must be associated with a
volume. The usage-types for those volumes are
determined and the usage-type-specific volplex utility
is called once for each of the usage-types represented.
A specific usage-type is passed to each of the plex
operands that apply to that usage-type. The order of
plex operands given to a usage-type are not necessarily
the order that they appear on the command line for the
switchout utility.
If a required volume is specified through the -v option
letter, then the usage-type for that volume is used for
all plex operands. No further checking is performed.
volplex mv
If the plex named by the oldplex argument is
associated, then use the usage-type for that volume;
otherwise use the gen usage-type. The usage-type-
specific utility is given the oldplex and newplex
arguments in that order.
SYNOPSIS FOR FSGEN AND GEN USAGE-TYPES
volplex [ -U usetype ] [ -o useopt ] att vol plex ...
volplex [ -U usetype ] [ -o useopt ] [ -v vol ] det plex ...
volplex [ -U usetype ] [ -o useopt ] [ -v vol ] dis plex ...
volplex [ -U usetype ] [ -o useopt ] cp vol plex ...
volplex [ -U usetype ] [ -o useopt ] [ -v vol ] mv oldplex newplex
FSGEN AND GEN DESCRIPTION
The volplex utility for the fsgen and gen volume usage-types
performs 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
Page 3 (printed 1/21/92)
volplex(1M) Volume Manager Utilities volplex(1M)
operation is applied.
These are the recognized operation keywords:
att Attach or associate each plex to the volume vol. If
the volume is enabled, then the contents of the volume
are copied onto the destination plexes, using the
ATOMICCOPY volume ioctl. This attach happens only if
the following conditions are met for each plex:
1. If the plex is associated with the named volume,
then the utility state of the plex must be STALE,
EMPTY, ACTIVE, or OFFLINE, and the plex must not be
enabled.
2. The volume must have at least one enabled, read-
mode plex that contains a complete image of the
volume contents (that is, one attached plex must
not be sparse relative to the volume).
If these conditions are met, then an attempt is made to
copy the volume contents onto the each new plex. If
the copy is successful, then the plex is made read-
write and will participate normally in volume error
policies. The final utility state for an attached plex
is set to EMPTY if the other plexes associated with the
volume are also EMPTY; if it's not empty the utility
state is set to ACTIVE.
If the volume is not enabled, then the named plexes are
associated with the volume. The operation fails if any
of the named plexes are already associated. If the
other plexes associated with the volume are EMPTY, or
if the volume does not have any associated plexes, then
the utility states for the new plexes are also set to
EMPTY; otherwise the utility states for the new plexes
are set to STALE.
An attempt to attach an unassociated plex fails if the
putil0 field for the plex is not empty. This makes it
possible to prevent use of a plex by using the voledit
utility to set the putil0 field to a nonempty string
value.
When an unassociated plex that has a logging subdisk is
being attached and the logging type of the volume is
BLKNO, then the the logging subdisk must be at least 1
sector in length. If the logging type of the volume is
UNDEF, then associating a plex with a logging subdisk
changes the logging type for the volume to BLKNO.
Logging of volume changes is enabled when two or more
attached plexes have associated log subdisks.
Page 4 (printed 1/21/92)
volplex(1M) Volume Manager Utilities volplex(1M)
If an attach operation is interrupted by a signal, then
an attempt is made to restore the destination plexes 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, then the
user may need to perform some cleanup. The specific
cleanup that is needed is written to the standard error
before volplex exits.
det Set the kernel state for the specified plexes to
DETACHED. Also, if the utility state for a plex is
ACTIVE or CLEAN, det changes the utility state to
STALE. This operation allows a plex to be accessed
through the corresponding plex device, in the /dev/plex
directory, but prevents active volume I/O from being
reflected to the plex.
A plex cannot be detached if it is the last complete,
enabled, read-mode plex in the volume and the volume
contains two or more noncomplete, enabled, read-mode
plexes. A plex is complete if it is compact and at
least as long as the volume to which it is associated.
A plex is in read-mode if the plex I/O mode is read-
only or read-write.
If a plex is enabled and in read-mode and is part of a
nondisabled volume, then -o force must be specified if
the plex is the last enabled, read-mode plex associated
with the volume, or if the plex is the last compact,
enabled, read-mode plex associated with the volume.
The following applies to the fsgen usage-type only: If
the plex is enabled, and the volume is both enabled and
open, then an FSType-specific volsync utility is called
to synchronize any activity by the user of the volume
with the disk image before the detach operation
completes. For the s5 and ufs file systems this
utility simply calls sync (see sync(1M)). For the vxfs
file system, supplied by VERITAS, this action freezes
all activity on the volume, detaches the plex, and
unfreezes the volume. This guarantees a reliable
snapshot of the volume contents.
dis Dissociate the named plexes from the volumes for the
particular usage-type - fsgen or gen - to which the
plexes are associated. The utility state for each plex
is cleared, because the plex is no longer associated
with that usage-type. If a plex is enabled, then a
detach operation is also performed. The restrictions
that apply to the det operation also apply to dis.
cp Copy the contents of a volume to the named plexes.
Page 5 (printed 1/21/92)
volplex(1M) Volume Manager Utilities volplex(1M)
This operation can be applied only to an enabled volume
that also has at least one enabled, read-mode plex.
The destination plexes cannot be associated before the
cp operation, and they are dissociated after the
operation completes. The copy operation is performed
using the ATOMICCOPY volume ioctl.
If the rerr option is set, through the -o useopt
string, then read errors are reported, but do not
prevent the operation from proceeding. Likewise, if
the werr option is set, then write errors are reported,
but do not prevent the operation from proceeding.
If a copy operation is interrupted by a signal, then an
attempt is made to restore the destination plexes to
their original state. If this attempt is interrupted,
such as through another signal, then some cleanup may
need to be performed by the user. The specific cleanup
that is needed is written to the standard error before
volplex exits.
mv Copy the contents of plex oldplex onto newplex, and
replaces oldplex with newplex in the volume
association. oldplex must not be disabled and must be
in read-mode. Also, oldplex must be associated with a
volume that is not disabled, and newplex must not be
associated before the move operation.
If newplex contains unmapped regions (address ranges
that are not backed by a subdisk) that match mapped
regions from oldplex, then -o force must be specified
for the operation to proceed.
If a plex address region is mapped in newplex but is
not mapped in oldplex, then the following rules govern
what is copied onto the region that is mapped only in
newplex:
1. If the volume contains at least one complete,
enabled, read-mode plex then the volume contents
are copied onto the destination plex; otherwise,
2. If -o mapzero is specified then zeroed blocks are
written onto the destination plex; otherwise,
3. That region in the destination plex is left
unchanged.
A copy is performed using the ATOMICCOPY volume ioctl.
Zeroing of a region is performed using the PLEXWRITE
volume ioctl.
Page 6 (printed 1/21/92)
volplex(1M) Volume Manager Utilities volplex(1M)
If a move operation is interrupted by a signal, then an
attempt is made to restore the source and destination
plexes to their original states. If this attempt is
interrupted, such as through another signal, then the
user may need to perform some cleanup. The specific
cleanup that is needed is written to the standard error
before volplex exits.
FSGEN AND GEN OPTIONS
The following options are recognized:
-U usetype
For fsgen:
A usage-type name passed in from the switchout volplex
utility. If this option is specified then the value
for usetype must be fsgen.
For gen:
The gen usage-type volplex utility can be used by
anther usage-type that has similar characteristics as
long as the name of the other usage-type is specified
with this option.
-o useopt
A list of options separated by commas and white space.
These options can be either a name, or a name and a
value separated by an equal sign. The recognized
usage-type options are:
force Force a plex to be detached, with det or dis,
even if it is the last enabled plex for a
volume. Also forces an mv operation, even if
the subdisk configurations for oldplex and
newplex do not match.
rerr Ignore volume or plex read errors when
copying data onto a plex. An error message
is written to the standard error if a read
error occurs, but the error does not affect
the success of the operation. This option
can be used only with the cp operation. This
option is ignored if used with other
operations.
werr Ignore plex write errors when copying data
onto a plex. An error message is written to
the standard error if a write error occurs,
but the error does not affect the success of
the operation. This option can be used only
with the cp operation. This option is
ignored if used with other operations.
Page 7 (printed 1/21/92)
volplex(1M) Volume Manager Utilities volplex(1M)
mapzero If mv is used to move plex contents onto a
destination plex that has a mapped region for
which no corresponding mapped region exists
in the source plex, this option zeros that
region of the destination plex. See the
description of the mv operation for details.
iosize=size
Specify the number of sectors to copy in each
call to the ATOMICCOPY volume ioctl. This
can affect the att, cp, and mv operations.
The default I/O size is 32 kilobytes. The
I/O size value is silently truncated to 128
kilobytes, which is the size of
VOLMAXSPECIALIO in the include file
sys/vol.h. An I/O size must be an integer
multiple of the system sector size, which is
512 bytes for the reference port of of the
Volume Manager. A large I/O size generally
increases the speed of the operation at the
expense of regular volume I/O. Smaller I/O
sizes decrease memory requirements for the
operation and have a smaller impact on
throughput of regular volume I/O.
An I/O size can be specified using a C-style
decimal, hexadecimal, or octal number and can
be given a suffix of s, b, k, m, or g to
indicate sectors (the default), 512-byte
blocks, kilobytes, megabytes, or gigabytes.
This suffix can be in upper- or lowercase.
See volsscan(3X) for more information.
slow[=iodelay]
Reduce the system performance impact of an
att, mv or cp operation. The plex-to-plex
copies required for these operations can have
a serious impact on I/O throughput of other
processes using the affected disk drives. To
reduce this impact, at the expense of the
plex-to-plex copy speed, the slow option
introduces a delay of milliseconds between
each individual I/O request (iosize defines
the size of each I/O request). Either an
explicit number of milliseconds can be given,
or a system default is used.
-v vol
Require that the plex named by a plex or oldplex
operand be associated with the volume named by vol.
This option serves as a sanity check to ensure that the
Page 8 (printed 1/21/92)
volplex(1M) Volume Manager Utilities volplex(1M)
specified plex is actually the plex desired for the
operation.
FILES
/usr/lib/VxVM/type/usetype/volplex
Usage-type-specific utility for performing
plex operations.
/usr/lib/VxVM/type/gen/volplex
Usage-type-specific utility for the gen
volume usage-type.
/dev/plex/ Directory containing plex devices. This
directory contains an entry for each plex
that is associated with a volume. Each plex
device is a character-special file that can
be used to examine a specific plex within a
volume. Because plex devices are not block-
special devices, they can not be mounted as
file systems. A plex device can be accessed
only if neither the plex nor the volume is
disabled.
/usr/lib/VxVM/type/fsgen/fs/fstype/volsync
volume plex ...
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(1M) for a list of standard
exit codes.
SEE ALSO
volintro(1M), voledit(1M), volsscan(3X), vol(7), ioctl(2),
and sync(1M).
Page 9 (printed 1/21/92)