volplex(8)						      System Manager's Manual							volplex(8)

NAME

       volplex - Perform Logical Storage Manager operations on plexes

SYNOPSIS

       /sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] att volume plex...

       /sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] det plex...

       /sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] dis plex...

       /sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] cp volume plex...

       /sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] snapstart volume plex

       /sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] snapshot plex newvolume

       /sbin/volplex [-Vf] [-g diskgroup] [-U usetype] [-o useopt] [-v volume] mv oldplex newplex

OPTIONS

       The  following  options	are  recognized:  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.  Limits the operation to apply to this usage type. Attempts to affect volumes
       with a different usage type will fail.  Passes in usage-type-specific options to the operation. A certain set of operations are expected to
       be implemented by all usage types: Reduces the system performance impact of copy operations.  Copy operations are usually a  set  of  short
       copy  operations  on  small  regions  of  the volume (normally from 16 kilobytes to 256 kilobytes). This option inserts a delay between the
       recovery of each such region. A specific delay can be specified with iodelay as a number of milliseconds; otherwise, a  default	is  chosen
       (normally  250  milliseconds).	Performs copy operations in regions with the length specified by size, which is a standard Logical Storage
       Manager length number (see volintro(8)). Specifying a larger number typically causes the operation to complete  sooner,	but  with  greater
       impact  on  other  processes using the volume.  The default I/O size is 256 kilobytes.  Removes the plexes after successful completion of a
       volplex dis operation. Removes the source plex after successful completion of volplex mv.  Requires that the plex named by a plex  or  old-
       plex  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.  Displays a list of utilities that would be called from volplex, along with the arguments that would be
       passed.	The -V option performs a ``mock run'' so the utilities are not actually called.  Forces an operation that the Logical Storage Man-
       ager considers potentially dangerous or of questionable use. This permits a limited set of operations that would otherwise  be  disallowed.
       Some operations may be disallowed even with this flag.

DESCRIPTION

       The  volplex utility performs Logical Storage Manager operations on plexes and on volume-and-plex combinations. The first operand is a key-
       word that determines the specific operation to perform. The remaining operands specify the configuration objects to which the operation	is
       to be applied.

       Each  operation	can  be  applied to only one disk group at a time, due to internal implementation constraints. Any volume or plex operands
       will be used to determine a default disk group, according to the standard disk group selection rules described in volintro(8).  A  specific
       disk group can be forced with -g diskgroup.

KEYWORDS

       These are the recognized operation keywords: 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 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.  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.	Dissociates each of the named plexes. Dis-
	      sociating 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 volplex att or with volmake. Any checks and synchronizations that apply to the det operation also apply to
	      the dis operation.

	      Plex dissociation is the normal means of unmirroring a volume, or reducing the mirror count for a volume. To support this 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 allocations (such as with volassist or with volmake).

	      Plex dissociation can also be used for file system backups of volumes that are normally mirrored. To support  backup  programs  that
	      require a mounted file system, a plex can be dissociated and then allocated to a new volume, such as with the command:

	      volmake -U gen vol volume plex=plex

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

									      Note

	      This backup procedure cannot be used for AdvFS.  Copies the named volume to the named plexes. The volume cannot be disabled, and the
	      named plexes must not be associated while the command is running. The results of the operation will be a set of  dissociated  plexes
	      that  are  an  exact copy of the volume at the time of completion of the operation.  The rules for performing the 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 consis-
	      tent 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.  These two
	      operations form the two parts of a preferred means of copying a volume to a  plex  for  backup  purposes.  The  snapstart  operation
	      attaches a plex to a volume and, when the operation is complete, leaves the plex associated as a temporary plex. After the operation
	      completes, the administrator can convert the plex attached by snapstart into a new volume using volplex  snapshot.  To  improve  the
	      quality of the copies, some usage types attempt to make the detached plex consistent with respect to in-memory data.

	      This method of backup is preferable to using volplex cp because it allows 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 difficult to know when it will complete. Also, directly converting the plex into a new volume is more con-
	      venient than requiring additional steps.	Attaches the plex newplex to the volume that oldplex is associated  with  and  dissociates
	      oldplex.	The volume cannot be disabled, and newplex must name a dissociated plex. The operation ensures seamless replacement of the
	      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.

FSGEN AND GEN USAGE TYPES

       The  fsgen  and	gen usage types provide similar, though not identical, semantics for all operations of the volplex utility. In particular,
       the fsgen usage type will attempt to flush in-memory data cached for the file system residing on the volume. For most  file  systems,  this
       consists of calling sync to attempt to flush all in-memory data to disk.

       If  a  volplex  operation  is  interrupted  by a signal, 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 volplex exits.

       The  fsgen  and	gen  usage types provide the following options as arguments to -o in addition to the required options: Forces an operation
       that the Logical Storage Manager 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.
       Ignores volume or plex read errors when copying data onto a plex. A warning message is written to standard error if a  read  error  occurs,
       but  the error does not affect success of the operation. This operation can be used only with the cp operation; the operation is ignored if
       used with other operations.  Ignores plex write errors when copying data onto a plex. A warning message is written to standard error  if  a
       write  error  occurs,  but  the	error does not affect success of the operation. This operation can be used only with the cp operation; the
       operation is ignored if used with other operations.  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, this flag zeroes out that mapped region in the
       destination plex. Without this flag, the mapped region may be left unchanged from its original contents.

       Limitations and extensions for the fsgen and gen usage types consist of the following: If the volume is enabled and one of the named plexes
       is associated with the volume, then the plex must be STALE, EMPTY, ACTIVE, or OFFLINE.  If the operation succeeds in attaching a plex, then
       any I/O fail condition for the plex is cleared. Also, attaching to an enabled volume requires that the volume have at  least  one  enabled,
       read-write plex.

	      If  the  volume  is not enabled, then the named plexes are associated with the volume (if not already associated) and are set to the
	      STALE state, so that the plex will be fully attached by the next volume start or volume startall operation that applies to the  vol-
	      ume.

	      If  the  log  type  of the volume is UNDEF and an unassociated plex with a log subdisk is attached, the volume is automatically con-
	      verted 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 voledit set to set the putil0 field to a non-empty string. The putil0 field can then be cleared with  either  voledit  set	or
	      with  volmend  clear putil0.  A detach or dissociate of a plex in an enabled volume fails if applied to a plex that is the last com-
	      plete, 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 automatically.  The fsgen and gen usage types do not add any specific restrictions to the cp operation.	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 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 arguments to -o in addition to the required options: Forces an operation that the
       Logical Storage Manager considers potentially dangerous or of questionable use. This applies to attempts to dissociate the RAID5 plex of  a
       non- EMPTY volume or to remove the last RAID5 log plex of a non- EMPTY volume.

       As  with other usage types, if a volplex operation is interrupted by a signal, then an attempt is made to restore the disk group configura-
       tion 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 volplex exits.

       The  raid5  usage type supports only the following keywords: Attaches the named plexes to the named volume. If a plex has a layout of RAID,
       the plex will be attached as the RAID5 plex of the RAID5 volume. To attach a RAID5 plex to the volume, the volume must be disabled  and	be
       in the EMPTY state, and the RAID5 plex will be given a state of EMPTY.

	      If  a  plex  has	a layout other than RAID, the plex will be attached as a RAID5 log plex for the RAID5 volume. If the volume has no
	      RAID5 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. RAID5 log plexes cannot be sparse in respect to the volume's log length; attempts to attach a sparse log plex will fail.

	      If the RAID5 volume is not enabled, log plexes are attached and marked as STALE. If the RAID5 volume  is	enabled  and  has  no  log
	      plexes, attaching a log plex will cause plexes being attached as log plexes to be zeroed before they are enabled. Otherwise, the new
	      log plexes are attached write-only and the contents of the existing log plexes are copied to the new log	plexes	using  ATOMIC_COPY
	      ioctls,  after which the logs are enabled.  Dissociates the named plex from the RAID5 volume to which it is attached. If the plex is
	      the RAID5 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 RAID5 volume with no usable log plexes, the -o force option is
	      required.

       Note that the RAID5 usage type does not support the det, cp, snapstart, snapshot or copy keywords; these operations are either  inappropri-
       ate or impossible to perform within the operational concepts of RAID5.

EXIT CODES

       The  volplex  utility  exits with a nonzero status if the attempted operation fails. A nonzero exit code is not a complete indicator of the
       problems encountered but rather denotes the first condition that prevented further execution of the utility. See volintro(8) for a list	of
       standard exit codes.

FILES

       The utility that performs volplex operations for a particular volume usage type.  Path to a program used with the fsgen usage type for syn-
       chronizing in-memory file system data with a volume, for the file system type fstype. The program is given arguments of a volume  name  and
       one or more plex names. For the ufs and AdvFS file system types, this is a link to sync.

SEE ALSO

       sync(8), volintro(8), volassist(8), voledit(8), volmend(8), volume(8)

																	volplex(8)