unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 vxplex(1M)			  VxVM 3.5			  vxplex(1M)
				 1 Jun 2002



 NAME
      vxplex - perform VERITAS Volume Manager operations on plexes

 SYNOPSIS
      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
      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:  August 2, 2006






 vxplex(1M)			  VxVM 3.5			  vxplex(1M)
				 1 Jun 2002



 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 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:  August 2, 2006






 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:  August 2, 2006






 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:  August 2, 2006






 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
      -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:  August 2, 2006






 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:  August 2, 2006






 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:  August 2, 2006






 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
      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:  August 2, 2006






 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:  August 2, 2006






 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, 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 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
      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:  August 2, 2006






 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
      /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:  August 2, 2006






 vxplex(1M)			  VxVM 3.5			  vxplex(1M)
				 1 Jun 2002



 EXIT CODES
      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
      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
      sync(1M), vxassist(1M), vxedit(1M), vxintro(1M), vxmend(1M),
      vxtask(1M), vxvol(1M)


























				   - 12 -	  Formatted:  August 2, 2006