 |
Index for Section 8 |
|
 |
Alphabetical listing for V |
|
volassist(8)
NAME
volassist - Create, mirror, backup, grow, shrink, and move Logical Storage
Manager (LSM) volumes
SYNOPSIS
/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
OPTIONS
The following options are recognized:
-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 volassist 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 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 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 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 kilobytes.
-b Perform extended operations in background. This applies to plex
consistency recovery operations for volassist make, growto, and growby.
This flag also applies to plex attach operations started by either
volassist mirror and volassist 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/volassist.
-f Force a volassist growto, growby, shrinkto, or shrinkby operation when
a volume is open.
DESCRIPTION
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 than
disk03.
NOTES ON OPERATION
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 snapshot mirror is
automatically removed when the volume is started.
KEYWORDS
The recognized operation keywords are:
make
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.
mirror
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
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.
If the volume is enabled, then subdisks within detached or disabled
plexes will be moved without recovery of data. If the volume is not
enabled, then 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 plexes within an enabled volume, log subdisks will be moved
to another disk and recovered. Striped plexes within the volume that
have a subdisk on the volume will be moved to another disk, and the
entire plex will be recovered. Subdisks within concatenated plexes that
reside on other disks will be moved and recovered.
growto and growby
Increase the length of the named volume to the length specified by
newlength, or by the length specified by lengthchange. The new length
or change in length is specified as 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 the length of the
last subdisk in each plex of the volume, or by adding new subdisks
concatenated to the end of each plex. If medianame operands are
specified, then new space is allocated only from the indicated disks.
With no medianame operands, all non-volatile, non-reserved disks in the
disk group of the volume are considered candidates for allocation.
Attributes can be specified to indicate various desired properties for
the new allocations.
A volume containing one or more striped plexes cannot be grown. Also,
growing a volume requires that the volume be enabled. If the volume is
mirrored, volassist will attempt to ensure consistency of the new
allocated extensions to each plex using standard means of plex
recovery.
File systems such as AdvFS and UFS cannot currently take advantage of
an enlarged volume.
Note
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.
shrinkto and shrinkby
Decrease the length of the named volume to the length specified by
newlength, or by the length specified by lengthchange. The new length
or change in length is specified as 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.
A volume containing one or more striped plexes cannot be shrunk.
File systems such as AdvFS and UFS cannot currently take advantage of a
shrunk volume.
Note
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 shrink, you
must use the -f force option.
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.
Some usage types will attempt to synchronize any in-memory data
associated with the volume (such as unwritten file modifications) 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.
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.
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/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:
1. The command line
2. The user's defaults file, as supplied with a -d command line argument
3. 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:
nmirror=count
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.
mirror=boolean
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.
dg=string
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.
usetype=string
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.
alloc=size
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.
align=size
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)).
layout=string,string,...
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:
span (default)
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.
nospan
Restrict a plex to use space on a single physical disk.
contig
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.
noncontig (default)
Do not restrict plex allocation to contiguous regions of disk.
The striped plex allocation policy is equivalent to allocating nstripe
contiguous areas of disk space, on different physical disks, that are
each 1/nstripe as large as the volume volume.
nstripe=count
The number of stripes to create when allocating a striped plex. If not
specified, volassist will default the number of stripes to no less than
2, and no more than 8. If medianame operands are specified, then the
default will adjust to the number of named disks. If no medianame
operands are specified, then the default is half of the candidate
disks, adjusted to a number between 2 and 8. This option can only be
specified if layout=stripe is also specified.
stwidth=size
Set the stripe width for striped plexes to the indicated size. If not
specified, defaults to 64K. This option can only be specified if
layout=stripe is also specified.
logtype=string
Set the logging type to use when creating a volume. The two log types
recognized are:
none
Do not do any special logging.
blkno
Log all writes to log subdisks associated with each plex in the
volume. This provides much faster volume recovery time, at the
expense of degraded performance during normal volume operation. The
log subdisks are each 1 block long. By default, volassist allocates
log subdisks in a block immediately before the first regular
subdisk in the plex.
If no default log type is found, but logging is enabled, then blkno
is selected as the default.
init=string
Specify the type of initialization to use when creating a volume. If
not specified, the volume will be started by calling volume start to
use the default initialization procedure. If specified as none, created
volumes will remain unstarted and uninitialized. The possible types of
initialization are specified in volume(8) under the description of the
init operation.
EXIT CODES
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.
See volintro(8) for a list of standard exit codes.
FILES
/etc/default/volassist
System default settings for volassist attributes.
SEE ALSO
Commands: volintro(8), voledit(8), volmake(8), volmend(8), volplex(8),
volsd(8), volume(8)