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)