vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
NAME [Toc] [Back]
vxplex - perform VERITAS Volume Manager operations on plexes
SYNOPSIS [Toc] [Back]
vxplex [-fV] [-g diskgroup] [-o useopt] [-R request_portal] [-s
srcplex1 [-s srcplex2] ...] [-t tasktag] [-T taskid] [-U usetype] att
volume plex...
vxplex [-fV] [-g diskgroup] [-o useopt] [-R request_portal] [-t
tasktag] [-T taskid] [-U usetype] convert state=ACTIVE|SNAPDIS|SNAPDONE
plex [plex1...]
vxplex [-fV] [-g diskgroup] [-o useopt] [-R request_portal] [-t
tasktag] [-T taskid] [-U usetype] cp volume plex...
vxplex [-fV] [-g diskgroup] [-o useopt] [-R request_portal] [-t
tasktag] [-T taskid] [-U usetype] [-v volume] det plex...
vxplex [-fV] [-g diskgroup] [-o useopt] [-R request_portal] [-t
tasktag] [-T taskid] [-U usetype] [-v volume] dis plex...
vxplex [-fV] [-g diskgroup] [-o useopt] [-R request_portal] [-t
tasktag] [-T taskid] [-U usetype] [-v volume] mv oldplex newplex
vxplex [-fV] [-g diskgroup] [-o useopt] [-R request_portal] [-t
tasktag] [-T taskid] [-U usetype] snapabort plex...
vxplex [-fV] [-c checkpoint] [-g diskgroup] [-o useopt] [-R
request_portal] [-t tasktag] [-T taskid] [-U usetype] snapshot plex
[new_volume] [plex [new_volume]...]
vxplex [-fV] [-g diskgroup] [-o useopt] [-R request_portal] [-s
srcplex1 [-s srcplex2] ...] [-t tasktag] [-T taskid] [-U usetype]
snapstart volume plex...
vxplex [-fV] [-g diskgroup] [-o useopt] [-R request_portal] [-t
tasktag] [-T taskid] [-U usetype] snapback volume plex...
DESCRIPTION [Toc] [Back]
The vxplex utility performs VERITAS Volume Manager (VxVM) 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. Any
volume or plex operands are used to determine a default disk group,
according to the standard disk group selection rules described in
vxintro(1M). A specific disk group can be forced with -g diskgroup.
- 1 - Formatted: January 24, 2005
vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
KEYWORDS [Toc] [Back]
att Attaches 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 is 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.
convert Converts a snapshot plex into a regular plex, or a regular
plex into a snapshot plex. This operation allows you to
create a snapshot plex for a volume that already has two or
more mirrors without using snapstart.
The main difference between a snapshot plex and a regular
plex is the plex state. A plex may be in one of many states
depending on errors, detaches and other transactions. The
vxplex convert operation is limited to moving plexes between
the ACTIVE, SNAPDONE, and SNAPDIS plex states. The state of
a regular plex that is attached to an open volume is ACTIVE.
The state of a snapshot plex after the snapshot operation
has completed is usually SNAPDONE, although it may be in the
SNAPDIS state if attached using vxplex.
The state attribute to the convert operation specifies the
final state of the plex after conversion: ACTIVE, SNAPDIS,
or SNAPDONE. A regular plex is usually converted to a
snapshot plex in the SNAPDONE state, and a snapshot plex is
usually converted to a regular plex in the ACTIVE state.
The SNAPDIS option is provided for convenience of scripting.
As well as changing the plex state, the convert operation
also changes the I/O mode and the noerror flag for the plex.
The I/O mode is set to read/write for a regular plex, and to
read-only for a snapshot plex. The noerror flag is cleared
for regular plexes, and set for snapshot plexes.
Additionally, if Persistent FastResync is enabled on a
volume (that is, a data change object (DCO) and DCO volume
are associated with the volume), a DCO plex must be added if
a regular plex is converted to a snapshot plex, and a DCO
plex must be removed if a snapshot plex is converted to a
regular plex.
The following example shows how to convert the regular plex
plex1 to a snapshot plex, which is associated with the DCO
plex, dcoplex1:
- 2 - Formatted: January 24, 2005
vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
vxplex -g mydg -o dcoplex=dcoplex1 convert state=SNAPDONE plex1
Note: The last complete regular plex in a volume, an
incomplete regular plex, or a dirty region logging (DRL) log
plex cannot be converted into a snapshot plex.
cp Copies the named volume to the named plexes. The volume
cannot be enabled, and the named plexes must not be
associated. The result of the operation is a set of
dissociated plexes that is 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.
det Detaches 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. 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.
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,
which can be done either with vxplex att or with vxmake.
Any checks and synchronizations that apply to the det
operation also apply to the dis operation.
Plex dissociation is the typical means of unmirroring a
volume or reducing the mirror count for a volume. To do
this, use -o rm 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 vxassist or vxmake).
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 does 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 as in the following example:
- 3 - Formatted: January 24, 2005
vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
vxmake -U gen vol volume01 plex=plex01
The created volume can then be started and mounted for use
by the backup program.
Another common use of dis is to remove DCM plexes from data
volumes. Removing all the DCMs from a single data volume
disables SRL overflow protection for all the data volumes in
the RVG. The dissociation fails if the DCM is active.
You can also remove a mirror from a volume, as shown in the
following example:
vxplex -o rm dis vol01-02
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 or striped plexes, the vxsd mv operation
can be used to move individual subdisks off a disk. The
rules for performing the move depend upon the usage types of
the volume to which oldplex is associated.
oem Not used in this release.
snapabort This operation can be used in order to cancel the effects of
a snapstart.
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.
If the -s option is used to specify one or more source
plexes, snapstart synchronizes the data in the newly
attached snapshot plex from the source plexes.
- 4 - Formatted: January 24, 2005
vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
If you use snapstart to attach a pre-existing plex, run the
following command to convert the state of the plex to
SNAPDONE when the snapstart operation is complete:
vxplex -g diskgroup convert state=SNAPDONE plex
After the snapstart operation completes and the temporary
plex is in the SNAPDONE state, you can use vxplex snapshot
to convert it into a new volume. If identical new_volume
names are specified for two or more SNAPDONE plexes, a
mirrored snapshot volume is created.
For convenience of administration, you can use the -o
comment=comment option with snapshot to define a comment for
the snapshot 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 method of backup is preferable to using vxplex 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.
snapback This operation dissociates one or more named plexes from
their current volume and attaches them to the specified
volume. If a plex is the last in its current volume, this
volume is removed from the disk group.
Note: The volumes containing the named plexes and
destination volume must be in the same disk group.
OPTIONS [Toc] [Back]
-c checkpoint
Sets a named checkpoint on a snapshot. Note: This option is
a deprecated feature of VVR and should not be used.
-f Forces an operation that VxVM 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.
-g diskgroup
Specifies the disk group for the operation, either by disk
group ID or by disk group name. By default, the disk group
- 5 - Formatted: January 24, 2005
vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
is chosen based on the name operands.
-o useopt Passes in usage-type-specific options to the operation. A
certain set of operations are expected to be implemented by
all usage types:
comment=comment
Sets a comment on a snapshot volume during a snapshot
operation.
dcoplex=dco_plex
Specifies the DCO plex to be used with a convert
operation.
iosize=size
Performs copy operations in regions with the length
specified by size, which is a standard VERITAS Volume
Manager length number (see vxintro(1M)). 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.
nofmr
Forces a full resynchronization during a snapback or
att operation even if FastResync is enabled.
numchild=number
Specifies the number of child processes that are used
to perform resynchronization during att and snapback
operations. The default value of number is 1 (no child
processes), which is the same as specifying a number of
0. Specifying a larger value for number potentially
speeds up resynchronization, although the effectiveness
of this depends to some extent on the underlying
characteristics of the disk array. No further benefit
in performance may be noticeable for a value for number
greater than 3.
By default, the child processes divide the volume into
equally sized chunks, which they then resynchronize
independently with the volume. This behavior may be
modified using the useopt sequential.
Note: A large iosize of 1m or 2m is recommended for use
with this option.
renamesnapplex
Specifies that a snapshot plex is renamed when the
snapshot operation is used to create a snapshot volume.
If this option is not specified, the plex retains the
- 6 - Formatted: January 24, 2005
vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
same name that it had in the original volume.
resyncfromoriginal
Chooses the original volume as the preferred copy of
data during a snapback or att operation. This is the
default behavior.
Note: Unmount the snapshot volume (if mounted) before
performing this operation.
resyncfromreplica
Chooses the replica plex as the preferred copy of data
during a snapback or att operation. resyncfromoriginal
is the default behavior.
Note: Unmount the original volume (if mounted) before
performing this operation.
rm Removes the plexes after successful completion of a
vxplex dis operation. Remove the source plex after
successful completion of vxplex mv.
sequential
When specified with the useopt numchild for values of
number greater than 1, the child processes co-operate
in resynchronizing regions of the volume that are close
together, starting at the beginning of the volume and
moving to the end. This creates more overhead for the
resynchronization, but it potentially makes better use
of the sequential read-ahead buffer of the physical
disks.
slow[=iodelay]
Reduces the system performance impact of copy
operations. Such operations are usually performed 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).
-R request_portal
Specifies a rendezvous file path name for regular
configuration and query requests. /etc/vx/vold_request is
the default.
-s srcplex1 [-s srcplex2] ...
Specifies one or more source plexes to be used for
resynchronization in the att and snapstart operations.
- 7 - Formatted: January 24, 2005
vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
-t tasktag
If any tasks are registered to track the progress of the
operation, marks them with the tag tasktag. The tag
specified by tasktag is a sequence of up to 16 alphanumeric
characters.
-T taskid Associates new tasks with the specified parent task ID.
-U usetype
Limits the operation to apply to this usage type. Attempts
to affect volumes with a different usage type fail.
-v volume Requires 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 Displays a list of utilities that would be called from
vxplex, along with the arguments that would be passed. The
-V option performs a preview run so the utilities are not
actually called.
FSGEN and GEN Usage Types [Toc] [Back]
The fsgen and gen usage types provide similar, though not identical,
semantics for all operations of the vxplex utility. In particular,
the fsgen usage type attempts to flush in-memory data cached for the
file system residing on the volume. For most file systems, this
consists of calling sync(1M) to attempt to flush all in-memory data to
disk. For the vxfs file system type, special ioctls are called to
ensure a reliable flush of the involved volume.
If a vxplex 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 vxplex 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 VxVM considers 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.
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.
- 8 - Formatted: January 24, 2005
vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
Without this flag, the mapped region may be left unchanged
from its original contents.
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.
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 is fully
attached by the next vxvol start or vxvol startall operation
that is applied 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 DRL. Logging
of volume changes 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 vxedit set to set the putil0
field to a non-empty string. The putil0 field can then be
cleared with either vxedit set or with vxmend clear putil0.
cp The fsgen and gen usage types do not add any specific
restrictions to the cp operation.
det, dis A detach or dissociate of a plex can fail for one of two
reasons. In an enabled volume a detach or dissociate fails
- 9 - Formatted: January 24, 2005
vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
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, noncomplete
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 other way a detach or
dissociate can fail is if the plex is of type DCM and it is
active. A DCM is active if SRL overflow protection is active
or if a resync of a replicated volume is in progress.
The det operation changes the state for an ACTIVE or CLEAN
plex to STALE. The next time the volume is started, the
plex is re-attached automatically.
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 prevents 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.
RAID5 Usage-Type [Toc] [Back]
The raid5 usage type provides the following options as arguments to -o
in addition to the required options:
force Forces an operation that VxVM considers potentially
dangerous or of questionable use. This applies to attempts
to dissociate the RAID-5 plex of a non-EMPTY volume or to
remove the last RAID-5 log plex of a non-EMPTY volume.
As with other usage types, if a vxplex 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 vxplex exits.
The raid5 usage type supports the following keywords as described
here:
att Attaches the named plexes to the named volume. If a plex has
a layout of RAID, the plex is attached as the RAID-5 plex of
the RAID-5 volume. To attach a RAID-5 plex to the volume,
the volume must be disabled and be in the EMPTY state, and
- 10 - Formatted: January 24, 2005
vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
the RAID-5 plex is given a state of EMPTY.
If a plex has a layout other than RAID, the plex is attached
as a RAID-5 log plex for the RAID-5 volume. If the volume
has no RAID-5 log plexes, the log length for the volume is
set to the length of the smallest log plex being attached.
If the volume already has at least one log plex, a plex can
only be attached as a log plex if its contiguous length is
at minimum the volume's log length. RAID-5 log plexes cannot
be sparse in respect to the volume's log length; attempts to
attach a sparse log plex 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 causes 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 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 would leave the RAID-5
volume with no usable log plexes, the -o force option is
required.
Note: The RAID-5 usage type does not support the det, copy or cp
operations.
FILES [Toc] [Back]
/usr/lib/vxvm/type/usetype/vxplex
The utility that performs vxplex
operations for a particular volume usage
type.
/usr/lib/vxvm/type/fsgen/fs.d/fstype/vxsync
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 vxfs file
system type, this program uses the
VERITAS File System (VxFS) freeze
feature to ensure a perfect synchronized
detach.
- 11 - Formatted: January 24, 2005
vxplex(1M) VxVM 3.5 vxplex(1M)
1 Jun 2002
EXIT CODES [Toc] [Back]
The vxplex utility exits with a non-zero status if the attempted
operation fails. A non-zero 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 vxintro(1M) for a list of standard exit codes.
EXAMPLES [Toc] [Back]
Associate plex vol02-03 with the existing volume vol02:
vxplex att vol02 vol02-03
Temporarily detach plex vol03-03 from its volume:
vxplex det vol03-03
Dissociate plex vol01-03 from the plexes vol01-01 through vol01-03 on
volume vol01:
vxplex dis vol01-03
SEE ALSO [Toc] [Back]
sync(1M), vxassist(1M), vxedit(1M), vxintro(1M), vxmend(1M),
vxtask(1M), vxvol(1M)
- 12 - Formatted: January 24, 2005 [ Back ] |
