vxassist - create, mirror, backup, grow, shrink, and move volumes
vxassist [options] [-b] make volume length [attribute...]
vxassist [-b] [options] mirror volume [attribute...]
vxassist [options] [-b] move volume !storage-spec... [attribute...]
vxassist [options] [-b] growto volume newlength [attribute...]
vxassist [options] [-b] growby volume lengthchange [attribute...]
vxassist [options] shrinkto volume newlength
vxassist [options] shrinkby volume lengthchange
vxassist [options] [-b] snapstart volume [attribute...]
vxassist [options] snapshot volume newvolume
vxassist [options] snapwait volume
The vxassist utility is an interface to the VERITAS Volume Manager 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 a specified set of disks, and provides facilities for the on-line backup of existing volumes.
The vxassist command is supplied a keyword that selects the action to perform.
Each operation can be applied to only one disk group at a time, due to internal implementation constraints. For the make operation, attributes that name specific disks may be used to determine a default disk group, according to the standard disk group selection rules described in
For other operations, the volume operand is used. A specific disk group can be forced with -g diskgroup. When no disk attributes are specified, the make operation defaults to using the rootdg disk group. An alternate default disk group can be specified in a defaults file (/etc/default/vxassist).
Many vxassist operations can take a set of attributes that specify how volumes should be laid out, which sets of disks they should be built on, among other things. Attributes are of two basic types: storage specifications, and attribute settings. Storage specification attributes are either simple disk names (e.g., disk01) or selected groups of disks (e.g., ctlr:c1 specifies all disks on controller 1). Excluded (negated) storage specification can be specified with a prefix of !. For example, the arguments ctlr:c1 and !target:c1b0t5 can be combined to indicate that storage should be allocated from controller 1, but not from SCSI target 5 on that controller.
Other attributes are of the form attrname=value; these additional attributes can specify the type of a volume (mirrored, RAID-5, striped, logged), layout policies (contiguous, spanning), mirroring requirements (mirror across controllers or SCSI targets), constraint parameters (constrain allocations to a single controller), and more. A complete list of attribute specifications is given later in this man page.
If no non-excluded storage specification attributes are given, then any non-reserved, non-volatile, non-spare, non-excluded disk may be used to allocate storage. Attributes may constrain the selection, particularly with respect to the selection of multiple disks. For example, the command:
vxassist make mirvol 500m layout=mirror,log mirror=ctlr !ctlr:c2
requests that vxassist create a new mirrored volume on any disks that are not on controller 2. The selection of disks is constrained by the mirror=ctlr attribute such that no disks within a mirror can be on the same controller as any disks on the other mirror.
The recognized operation keywords are:
- Create a volume with the specified name and the specified length. The length is specified as a
standard Volume Manager length (see
Attributes can be specified to
indicate various desired properties and storage locations for the created volume.
- Create a new mirror (or plex) and attach it to the volume. This operation is allowed only if the
volume is enabled. Attributes can be specified to indicate various desired properties and
storage locations for the created volume. Attributes that constrain mirroring (such as
requiring that mirrors be on separate groups of disks) apply between the existing mirrors of
the volume and the new mirror.
- Move subdisks within the named volume off the excluded storage specified on the command line.
Excluded storage is specified with a prefix of !. The move operation requires that at least
one excluded storage specification be given.
- If the volume is enabled, then subdisks within detached or disabled plexes (or detached log or RAID-
5 subdisks) will be moved without recovery of data. If the volume is not enabled, then stale
log or RAID-5 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, then 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.
- growto and growby
- Increase 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 Volume Manager length
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 (i.e., 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.
- No attempt will be made by vxassist to adapt the file system that resides 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.
- shrinkto and shrinkby
- Decrease 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 Volume Manager length
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.
- No attempt will be made, by vxassist to adapt the file system that resides on the volume (or other
users of the volume). It is expected that any necessary application notifications will be
made before the shrink operation is initiated.
- Add a log to a mirrored or RAID-5 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 RAID-5 volume, the loglen attribute can be used to specify the length
of the log; otherwise, the loglen attribute will be ignored. Other attributes can be specified
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 disk sets
already used by the volume.
- 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 then be attached to the volume. Adding a log to a
RAID-5 volume involves creating a new plex that will be attached to the volume as a log
- snapstart and snapshot
- Create a temporary mirror and attach 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. Attributes can be specified 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 modifications) when the snapshot operation is done. In particular,
if the fsgen usage type is used with a volume containing a VxFS file system, then
cooperating procedures ensure that all file system data is consistently flushed to the
volume. For ufs and s5, the synchronization operation consists of a call to
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.
- 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.
- -g diskgroup
- Specify 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 medianame operands (if any) for the vxassist make
operation, or based on the volume operands for all other operations.
- -U usetype
- Limit the operation to apply to this usage type. Attempts to affect volumes with a different usage
type will fail. For a vxassist 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/vxassist file or else is set to the fsgen usage type.
- -o useopt
- Pass in usage-type-specific options to the operation. A certain set of operations are expected to be
implemented by all usage types:
- Reduce the system performance 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 specific delay can be specified with
iodelay as a number of milliseconds, or a default is chosen (normally 250
- Perform copy and recovery operations in regions with the length specified by size, which
is a standard Volume Manager length number
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 128 kilobytes.
- Perform extended operations in the background. This applies to plex consistency recovery
operations for vxassist make, growto, and growby. This flag also applies to plex attach
operations started by vxassist mirror and vxassist snapstart.
- -d defaults
- Specify a file containing defaults for various attributes related to volume creation and space
allocation. If not specified, this defaults to /etc/default/vxassist.
Attribute values for various purposes can be specified 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/vxassist.
Attributes are selected according to the order in which they are scanned. In general they are taken in decreasing priority of being specified on:
1. The command line.
2. The specified defaults file. (as supplied with the -d command line argument)
3. The system defaults file. (as specified in /etc/default/vxassist)
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 specified in a defaults file, then 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 specification attributes have one of the following forms:
The defined disk classes (and alternate names, or aliases, for those classes) are as follows:
- Specify (or exclude) the given disk. diskname refers to a disk media record name in a Volume
Manager disk group.
- Specify (or exclude) a set of disks. diskclass names a particular type of disk grouping (for example,
ctlr to indicate groups of disks on a single controller), and instance specifies which
grouping of that type (for example c1). Each type of disk class has a particular format for
specifying instances of the class.
- Specify that the allocation must be constrained to include disks from the same instance of the given
class. For example, a storage specification of diskparam:same indicates that all disks
selected must have the same basic parameters (tracksize, cylinder size, size, and
revolutions-per-minute), but does not specify which specific parameters to use.
The diskgeom and diskparam attributes are most often useful in the form diskgeom:same and diskparam:same, to indicate that all disks used for creating a volume should be on similar disk drives.
- ctlr (alias c)
- Specify disks from a particular controller. The controller is identified in the form c#, where # is a
decimal controller number starting at 0.
- Specify a specific Volume Manager disk by disk access record name. An example of a disk access
record name is c1b0t5d0s6, which indicates a special Volume Manager disk defined on
slice 6 of disk c1b0t5d0.
- device (alias d)
- Specify all Volume Manager disks on a specific physical disk. The physical disk is specified in the
form c#b#t#d#, which indicates the controller, bus id., target, and disk numbers. Normally,
only one Volume Manager disk device is created for each physical disk. However, the
vxdisk define operation [see vxdisk(ADM)] can be used to create additional Volume
Manager disk devices on selected partitions.
- diskgeom (alias geom)
- Specify disks with a particular geometry. The geometry is specified in the form cyls.heads.sectors,
to indicate the number of cylinders, heads, and sectors per track, of the disk. Many modern
drives have variable geometries (or geometries that don't fit the standard conventions). For
such drives, the geometry parameters used are whatever the drive reports.
- Specify disks with particular parameters. The parameters are specified in the form
cyls.heads.sectors.rpm, to indicate cylinders, heads, sectors per track, and the number of
revolutions per minute of the drive. As with the diskgeom parameter, the instances of the
diskparam disk class depend upon the values reported by the drive, and may not be
- diskrm (alias rpm)
- Specify disks with a particular number of revolutions per minute. The revolutions per minute is
given as a simple decimal number.
- dm (alias disk)
- Specify a Volume Manager disk by disk media record name, in the disk group of the volume.
Specifying a disk class type of dm or disk is equivalent to giving a storage specification
with no disk class name.
- target (alias t)
- Specify disks on the same SCSI target address in the same controller. The target is specified in the
form c#b#t#. For example, t:c2b0t4 selects disks on target 4 of controller 2.
Other attributes are of the form attribute=value. The attribute name in an attribute value pair will never contain a colon, so it is possible 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 logically
concatenated to form one longer list.
- Specify a comment to give to a volume when it is created. This comment can be displayed with
vxprint -l, and can be changed, at a later time, with vxedit set. This attribute is used only
with the make operation.
- diskgroup=disk-group (alias: dg)
- Specify the disk group for an operation. If a disk group is specified in a defaults file, then 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).
- Specify the file system type for a new volume (this is used only with the make operation). The file
system type for a volume is usually determined when needed by running the fstyp utility
but can be specified explicitly. The file system type parameter is used the
with Volume Manager vxresize utility, as well as with volume snapshots, copies, and
dissociates (to select features that are used with the VERITAS VxFS file system).
- The file system type can be changed at any later time with the vxedit set operation.
- Set 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.
- Specify the means for initializing a new volume. The default method (which can be selected
explicitly with init=default) is to call vxvol start to do a usage-type-specific default
initialization operation. A new volume can be left unintialized 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.
- Specify a volume or plex layout type (RAID-5, mirrored, unmirrored, striped, cylinder alignment,
etc), and turn on or off some features (such as logging). The list of layout specifications is
given in the next section. By default, unmirrored, non-striped volumes are created with no
- Specify a log length to use for dirty-region log subdisks for mirrored volumes or for RAID-5 log
plexes. If a log length is specified on the command line, then logging will be enabled by
- Specify the logging type for a mirrored volume. Dirty region logging (the default) can be selected
with either logtype=drl or logtype=region. Logging can be disabled altogether with
- max_nraid5column=number (alias: maxraid5columns)
- Specify the default maximum number of stripe columns for a RAID-5 volume (default value: 8). The
rules for selecting the default number of RAID-5 stripe columns are described later.
- max_ncolumn=number (alias: maxcolumns)
- Specify the default maximum number of stripe columns, either for a RAID-5 volume (if
max_nraid5stripe is not also specified) or for a striped plex (default value: 8). The rules
for selecting the default number of stripe columns is described later.
- max_regionloglen=length (alias: maxregionloglen)
- Specify the maximum default dirty region logging log subdisk length. If the user does not specify
the dirty region log length for a volume, when creating the first log for a mirrored volume,
vxassist uses a simple formula based on the log length. The default length will not be
bounded by max_regionloglen (default value: 32K).
- min_nraid5column=number (alias: minraid5columns)
- Specify the default minimum number of stripe columns for a RAID-5 volume (default value: 3). The
policy for selecting a default number of RAID-5 stripe columns will not be allowed to
create a RAID-5 volume with fewer than min_nraid5stripe stripe columns.
- min_nstripe=number (alias: minstripes)
- Specify the default minimum number of stripe columns for either a RAID-5 volume (if
min_nraid5stripe is not also specified) or for a striped plex (default value: 2). The policy
for selecting a default number of stripe columns will not be allowed to select fewer than
this number of columns.
- Specify various mirroring parameters. Multiple mirroring parameters can be given, each separated
by a comma. A decimal number indicates a specific number of mirrors to create, when
creating a mirrored volume (equivalent to nmirror=number). yes indicates that volumes
should be mirrored by default (equivalent to layout=mirror). no indicates that volumes
should be unmirrored by default (equivalent to layout=nomirror).
- Any other mirroring parameters specify that volumes should be mirrored across instances of a
particular disk class. For example, mirror=target specifies that volumes should be
mirrored between SCSI target addresses. Each mirror can contain disks from any number
of instances of the disk class, but different mirrors cannot use disks from the same instance
of the disk class.
- Specify the permissions for the block and character device nodes created for a new volume. The
mode can be specified either as an octal number or symbolically. A symbolic mode is
specified using the syntax given in
This attribute is used only with the make
operation. The default mode for a volume gives read and write access only to the owner.
- Specify the number of logs to create, by default, for a RAID-5 or mirrored volume (presuming that
logs will be created). The number of logs to create can be specified independently for
RAID-5 or mirrored volumes using the nraid5log and nregionlog attributes.
- Specify the number of mirrors to create when mirroring a volume (default value: 2).
- Specify the number of log plexes to create for a new RAID-5 volume (default value: 1). This
attribute is used only with the make operation.
- nraid5stripe=number (alias: raid5stripes)
- Specify the number of stripe columns to use when creating a new RAID-5 volume (the default is to
adjust the number to available disks). This attribute is used only with the make operation.
- Specify 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
- nstripe=number (alias: stripes, ncolumn)
- Specify the number of stripe columns to use when creating a new RAID-5 volume (with the make
operation) or when creating a striped plex (with the make, mirror, and snapstart
operations). The default is to adjust to the number of available disks.
- raid5_stripeunit=width (alias: raid5_stwid)
- Specify the stripe unit size to use when creating a new RAID-5 volume (default value: 16K). This
attribute is used only with the make operation.
- Specify the log length to use when adding the first log to a RAID-5 volume. The default is four times
the full stripe width (the stripe unit size times the number of stripe columns).
- Specify 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.
- stripe_stripeunit=width (alias: stripe_stwid)
- Specify the stripe unit size to use when creating striped plexes to attach to a volume. When attaching
a new volume, 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.
- stripeunit=width (alias: stwid, stripewidth)
- Specify the stripe unit size to use for either a RAID-5 volume or for striped plexes. stripeunit can
be used to set the values for both raid5_stripeunit and stripe_stripeunit.
- Specify 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
- Specify the usage type to use when creating a new volume (default value: raid5 for RAID-5
volumes; fsgen, otherwise). This attribute is used only with the make operation. The usage
type can also be specified in the option list with -U.
- Specify 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
- For example, a defaults file can name a specific controller type to use for allocations, if possible. As
soon as all disks on that type of controller are full, other controllers will be used.
- Specify a desired list of disk class mirroring specifications. This is useful in a defaults file to indicate
a set of desired mirroring constraints that can be dropped if they fail to yield a reasonable
set of allocations.
- For example, in a SPARCstorage Array, a defaults file can specify that volumes should be mirrored
between removable trays of disks, if possible. Then, if the set of volumes builds up in such
a way that a new volume cannot be mirrored across SPARCstorage Array trays, this
constraint will be dropped.
The layout attribute specifies a comma-separated list of simple parameters (with no arguments) that apply to vxassist operations.
Defined layout specifications are:
- mirror, nomirror, raid5
- New volumes should be mirrored, unmirrored (default), or RAID-5, respectively.
- stripe, nostripe
- New plexes should be striped or unstriped, respectively. When creating a new volume, the default
is nostripe. When adding a new plex to an existing volume, the default is stripe if the
volume already has one or more striped plexes, and nostripe in other cases.
- span, nospan
- Allow (default) or disallow plexes, regular stripe columns, or RAID-5 stripe columns from spanning
multiple disks. If nospan is indicated, then plexes or columns can be formed from multiple
regions of the same disk, but cannot be formed from more than one disk.
- contig, nocontig
- Disallow or allow (default) plexes, regular stripe columns, or RAID-5 stripe columns from using
multiple regions of disk. If contig is specified, then plexes and columns must be allocated
from a single contiguous region of disk. If this is not possible, the allocation fails. By
default, vxassist tries to allocate space contiguously, but will use multiple regions or
multiple disks if needed.
- log, nolog
- Create (or don't create) dirty region logs (for mirrored volumes) or log plexes (for RAID-5 volumes)
when creating a new volume. This attribute can be specified independently for mirrored
and RAID-5 volumes with the raid5log and regionlog layout specifications.
- raid5log, noraid5log
- Create (default) or don't create log plexes for RAID-5 volumes.
- regionlog, noregionlog
- Create or don't create (default) dirty-region log subdisks for mirrored volumes.
- diskalign, nodiskalign
- Align (default) or don't align subdisks on cylinder boundaries. When alignment is not disabled,
subdisks are created beginning on cylinder boundaries and are extended to match the end
of a cylinder. Dirty region log subdisks, however, are not cylinder aligned (they are usually
only 2 or 3 blocks long). Instead, when creating log subdisks, spaces are located from the
available disks that could not be turned into regular subdisks because the spaces aren't
cylinder aligned. For example, once one cylinder is used for a log subdisk, that cylinder
cannot be used to create an aligned data (or RAID-5 log) subdisk, so other log subdisks will
be created there until that cylinder fills up.
- System default settings file for vxassist attributes.
The vxassist 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 vxintro(ADM) for a list of standard exit codes.
Copyright © 2005 The SCO Group, Inc. All rights reserved.