volassist - Create, mirror, backup, grow, shrink, and move Logical Storage Manager (LSM) volumes
/sbin/volassist [options] make volume length attribute=value... [[!]medianame[,offset]...]
/sbin/volassist [options] mirror volume attribute=value... [[!]medianame[,offset]...]
/sbin/volassist [options] move volume attribute=value... !medianame [[!]medianame[,offset]...]
/sbin/volassist [options] growto volume newlength attribute=value... [[!]medianame[,offset]...]
/sbin/volassist [options] growby volume lengthchange attribute=value [[!]medianame[,offset]...]
/sbin/volassist [options] shrinkto volume newlength attribute=value...
/sbin/volassist [options] shrinkby volume lengthchange attribute=value
/sbin/volassist [options] snapstart volume attribute=value [[!]medianame[,offset]...]
/sbin/volassist [options] snapshot volume newvolume
/sbin/volassist [options] snapwait volume
The following options are recognized:
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
operands (if any) for the
operation, or based on the
for all other operations.
Limit the operation to apply to this usage type. Attempts
to affect volumes with a different usage type will fail. For a
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
file or else
is set to the
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
as a number
of milliseconds, or a default is chosen (normally 250 milliseconds).
Perform copy and recovery operations in regions with the length
size, which is a standard Logical
Storage Manager length number (see
volintro(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 32
Perform extended operations in background. This applies to
plex consistency recovery operations for
growby. This flag also applies to
plex attach operations started by either
Specify a file containing defaults for various attributes
related to volume creation and space allocation. If not specified, this defaults
when a volume is open.
The volassist utility is a one-step interface that finds space for and creates simple volumes, adds simple mirrors to existing volumes, extends and shrinks existing volumes, provides for the migration of data from a specified disk, and provides facilities for the backup of existing volumes.
The 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, any medianame operands will be used to determine a default disk group, according to the standard disk group selection rules described in volintro(8). For other operations, the volume operand is used. A specific disk group can be forced with -g diskgroup. With no medianame operands, the make operation defaults to using the rootdg disk group. An alternate default disk group can be specified in a defaults file (/etc/default/volassist).
The medianame operands name disks to use for allocating new space for a volume. These arguments can be either a simple name for a disk media record, or they can be of the form medianame,offset to specify an offset within the named disk. If an offset is specified, then regions from the that offset to the end of the disk are considered candidates for allocation.
A specific disk can be avoided, for allocation purposes, by specifying a medianame operand with a prefix character of ! (or, \! from csh). For example, the command:
/sbin/volassist make vol1 1000m !disk03
creates a 1000MB volume on any non-volatile, non-reserved disk other
The volassist utility allows users to create and modify simple volumes through a single command front-end. For the make, mirror, snapstart and grow operations, volassist seeks out available disk space and tries to allocate it in the configuration that conforms to the layout specifications and offers the best use of free space.
In order to avoid risking the loss of data availability and I/O performance, volassist will not create volumes with more than one mirror per disk, or striped mirrors with more than one stripe per disk. However, snapshot mirrors may co-reside with normal mirrors of the volume because their association with the volume is temporary and snapshot mirrors are not used for data access or recovery.
volassist creates new volumes in the EMPTY state and attempts to start them. If the volume fails to start, volassist will attempt to remove it and release the space used to allocate this volume.
New mirrors can be created for and attached to any enabled volume that is ACTIVE or EMPTY. If the new mirror is successfully attached to the volume, its state is changed to be compatible with the volume. If the attach operation fails, the mirror is removed and the space it occupied is released. If the attach operation is interrupted by a system crash, the mirror will be automatically removed and its space released, when the volume is started again.
The snapstart, snapwait and snapshot operations provide a way to backup volumes with minimal interruption to I/O activity. The snapstart operation creates a mirror which gets attached to the volume and brought up-to-date. The end of the update procedure is indicated by the new snapshot mirror changing its state to SNAPDONE. This change can be tracked by using the volassist snapwait operation, which waits until at least one of the snapshot mirrors changes its state to SNAPDONE. If the attach process fails, the snapshot plex (mirror) is removed and its space is released.
Once the attach of the snapshot plex is completed, it continues being updated until it is detached. The backup operation is completed by using the volassist snapshot command on a volume with a SNAPDONE mirror. This operation detaches the finished snapshot, creates a new volume, and attaches the snapshot mirror to it. The state of the snapshot is set to ACTIVE.
If the snapshot procedure is interrupted, the
mirror is automatically removed when the volume is started.
The recognized operation keywords are: Create a volume with the specified name and the specified length. The length is specified as a standard Logical Storage Manager length (see volintro(8)). If medianame operands are specified, then create the volume by allocating subdisks on the indicated disks. With no medianame operands, all non-volatile, non-reserved disks in the disk group are considered candidates for allocation. Attributes can be specified to indicate various desired properties for the created volume. Create a new mirror (plex) and attach it to the volume. This operation is allowed only if the volume is enabled. If medianame operands are specified, then create the new mirror by allocating subdisks on the indicated disks. With no medianame operands, all non-volatile, non-reserved disks in the disk group are considered candidates for allocation. Attributes can be specified to indicate various desired properties for the new plex. Move subdisks within the named volume off the exclusion disks listed on the command line. Exclusion disks are specified with a prefix of !. The move operation requires that at least one exclusion disk be specified.
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/volassist.
Attributes are selected according to the order in which they are scanned. In general they are taken in decreasing priority of being specified on: The command line The user's defaults file, as supplied with a -d command line argument The system defaults file, as specified by /etc/default/volassist
Some attributes have boolean values, which can be on or off. Boolean values can be specified as on or off or as true or false. Some attributes have length values, which can be specified as standard Logical Storage Manager length numbers (see volintro(8)). Some attributes have simple numeric counts, which are specified as simple decimal numbers. Some attributes have string values, which can consist of any string, with some restrictions that depend upon the attribute. Defined attributes are: The number of mirrors to create for a make operation, if mirroring is requested. This number must be between 2 and 8. If not specified, defaults to 2. If set, create mirrored volumes with the make operation. If no other default exists and this entry is not given, then this attribute defaults to off. Set the disk group to use when creating a volume with the make operation. This option should be used only in a defaults file. The -g option should be used to specify a disk group from the command line. A disk group can be specified either by disk group ID or by disk group name. The default value for the disk group is rootdg. The usage type to use when creating a volume with the make operation. Usage type names are limited to 14 characters and cannot contain any blanks. If no usage type is specified, this defaults to fsgen. Allocation granularity size. If set to a non-zero value, this option will force the length for all allocated subdisks to be a multiple of this size. An exception to this rule is for striped plexes. The allocation sizes for subdisks will be adjusted up to be a multiple of the stripe width for the plex. The length for volumes will also be adjusted to match the allocation granularity. Volume lengths will never be less than the size requested from the command line. Alignment boundary size. If set to a non-zero value, this will force all allocations to start on a size-multiple boundary from the start of the public region of a disk. Normally, the value for the align attribute should be the same as or larger than the alloc attribute. The primary purpose for align is to increase the likelihood that created subdisks are sufficiently compatible that they can be swapped and moved between disks with a reasonably small set of subdisk split, join, and move operations (see volsd(8)). Specify the layout to use for creating plexes (mirrors). There are two basic layout types: concat and stripe for simple concatenated or striped plexes. If the stripe layout is selected, then the nstripe and stwidth attributes will be used to define the characteristics of the striped plex. If the basic layout is concat (the default), then additional layout modifiers may be specified to control allocation of subdisks within the plex to various disks: Allow a plex to be allocated from space on multiple physical disks. Spanned plexes can have better performance in some cases than non-spanned disks, and they can also be larger than any single disk attached to the system. However, without mirroring, a plex that spans several disks will fail if any one of the disks fails, reducing the reliability of the volume. Mirroring can restore and increase the reliability of the volume. Restrict a plex to use space on a single physical disk. Restrict a plex to a contiguous region of disk. This disables spanning, and also prevents a plex from being scattered across discontiguous sections of a disk. Do not restrict plex allocation to contiguous regions of disk.
The volassist 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.
for a list of standard exit codes.
System default settings for
Commands: volintro(8), voledit(8), volmake(8), volmend(8), volplex(8), volsd(8), volume(8)