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

NAME

       volassist - Interface to create, mirror, back up, grow, shrink, and move LSM volumes

SYNOPSIS

       /sbin/volassist help [help_topic | showattrs | space]

       /sbin/volassist [options] [-b] make volume length [attribute...]

       /sbin/volassist [options] [-b] mirror volume [attribute...]

       /sbin/volassist [options] addlog volume [attribute...]

       /sbin/volassist [options] [-b] move volume [!]storage-spec... [attribute...]

       /sbin/volassist [options] [-b] growto volume newlength [attribute...]

       /sbin/volassist [options] [-b] growby volume lengthchange [attribute...]

       /sbin/volassist [options] shrinkto volume newlength

       /sbin/volassist [options] shrinkby volume lengthchange

       /sbin/volassist [options] [-b] snapstart volume [attribute...]

       /sbin/volassist [options] snapshot volume newvolume

       /sbin/volassist [options] snapwait volume

       /sbin/volassist [options] [-p] maxsize [attribute...]

       /sbin/volassist [options] [-p] maxgrow volume [attribute...]

OPTIONS

       The following are volassist options: 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 storage specification attributes (if any) for the volassist make operation, or based  on  the  volume
       operands  for  all  other  operations.  Limits the operation to apply to this usage type. Attempts to affect volumes with a different usage
       type will fail. For a volassist make operation, this indicates the usage type to use for the created volume. Otherwise, the default is used
       and is determined by the existence of an entry in the /etc/default/volassist file or is set to the fsgen usage type.  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  per-
       formance  impact  of copy operations.  Copy and plex consistency recovery operations are usually a set of short 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  spe-
       cific  delay  can be specified with iodelay as a number of milliseconds, or a default is chosen (normally 250 milliseconds).  Performs copy
       and recovery operations in regions with 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 typically between 32 and 256 kilobytes.  Performs extended operations in the background. This  applies	to
       plex  consistency  recovery operations for volassist make, growto, and growby.  This flag also applies to plex attach operations started by
       volassist mirror and volassist snapstart.  Specifies a file containing defaults for various attributes related to volume creation and space
       allocation.  Attribute  values  that  are  passed  in  through  this  file  will override any values specified in the system defaults file,
       /etc/default/volassist.	Forces certain operations that are disallowed by default to prevent their incorrect use. For example, this  option
       is  required  for a volassist growto, growby, shrinkto, or shrinkby operation.  This option is also required to create a RAID5 volume using
       the nolog attribute.  Limits the output of the maxsize and maxgrow operations to a numeric value only (no text). This option is mainly  for
       use in scripts.	Specifies that the system defaults file, /etc/default/volassist, should not be used when creating volumes.  Specifies ver-
       bose mode, printing a trace of other utilities that are called.

DESCRIPTION

       The volassist command is an LSM command that finds space for and creates volumes, adds mirrors and logs to existing  volumes,  extends  and
       shrinks	existing volumes, provides for the migration of data from specified disks, and provides facilities for the online backup of exist-
       ing volumes.

       volassist operations are applied to only one disk group at a time, which by default is the rootdg disk group.  Use the -g diskgroup  option
       to specify a disk group. You can specify a default disk group in the /etc/default/volassist file.

       Many  volassist operations use attributes to specify how volumes are laid out and on which disks, among other things. Attributes are of two
       basic types: storage specifications and attribute settings.

       Storage specification attributes consist of a simple disk media name (for example, disk01) or disk access name (for example, dsk5a). If the
       storage specification attribute is prefixed with !  (or, !  from csh), the specified disk or partition is excluded from the operation. For
       example, the command:

       /sbin/volassist make vol1 1000m !disk03

       creates a 1000MB volume on any non-volatile, non-reserved disk other than disk03.

       Other attributes are of the form attrname=value. These attributes specify the type of a volume (mirrored, RAID5, striped,  logged),  layout
       policies (contiguous, spanning), mirroring requirements and more. See KEYWORDS for a complete list of attribute specifications.

KEYWORDS

       volassit  keywords  are: Displays a list of help topic keywords that can be combined with volassist help to display detailed information on
       command usage, options, and attributes.

	      The volassist help showattrs keyword combination displays a list of current attribute settings.

	      The volassist help space keyword combination displays current disk allocation information.  Creates a volume with the specified name
	      and  the specified length. The length is specified as a standard Logical Storage Manager length (see volintro(8)). Attributes can be
	      specified to indicate various desired properties and storage locations for the created volume.

	      By default, a DRL is created when you create a mirrored volume and a RAID5 log is created when you create a RAID5 volume.

	      Use the layout=mirror,nolog option to create a mirrored volume with DRL disabled.  Creates a new mirror (or plex) and attaches it to
	      the  volume.  This operation is allowed only if the volume is enabled. You can specify attributes to indicate desired properties and
	      storage locations for the volume. A mirrored volume must have at least two plexes; one that contains the original  volume  data  and
	      one that contains a copy of the volume data. By default, a DRL is created for a mirrored volume.	The volassist command configures a
	      larger log subdisk for the DRL than needed. This allows you to use the volume if the system becomes a Tru64 UNIX cluster member.

	      If you change the default DRL size, for example using the loglen=length option, then the minimum DRL length for a  cluster  environ-
	      ment is 65 blocks and the minimum DRL length for a non-cluster environment is 2 blocks.

	      If  you configure a DRL size less than 65 blocks for a non-cluster environment, DRL is disabled for that volume if you later migrate
	      it to a cluster environment.

	      Use the layout=mirror,nolog option to create a mirrored volume with DRL disabled.  Moves subdisks within the named  volume  off  the
	      excluded storage specified on the command line. Excluded storage is specified with a prefix of !	(or, !  from csh). The move oper-
	      ation requires that at least one excluded storage specification be given.

	      If the volume is enabled, subdisks within detached or disabled plexes (or detached log or RAID5  subdisks)  will	be  moved  without
	      recovery	of  data.   If the volume is not enabled, stale log or RAID5 subdisks, or subdisks within STALE or OFFLINE plexes, will be
	      moved without recovery. If there are other subdisks within a non-enabled volume that require moving, the move operation will fail.

	      For enabled subdisks in enabled plexes within an enabled volume, the data within subdisks will be moved to the new location, without
	      loss  of	availability (or redundancy) of the volume.  Increases the length of the named volume to the length specified by newlength
	      (growto), or by the length specified by lengthchange (growby). The new length or change in length is specified as a standard Logical
	      Storage  Manager	length	(see  volintro(8)).  The  growto  operation fails if the new length is not greater than the current volume
	      length.

	      The length of the volume is increased by extending existing subdisks in the volume, or  by  adding  and  associating  new  subdisks.
	      Plexes that are not fully populated already (that is, that are sparse) are left unchanged. Log-only plexes are also left unchanged.

	      Attributes  can  be  specified  to indicate various desired properties for the new allocations. Any mirroring constraints will still
	      apply between all extensions to the existing mirrors and the other mirrors. Growing of a volume requires that the volume be enabled.

	      The volassist growto/growby operations have no effect on any file systems that reside on the volume (or other users of the  volume).
	      It is expected that any necessary application notifications will be made after the grow operation completes successfully.

									     Notes

	      File systems such as AdvFS and UFS cannot currently take advantage of an enlarged volume.

	      These  operations  are  currently disallowed by default to prevent their incorrect use with an existing AdvFS or UFS file system. To
	      override this default behavior and force the volume to grow, you must use the -f force option.  Decreases the length  of	the  named
	      volume  to  the  length specified by newlength (shrinkto), or by the length specified by lengthchange (shrinkby).  The new length or
	      change in length is specified as a standard Logical Storage Manager length (see volintro(8)). The shrinkto operation  fails  if  the
	      new length is not less than the current volume length.

	      The length of a volume is decreased by removing and shortening subdisks to leave each plex with the desired volume length. The freed
	      space can then be allocated for use by other volumes. Log-only plexes are left unchanged.

	      The volassist shrinkto/shrinkby operations have no effect on any file systems that reside on the volume (or other users of the  vol-
	      ume). It is expected that any necessary application notifications will be made before the shrink operation is initiated.

									     Notes

	      File systems such as AdvFS and UFS cannot currently take advantage of a shrunk volume.

	      These  operations  are  currently disallowed by default to prevent their incorrect use with an existing AdvFS or UFS file system. To
	      override this default behavior and force the volume to grow, you must use the -f force option.  Adds a log to a  mirrored  or  RAID5
	      volume.  A  log  can be added to a mirrored volume only if the logging type of the volume is DRL (this is the default logging type).
	      When adding the first log to a mirrored or RAID5 volume, you can use the loglen attribute to specify the length of the log.  If  you
	      don't  specify the loglen attribute, the volassist command uses a default log size. The minimum DRL length for a cluster environment
	      is 65 blocks and the minimum DRL length for a non-cluster environment is 2 blocks.

	      If you configure a DRL size less than 65 blocks for a non-cluster environment, DRL is disabled for that volume if you later  migrate
	      it to a cluster environment.

	      Another  log  added  to  the volume uses the loglen attribute of the first log. You can specify other attributes to indicate desired
	      properties for the new allocations. Mirroring constraints do not apply to logs, though storage constraints  can  be  specified  that
	      constrain  the logs to disks already used by the volume. However, for better performance, the DRL should not use disks that are cur-
	      rently used for volume data.

	      Adding a log to a DRL mirrored volume involves creating a single log subdisk and a new plex to contain that subdisk.  The  new  plex
	      will attach to the volume. Adding a log to a RAID5 volume involves creating a new plex that will attach to the volume as a log plex.
	      The addlog command automatically creates these objects.  Creates a temporary mirror and attaches it to the named volume.	 When  the
	      attach  completes,  the  mirror will be considered a candidate for selection by the snapshot operation. The snapshot operation takes
	      one of these attached temporary mirrors and creates a new volume with the  temporary  mirror  as	its  one  plex.  You  can  specify
	      attributes to indicate desired properties of the snapshot mirror.

	      Some  usage types will attempt to synchronize any in-memory data associated with the volume (such as unwritten file system modifica-
	      tions) when the snapshot operation is done. For UFS, the synchronization operation consists of a call to sync(8),  which	will  make
	      the  snapshot  a	better image, but which may leave some inconsistencies between in-memory file system data and the data residing on
	      the backup image.

	      To ensure data synchronization with AdvFS file systems, you must unmount the file systems before doing the snapshot operation.  If a
	      snapstart  mirror  attach  is  done as a background task (such as using the -b option), it may be convenient to wait for an attached
	      mirror to become available. The snapwait operation waits for such an attach to complete on the named volume. When a snapshot  attach
	      has  completed,  the operation exits.  Returns information on the maxiumum volume size that can be created from the available space,
	      given a particular set of attributes. When used with the -p option, maxsize returns a numeric value only.   Returns  information	on
	      the  maxiumum  amount  of  space	by which the specified volume can be extended and the maximum size to which it can grow, given the
	      available space and a particular set of attributes. When used with the -p option, maxgrow returns a numeric value  only,	indicating
	      the maximum size to which the volume can grow.

ATTRIBUTES

       You  can specify attribute values for various purposes with arguments of the form attribute=value. Attributes can also be passed in through
       a defaults file.  Default attribute values can be stored in the file /etc/default/volassist.

       Attributes are selected according to the order in which they are scanned.  If conflicting attributes are specified, the last one  specified
       takes  precedence and is used. In general, attributes are taken in decreasing priority of being specified on: The command line.	The speci-
       fied defaults file (as supplied with the -d command line argument).  The system defaults file (as specified in /etc/default/volassist).

       Attributes from all sources have the same form. However, in some cases, command-line attributes	change	default  behaviors  in	ways  that
       defaults-file  supplied	attributes  do not. In particular, references to mirroring (such as specifying a mirror count) or logging (such as
       specifying a log count or length) on the command line will cause mirroring or logging to happen by default.  If such attributes are  speci-
       fied in a defaults file, they just indicate the attributes that would be used if mirroring or logging were enabled.

       Attributes  are	either	storage  specifications (possibly negated), or are in the form attribute=value. In a defaults file, attributes are
       whitespace-separated or are on separate lines. Blank lines in a defaults file are ignored, and comments can be included with the standard #
       convention.

   Storage Specifications
       Storage	specification attributes have one of the following forms: Specifies (or excludes) the given disk. The diskname parameter refers to
       a disk media record name in a Logical Storage Manager disk group.  Specifies (or excludes) a specific Logical Storage Manager disk by  disk
       access  record  name.  An  example of a disk access record name is dsk5a, which indicates a special Logical Storage Manager disk defined on
       partition a of disk dsk5.  Specifies (or excludes) all LSM disks on a specific physical disk. The physical disk is specified  in  the  form
       dsk#,  which  indicates	the disk number. Normally, only one LSM disk device is created for each physical disk. However, the voldisk define
       operation (see voldisk(8)) can be used to create additional LSM disk devices on selected partitions.  Specifies	(or  excludes)	a  Logical
       Storage Manager disk by disk media record name, in the disk group of the volume.

   Other Attributes
       Other attributes are of the form attribute=value. The attribute name in an attribute value pair will never contain a colon, so it is possi-
       ble to specify a disk that has an equal sign in its name using the storage specification dm:disk01=a.  Without  the  dm:  prefix,  disk01=a
       would yield an error indicating an unrecognized attribute.

       Defined	attributes  (and  common  aliases) are: This is provided as an alternate syntax for specifying storage as single attributes. It is
       useful in a defaults file, so that all attributes (including storage specifications) will be in the attribute=value format. Any	number	of
       storage	specifications can be specified, separated by commas. More than one alloc attribute can be specified, in which case they are logi-
       cally concatenated to form one longer list.  Specifies a comment to give to a volume when it is created.  This  comment	can  be  displayed
       with  volprint  -l,  and can be changed, at a later time, with voledit set. This attribute is used only with the make operation.  Specifies
       the disk group for an operation.  If a disk group is specified in a defaults file, it just specifies the default disk group to use for  the
       make  operation,  if  no  other	means of determining the disk group can be used. If specified as a command line attribute, it has the same
       effect as specifying a disk group with the -g option (the operation is forced to apply to the given disk group).  Sets the owning group for
       a  new  volume. The group can be specified numerically or with a system group name. This attribute is used only with the make operation. By
       default, volumes are created in group 0.  Specifies the means for initializing a new volume. The default  method  (which  can  be  selected
       explicitly  with  init=default)	is  to call volume start to do a usage-type-specific default initialization operation. A new volume can be
       left uninitialized with init=none. The most useful non-default initialization that can be specified  is	init=zero,  to	clear  the  volume
       before enabling it for general use.

	      Another  useful  initialization is init=active. This is used when creating a mirrored volume to indicate that the plexes do not need
	      an initial synchronization. This could be to save time prior to creating a file system when the contents of the volume  are  guaran-
	      teed  to	be written before being read.  Specifies a volume or plex layout type (concatenated, RAID5, mirrored, unmirrored, striped,
	      and others) and turns on or off some features (such as logging). By default, unmirrored, non-striped volumes  are  created  with	no
	      log.

	      See  the	next section ("Layout Specifications") for the defined layout-spec values.  Specifies a log length to use for dirty region
	      log subdisks for mirrored volumes or for RAID5 log plexes. If a log length is specified on the command line, logging is  enabled	by
	      default.	 Specifies  the  logging  type	for a mirrored volume. Dirty region logging (the default) can be selected with either log-
	      type=drl or logtype=region. To disable logging, enter: logtype=none.  Specifies the default maximum number of stripe columns  for  a
	      RAID5  volume  (default  value:  8).   Specifies	the  default  maximum  number  of  stripe  columns,  either for a RAID5 volume (if
	      max_nraid5stripe is omitted) or for a striped plex (default value: 8).  Specifies the maximum default dirty region log (DRL) subdisk
	      length.  If you do not specify the DRL length for a volume, when creating the first log for a mirrored volume, volassist uses a sim-
	      ple formula based on the log length. The default length will not be overridden by max_regionloglen (default value: 32K).	 Specifies
	      the  minimum  number  of	stripe	columns for a RAID5 volume. The default is 3 columns. The policy for selecting a default number of
	      RAID5 stripe columns is not to allow a RAID5 volume to have fewer than min_nraid5stripe stripe columns. The minimum number  of  col-
	      umns  that you can have is 3.  Specifies the default minimum number of stripe columns for either a RAID5 volume (if min_nraid5stripe
	      is omitted) or for a striped plex (default value: 2). The policy for selecting a default number of stripe columns is  not  to  allow
	      fewer  than this number of columns.  Specifies mirroring parameters. A decimal number indicates a specific number of mirrors to cre-
	      ate, when creating a mirrored volume (equivalent to nmirror=number). A value of yes indicates that volumes  should  be  mirrored	by
	      default  (equivalent  to	layout=mirror).   A value of no indicates that volumes should be unmirrored by default (equivalent to lay-
	      out=nomirror).  Specifies the permissions for the block and character device nodes created for a new volume. The mode can be  speci-
	      fied  either  as an octal number or symbolically. A symbolic mode is specified using the syntax given in chmod(1). This attribute is
	      used only with the make operation. The default mode for a volume gives read and write access only to the owner.  Specifies the  num-
	      ber  of logs to create, by default, for a RAID5 or mirrored volume (presuming that logs will be created). The number of logs to cre-
	      ate can be specified independently for RAID5 or mirrored volumes using the nraid5log and nregionlog attributes.  Specifies the  num-
	      ber  of  mirrors to create when mirroring a volume (default value: 2).  Specifies the number of log plexes to create for a new RAID5
	      volume (default value: 1). This attribute is used only with the make operation.  Specifies the number of stripe columns to use  when
	      creating	a  new	RAID5  volume  (the default is to adjust the number to available disks). This attribute is used only with the make
	      operation.  Specifies the number of log subdisks to create for a new mirrored volume (default value 1). This attribute is used  only
	      with the make operation, and only if logging is requested for the volume.  Specifies the number of stripe columns to use when creat-
	      ing a new RAID5 volume (with the make operation) or when creating a striped plex (with the make, mirror, and snapstart  operations).
	      The default is half of the candidate disks, adjusted to a number between 2 and 8.  Specifies the stripe unit size to use when creat-
	      ing a new RAID5 volume (default value: 16K).  This attribute is used only with the make operation.  Specifies the log length to  use
	      when  adding  the first log to a RAID5 volume. The default is ten times the full stripe width (the stripe unit size times the number
	      of stripe columns).  Specifies the log subdisk length to use when adding the first log subdisk to a mirrored volume. The default	is
	      chosen based on a formula involving the volume length.  Specifies the stripe unit size to use when creating striped plexes to attach
	      to a volume.  When attaching a new plex, the default is to use the same stripe unit size as any other striped plexes in the  volume.
	      If  the  volume  does  not yet contain striped plexes, the default value is 64K.	Specifies the stripe unit size to use for either a
	      RAID5 volume or for striped plexes.  This attribute can be used to set the values for both raid5_stripeunit  and	stripe_stripeunit.
	      Specifies  the owning user for a new volume (default value: root). The user can be specified numerically or it can be a system login
	      name. This attribute is used only with the make operation.  Specifies the usage type to use when creating a new volume with the make
	      operation  (default  value: raid5 for RAID5 volumes; fsgen, otherwise). The usage type can also be specified in the option list with
	      -U.  Specifies a set of desired storage specifications. This is useful in a defaults file to indicate desired storage specifications
	      that should be discarded if they fail to yield a reasonable set of allocations. The format is the same as for the alloc attribute (a
	      comma-separated list of storage specifications).

   Layout Specifications
       The layout attribute specifies a comma-separated list of parameters (with no arguments) that define how the  volassist  command	creates  a
       volume.

       Layout specifications are: Specifies whether or not the volumes should use concatenated plexes. The default is to use concatenated volumes.
       Specifies whether or not the volumes uses mirrored plexes or RAID 5 plexes. The default is create the  volume  without  mirror  or  RAID  5
       plexes.	 When creating a new volume or adding a plex to a volume that does not have a striped plex, the default is nostripe. When adding a
       new plex to a volume that has a striped plex, the default is stripe.  Allows (default) or disallows  plexes,  stripe  columns,  or  RAID  5
       stripe  columns to span multiple disks. If nospan is indicated, plexes or columns can be formed from multiple regions of the same disk, but
       cannot be formed from more than one disk.  Disallows or allows (default) plexes, stripe columns, or RAID 5 stripe columns to  use  multiple
       regions of disk. If contig is specified, plexes and columns must be allocated from a single contiguous region of disk.  If this is not pos-
       sible, the allocation fails. By default, the volassist command tries to allocate space contiguously, but will use multiple regions or  mul-
       tiple disks if needed.  Creates (default) or doesn't create a DRL or RAID 5 log plex. You can specify this attribute independently for vol-
       umes that use mirrored and RAID 5 plexes by using the raid5log and regionlog layout specifications. You must use the -f option to create  a
       volume  that  uses  a  RAID  5 plex with the nolog attribute.  Creates (default) or doesn't create log plexes for volumes that use a RAID 5
       plex. The -f option must be used with noraid5log to override the default behavior.  Creates (default) or doesn't create a DRL  for  volumes
       that use mirror plexes.

EXIT CODES

       The  volassist command 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 command.

       See volintro(8) for a list of standard exit codes.

FILES

       System default settings file for volassist attributes. This is an optional, user-created file that resides in the  /etc/default	directory,
       which is also user-created.

SEE ALSO

       volintro(8), voledit(8), volmake(8), volmend(8), volplex(8), volsd(8), volume(8)

																      volassist(8)