
#  man vxplex
Reformatting page.  Wait... done

Maintenance Commands                                   vxplex(1M)

NAME
     vxplex - perform Volume Manager operations on plexes

SYNOPSIS
     vxplex [-fV] [-g diskgroup] [-o useopt ]  [-t  tasktag]  [-U
     usetype ] att volume plex...

     vxplex [-fV] [-g diskgroup] [-o useopt ]  [-t  tasktag]  [-U
     usetype ] [-v volume ] det plex...

     vxplex [-fV] [-g diskgroup] [-o useopt ]  [-t  tasktag]  [-U
     usetype ] [-v volume ] dis plex...

     vxplex [-fV] [-g diskgroup] [-o useopt ]  [-t  tasktag]  [-U
     usetype ] cp volume plex...

     vxplex [-fV] [-g diskgroup] [-o useopt ]  [-t  tasktag]  [-U
     usetype ] snapstart volumeplex...

     vxplex [-fV] [-g diskgroup] [-o useopt ]  [-t  tasktag]  [-U
     usetype ] snapshot plex newvolume...

     vxplex [-fV] [-g diskgroup] [-o useopt ]  [-t  tasktag]  [-U
     usetype ] snapabort plex...

     vxplex [-fV] [-g diskgroup] [-o useopt ]  [-t  tasktag]  [-U
     usetype ] [-v volume ] mv oldplex newplex

DESCRIPTION
     The vxplex 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 configura-
     tion 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 vxintro(1M).  A specific disk  group  can
     be forced with -g diskgroup.

KEYWORDS
     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  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 per-
               forming the attach depend upon the usage  type  of

VxVM 3.0            Last change: 11 Dec 1998                    1

Maintenance Commands                                   vxplex(1M)

               the named volume.

               Attaching a plex is the normal means of recovering
               a  plex  after a disk replacement, or after a plex
               offline.

     cp        Copies the named volume to the named plexes.   The
               volume  cannot  be  enabled,  and the named plexes
               must not be associated.  The results of the opera-
               tion  will be a set of dissociated plexes that are
               an exact copy of the volume at the time of comple-
               tion  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.   Dissociat-
               ing  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 normal means of unmirror-
               ing  a  volume, or reducing the mirror count for a
               volume.  To support this use, -o rm can be used 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 allo-
               cations (such as with vxassist or with 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 will
               not work if the backup program requires a  mounted
               file  system.   To support such backup programs, a

VxVM 3.0            Last change: 11 Dec 1998                    2

Maintenance Commands                                   vxplex(1M)

               plex can be dissociated and can then be  allocated
               to a new volume, such as with the command:

                    vxmake -U gen vol volume plex=plex

               The created volume can then be started and mounted
               for use by the backup program.

     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.

     snapabort This operation cab be used in order to cancel  the
               effects of a snapstart.

     snapstart and snapshot
               These two operations form the two parts of a  pre-
               ferred  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 com-
               plete, leaves the plex associated as  a  temporary
               plex.  After the operation completes, the adminis-
               trator can convert the plex attached by  snapstart
               into  a  new  volume  using  vxplex  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
               vxplex  cp  because it allows the administrator 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 dif-
               ficult to  know  when  it  will  complete.   Also,
               directly  converting the plex into a new volume is

VxVM 3.0            Last change: 11 Dec 1998                    3

Maintenance Commands                                   vxplex(1M)

               more convenient than requiring additional steps.

OPTIONS
     -f        Forces an operation that the Volume  Manager  con-
               siders  potentially  dangerous  or of questionable
               use.  This permits a  limited  set  of  operations
               that  would  otherwise be disallowed.  Some opera-
               tions 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 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:

               iosize=size
                    Performs copy operations in regions with  the
                    length specified by size, which is a standard
                    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.

               rm   Removes the plexes after  successful  comple-
                    tion  of  a vxplex dis operation.  Remove the
                    source plex after  successful  completion  of
                    vxplex mv.

               slow[=iodelay]
                    Reduces the system performance impact of copy
                    operations.   Copies operations are usually a
                    set of short copy operations 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   mil-
                    liseconds).

     -t tasktag
               If any tasks are registered to track the  progress
               of the operation, mark them with the tag tasktag.

     -U usetype
               Limits the operation to apply to this usage  type.

VxVM 3.0            Last change: 11 Dec 1998                    4

Maintenance Commands                                   vxplex(1M)

               Attempts  to affect volumes with a different usage
               type will 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 ``mock  run''
               so the utilities are not actually called.

FSGEN and GEN Usage Types
     The fsgen and gen usage types provide  similar,  though  not
     identical,  semantics for all operations of the vxplex util-
     ity.  In particular, the fsgen usage type  will  attempt  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, this will use special  ioctls
     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 the Volume  Manager  con-
               siders  potentially  dangerous  or of questionable
               use.  This applies to attempts to detach or disso-
               ciate  the last (complete) plex in a volume, or to
               attempts to move a plex to a plex that has a  dif-
               ferent 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.   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

VxVM 3.0            Last change: 11 Dec 1998                    5

Maintenance Commands                                   vxplex(1M)

               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 opera-
               tion;  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 opera-
               tion can be used only with the cp  operation;  the
               operation  is  ignored  if  used with other opera-
               tions.

     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 vxvol start or vxvol  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  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 pos-
               sible 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.

     dis and det

VxVM 3.0            Last change: 11 Dec 1998                    6

Maintenance Commands                                   vxplex(1M)

               A detach or dissociate of a  plex  in  an  enabled
               volume fails 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, non-
               complete 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 det operation changes the state for an  ACTIVE
               or  CLEAN plex to STALE.  The next time the volume
               is started, the plex will be re-attached automati-
               cally.

     mv        If the destination plex has  unmapped  regions  (a
               range  of  blocks in the plex with no backing sub-
               disk) 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 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.

RAID5 Usage-Type
     The raid5 usage type provides the following options as argu-
     ments to -o in addition to the required options:

     force     Forces an operation that the Volume  Manager  con-
               siders  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  inter-
     rupted  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 inter-
     rupted (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 only the following keywords:

     att       Attaches the named plexes to the named volume.  If
               a  plex  has  a  layout  of RAID, the plex will be

VxVM 3.0            Last change: 11 Dec 1998                    7

Maintenance Commands                                   vxplex(1M)

               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
               the RAID-5 plex will be given a state of EMPTY.

               If a plex has a layout other than RAID,  the  plex
               will  be  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 will be 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 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.  Oth-
               erwise, 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  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,  snapstart, snapshot, snapabort, or copy keywords; these
     operations are either inappropriate or impossible to perform
     within the operational concepts of RAID-5.

FILES
     /etc/vx/type/usetype/vxplex   The  utility   that   performs
                                   vxplex  operations  for a par-
                                   ticular volume usage type.

     /etc/vx/type/fsgen/fs/fstype/vxsync
                                   Path to a  program  used  with
                                   the  fsgen usage type for syn-
                                   chronizing in-memory file sys-
                                   tem  data  with  a volume, for
                                   the file system  type  fstype.

VxVM 3.0            Last change: 11 Dec 1998                    8

Maintenance Commands                                   vxplex(1M)

                                   The program is given arguments
                                   of a volume name  and  one  or
                                   more  plex  names. For the ufs
                                   and s5 file system types, this
                                   is  a  link  to sync.  For the
                                   vxfs file system   type,  this
                                   program  uses  the  VxFS  file
                                   system   freeze   feature   to
                                   ensure  a perfect synchronized
                                   detach.

EXIT CODES
     The vxplex 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 vxintro(1M) for a list of standard exit
     codes.

SEE ALSO
     sync(1M), vxassist(1M), vxedit(1M), vxintro(1M), vxmend(1M),
     vxtask(1M), vxvol(1M)

VxVM 3.0            Last change: 11 Dec 1998                    9

#  

