 |
Index for
Section 8 |
|
 |
Alphabetical
listing for V |
|
 |
Bottom of
page |
|
volassist(8)
NAME
volassist - Interface to create, mirror, backup, 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:
-g diskgroup
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.
-U usetype
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.
-o useopt
Passes in usage-type-specific options to the operation. A certain set
of operations are expected to be implemented by all usage types:
slow[=iodelay]
Reduces 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
Performs 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 between 32 and 256 kilobytes.
-b 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.
-d defaults
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.
-f 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.
-p Limits the output of the maxsize and maxgrow operations to a numeric
value only (no text). This option is mainly for use in scripts.
-n Specifies that the system defaults file, /etc/default/volassist, should
not be used when creating volumes.
-v Specifies that volassist is to be run in verbose 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 existing 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. A complete list of
attribute specifications are below.
KEYWORDS
volassit keywords are:
help
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.
make
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.
mirror
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 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.
Use the layout=mirror,nolog option to create a mirrored volume with DRL
disabled.
move
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 operation 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.
growto and growby
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.
No attempt will be made by volassist 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.
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.
shrinkto and shrinkby
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.
No attempt will be made by volassist 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.
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.
addlog
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 currently 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.
snapstart and snapshot
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. 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. 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.
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.
maxsize
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.
maxgrow volume
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
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.
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:
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/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 specified 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:
[!]diskname
Specifies (or excludes) the given disk. The diskname parameter refers
to a disk media record name in a Logical Storage Manager disk group.
[!]da:da_name
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.
[!]device:dev_name (alias d)
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.
[!]dm:dm_name (alias disk)
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 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
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.
diskgroup=disk-group (alias: dg)
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).
group=owning-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.
init=initialization-type
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 guaranteed to be
written before being read.
layout=layout-spec[,layout-spec,...]
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.
loglen=length
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.
logtype=drl|region|none
Specifies the logging type for a mirrored volume. Dirty region logging
(the default) can be selected with either logtype=drl or
logtype=region. To disable logging, enter: logtype=none.
max_nraid5column=number (alias: maxraid5columns)
Specifies the default maximum number of stripe columns for a RAID5
volume (default value: 8).
max_ncolumn=number (alias: maxcolumns)
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).
max_regionloglen=length (alias: maxregionloglen)
Specifies 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, volassist 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)
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 allowed to create a RAID5 volume with fewer
than min_nraid5stripe stripe columns. The minimum number of columns
that you can have is 3.
min_nstripe=number (alias: minstripes)
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 will not be allowed to select fewer than this number of
columns.
mirror=number|yes|no
Specifies mirroring parameters. A decimal number indicates a specific
number of mirrors to create, 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 layout=nomirror).
mode=permissions
Specifies 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(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.
nlog=number
Specifies the number of logs to create, by default, for a RAID5 or
mirrored volume (presuming that logs will be created). The number of
logs to create can be specified independently for RAID5 or mirrored
volumes using the nraid5log and nregionlog attributes.
nmirror=number
Specifies the number of mirrors to create when mirroring a volume
(default value: 2).
nraid5log=number
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.
nraid5stripe=number (alias: raid5stripes)
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.
nregionlog=number
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.
nstripe=number (alias: stripes, ncolumn)
Specifies the number of stripe columns to use when creating 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.
raid5_stripeunit=width (alias: raid5_stwid)
Specifies the stripe unit size to use when creating a new RAID5 volume
(default value: 16K). This attribute is used only with the make
operation.
raid5loglen=length
Specifies the log length to use when adding the first log to a RAID5
volume. The default is four times the full stripe width (the stripe
unit size times the number of stripe columns).
regionloglen=length
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.
stripe_stripeunit=width (alias: stripe_stwid)
Specifies 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)
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.
user=owning-user
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.
usetype=volume-usage-type
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.
wantalloc=storage-spec[,storage-spec,...]
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 simple parameters
(with no arguments) that apply to volassist operations.
Defined layout specifications are:
concat
New volumes should be simple, concatenated plexes (default).
mirror, nomirror, raid5
New volumes should be mirrored, unmirrored (default), or RAID5,
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
Allows (default) or disallows plexes, regular stripe columns, or RAID5
stripe columns from spanning 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.
contig, nocontig
Disallows or allows (default) plexes, regular stripe columns, or RAID5
stripe columns from using 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 possible, the allocation
fails. By default, volassist tries to allocate space contiguously, but
will use multiple regions or multiple disks if needed.
log, nolog
Creates (or doesn't create) dirty region logs (for mirrored volumes) or
log plexes (for RAID5 volumes) when creating a new volume. This
attribute can be specified independently for mirrored and RAID5 volumes
with the raid5log and regionlog layout specifications. The -f option
must be used to create a RAID5 volume with the nolog attribute.
raid5log, noraid5log
Creates (default) or doesn't create log plexes for RAID5 volumes. The
-f option must be used with noraid5log to override the default
behavior.
regionlog, noregionlog
Creates or doesn't create (default) dirty-region log subdisks for
mirrored volumes.
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
/etc/default/volassist
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)
|
Index for
Section 8 |
|
|
Alphabetical
listing for V |
|
 |
Top of
page |
|