unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



volplex(8)							   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] cp 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] [-v volume] mv
  oldplex newplex

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

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

OPTIONS

  The following	options	are recognized:

  -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.

  -U usetype
      Limits the operation to apply to this usage type.	Attempts to affect
      volumes with a different usage type will fail.

  -o useopt
      Passes in	usage-type-specific options to the operation. The following
      operations are implemented by all	usage types:

      slow[=iodelay]
	  Reduces the system performance impact	of copy	operations.  Copy
	  operations are usually performed in series 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 mil-
	  liseconds; otherwise,	a default is chosen (normally 250 mil-
	  liseconds).

      iosize=size
	  Changes the copy region size to the length specified by size,	which
	  is a standard	Logical	Storage	Manager	length number (see volin-
	  tro(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.

      rm  Removes the plexes after successful completion of a plex dissocia-
	  tion operation. Removes the source plex after	successful completion
	  of a plex move operation.

  -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 volplex, along
      with the arguments that would be passed. The -V option performs a	"mock
      run" so the utilities are	not actually called.

  -f  Forces an	operation that the Logical Storage Manager considers poten-
      tially 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 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, 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:

  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 suc-
      cessful 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.

  cp  Copies the named volume to the named plexes. The volume cannot be	dis-
      abled, and the named plexes must not already be associated to any
      volume. The result of the	operation is a set of dissociated plexes that
      are an exact copy	of the volume at the time of completion	of the opera-
      tion. The	rules for performing the copy 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 pur-
      poses, 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 inaccessi-
      ble 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.

  mv  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 replace-
      ment of the old 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.

  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. After the operation completes,
      you 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 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 dif-
      ficult to	know when it will complete. Also, directly converting the
      plex into	a new volume is	more convenient	than requiring additional
      steps.




FSGEN AND GEN USAGE TYPES

  The fsgen and	gen usage types	provide	similar, though	not identical, seman-
  tics for all operations of the volplex utility. In particular, the fsgen
  usage	type will attempt to flush in-memory data cached for a 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, 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 you may need to perform some cleanup.  The specific
  cleanup actions 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:

  force
      Forces an	operation that the Logical Storage Manager considers poten-
      tially 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.  -o force
      is the same as -f.

  rerr
      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.

  werr
      Ignores plex write errors	when copying data onto a plex. A warning mes-
      sage 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.

  mapzero
      If you move or copy a sparse plex	(one that has no subdisk behind	one
      or more regions of the plex) to a	new plex that does have	subdisks
      behind the corresponding sparse regions of the source plex, this flag
      zeroes out that mapped region in the destination plex. Without this
      flag, the	mapped region may be left unchanged from its original con-
      tents.

  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 volume start or
      volume 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. Volume	logging	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.

  cp  The fsgen	and gen	usage types do not add any specific restrictions to
      the cp operation.

  dis and det
      Detaching	or dissociating	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 sparse, enabled, read-write
      plexes. In other words, a	volume cannot be left with two enabled,
      sparse 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 remove	plexes from a
      volume such that it is left with only one	enabled, read-write, sparse
      plex, or with 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 reat-
      tached automatically.

  mv  If either	the source or destination plex (or both) is sparse, the
      sparse regions must align	(must both occur in the	same respective	block
      addresses	within the plexes). If they do not, or if the destination
      plex is shorter than the source plex, 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.

RAID 5 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 the Logical Storage Manager considers poten-
      tially dangerous or of questionable use. This applies to attempts	to
      dissociate the RAID 5 data plex of a non-EMPTY volume or to remove the
      last RAID	5 log plex of a	non-EMPTY volume. This flag is the same	as
      -f.

  As with other	usage types, if	a volplex operation is interrupted by a	sig-
  nal, 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 you may need to perform some
  cleanup. The specific	cleanup	actions	needed are written to the standard
  error	before volplex 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 raid5,	the plex will be attached as the RAID 5	data plex of the
      volume. To attach	a RAID 5 plex to the volume, the volume	must be	dis-
      abled and	be in the EMPTY	state, and the RAID 5 plex will	be given a
      state of EMPTY. Only one RAID 5 data plex	can be attached	to a RAID 5
      volume.

      If a plex	has a layout other than	raid5, the plex	will be	attached as a
      RAID 5 log plex for the 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, another log	plex can be attached only if it	is at least as long
      as the shortest log plex already attached	to the volume. 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. 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 data 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,	mv,
  snapstart, or	snapshot keywords; these operations are	either inappropriate
  or impossible	to perform within the operational concepts of RAID 5.

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

  /sbin/lsm.d/usetype/volplex
      The utility that performs	volplex	operations for a particular volume
      usage type.

  /sbin/lsm.d/fsgen/fs.d/fstype/volsync
      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 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)