vxassist(ADM)

vxassist - create, mirror, backup, grow, shrink, and move volumes

Synopsis

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

Description

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 vxintro(ADM). 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:

make: Create a volume with the specified name and the specified length. The length is specified as a standard Volume Manager length (see vxintro(ADM)). Attributes can be specified to indicate various desired properties and storage locations for the created volume.
mirror: 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: 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 (see vxintro(ADM)). 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 (see vxintro(ADM)). 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.; 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.
addlog: 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 plex.
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 sync(ADM), 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.
snapwait: 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.

Options

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

slow[=iodelay]: 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 milliseconds).
iosize=size: Perform copy and recovery operations in regions with the length specified by size, which is a standard Volume Manager length number (see vxintro(ADM)). 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 128 kilobytes.

-b

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.

Attributes

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 specifications

Storage specification attributes have one of the following forms:

[!]diskname: Specify (or exclude) the given disk. diskname refers to a disk media record name in a Volume Manager disk group.
[!]diskclass:instance: 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.
diskclass:same: 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 defined disk classes (and alternate names, or aliases, for those classes) are as follows:

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.
da: 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.
diskparam: 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 accurate.
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.

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.

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

alloc=storage-spec[,storage-spec,...]: 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.
comment=comment: 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).
fstype=file-system-type: 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 (see fstyp(ADM)), 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.
group=owning-group: 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.
init=initialization-type: 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.
layout=layout-spec[,layout-spec,...]: 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 log.
loglen=length: 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 default.
logtype=drl|region|none: 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 logtype=none.
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.
mirror=number|yes|no|diskclass[,...]: 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.
mode=permissions: 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 chmod(C). This attribute is used only with the make operation. The default mode for a volume gives read and write access only to the owner.
nlog=number: 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.
nmirror=number: Specify the number of mirrors to create when mirroring a volume (default value: 2).
nraid5log=number: 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.
nregionlog=number: 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 volume.
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.
raid5loglen=length: 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).
regionloglen=length: 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.
user=owning-user: 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 operation.
usetype=volume-usage-type: 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.
wantalloc=storage-spec[,storage-spec,...]: 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 storage specifications).; 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.
wantmirror=diskclass[,diskclass,...]: 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.

Layout specifications

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.

Files

/etc/default/vxassist: System default settings file for vxassist attributes.

Exit codes

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.

References

chmod(C), fstyp(ADM), sync(ADM), vxedit(ADM), vxintro(ADM), vxmake(ADM), vxmend(ADM), vxplex(ADM), vxprint(ADM), vxresize(ADM), vxsd(ADM), vxvol(ADM)