volume-request(4)
NAME
volume-request, volume-defaults - Solaris Volume Manager
configuration information for top down volume creation with
metassist
SYNOPSIS
/usr/share/lib/xml/dtd/volume-request.dtd
/usr/share/lib/xml/dtd/volume-defaults.dtd
DESCRIPTION
A volume request file, XML-based and compliant with the
volume-request.dtd Document Type Definition, describes the
characteristics of the volumes that metassist should pro-
duce.
A system administrator would use the volume request file
instead of providing options at the command line to give
more specific instructions about the characteristics of the
volumes to create.
If you start metassist by providing a volume-request file as
input, metassist can implement the configuration specified
in the file, can generate a command file that sets up the
configuraiton for you to inspect or edit, or can generate a
volume configuration file for you to inspect or edit.
As a system administrator, you would want to create a volume
request file if you need to reuse configurations (and do not
want to reenter the same command arguments), or if you
prefer to use a configuration file to specify volume charac-
teristics.
Volume request files must be valid XML that complies with
the document type definition in the volume-request.dtd file,
located at /usr/share/lib/xml/dtd/volume-request.dtd. You
create a volume request file, and provide it as input to
metassist to create volumes from the top down.
Defining Volume Request
The top level element <volume-request> surrounds the volume
request data. This element has no attributes. A volume
request requires at least one <diskset> element, which must
be the first element after <volume-request>.
Optionally, the <volume-request> element can include one or
more <available> and <unavailable> elements to specify which
controllers or disks associated with a specific controller
can or cannot be used to create the volume.
Optionally, the <volume-request> element can include a <hsp>
element to specify characteristics of a hot spare pool if
fault recovery is used.
If not specified for a volume with fault-recovery, the first
hot spare pool found in the disk set is used. If no hot
spare pool exists but one is required, a hot spare pool is
created.
Optionally, the volume-request can include one or more <con-
cat>, <stripe>, <mirror>, <volume> elements to specify
volumes to create.
Defining Disk Set
Within the <volume-request> element, a <diskset> element
must exist. The <diskset> element, with the name attribute,
specifies the name of the disk set to be used. If this disk
set does not exist, it is created. This element and the name
attribute are required.
Defining Availability
Within the <volume-request> element and within other ele-
ments, you can specify available or unavailable components
(disks, or disks on a specific controller path) for use or
exclusion from use in a volume or hot spare pool.
The <available> and <unavailable> elements require a name
attribute which specifies either a full ctd name, or a par-
tial ctd name that is used with the implied wildcard to com-
plete the expression. For example, specifying c3t2d0 as
available would look like:
<available name="/dev/dsk/c3t2d0">
Specifying all disks on controller 2 as unavailable would
look like:
<unavailable name="c2">
Components specified as available must be either part of the
named disk set used for this volume creation, or must be
unused and not in any disk set. If the components are
selected for use, the metassist command automatically adds
them.
It is unnecessary to specify components that are in other
disk sets as unavailable. metassist automatically excludes
them from consideration. However, unused components or com-
ponents that are not obviously used (for example., an
unmounted slice that is reserved for different uses) must be
explicitly specified as unused, or the metassist command can
include them in the configuration.
Defining Hot Spare Pool
The next element within the <volume-request> element, after
the <diskset> and, optionally, <available> and <unavailable>
elements, is the <hsp> element. Its sole attribute specifies
the name of the hot spare pool:
<hsp name="hsp001">
The hot spare pool names must start with hsp and conclude
with a number, thus following the existing Solaris Volume
Manager hot spare pool naming requirements.
Within the <hsp> element, you can specify one or more
<available> and <unavailable> elements to specify which
disks, or disks associated with a specific controller can or
cannot be used to create the hot spares within the pool.
Also within the <hsp> element, you can use the <slice> ele-
ment to specify hot spares to be included in the hot spare
pool (see DEFINING SLICE). Depending on the requirements
placed on the hot spare pool by other parts of the volume
request, additional slices can be added to the hot spare
pool.
Defining Slice
The <slice> element is used to define slices to include or
exclude within other elements. It requires only a name
attribute to specify the ctd name of the slice, and the con-
text of the <slice> element determines the function of the
element. Sample slice elements might look like:
<slice name="c0t1d0s2"></slice>
<slice name="c0t12938567201lkj29561sllkj381d0s2" />
Defining Stripe
The <stripe> element defines stripes (interlaced RAID 0
volumes) to be used in a volume. It can contain either slice
elements (to explicitly determine which slices are used), or
appropriate combinations of available and unavailable ele-
ments if the specific determination of slices is to be left
to the metassist command.
The <stripe> element takes an optional name attribute to
specify a name. If the name isn't specified, an available
name is automatically selected from available Solaris Volume
Manager names. If possible, names for related components are
related.
The <stripe> element takes an optional size attribute that
specifies the size as value and units (for example, 10TB,
5GB). If slices for the <stripe> are explicitly specified,
the size attribute is ignored. The <available> and
<unavailable> elements can be used to constrain slices for
use in a stripe.
The <stripe> elements takes optional mincomp and maxcomp
attributes to specify both the minimum and maximum number of
components that can be included in it. As with size, if
slices for the <stripe> are explicitly specified, the min-
comp and maxcomp attributes are ignored.
The <stripe> elements takes an optional interlace attribute
as value and units (for example, 16KB, 5BLOCKS, 20KB). If
this value isn't specified, the Solaris Volume Manager
default value is used.
The <stripe> element takes an optional usehsp attribute to
specify if a hot spare pool should be associated with this
component. This attribute is specified as a boolean value,
as usehsp="TRUE". If the component is not a submirror, this
attribute is ignored.
Defining Concat
The <concat> element defines concats (non-interlaced RAID 0
volumes) to be used in a configuration. It is specified in
the same way as a <stripe> element, except that the mincomp,
maxcomp, and interlace attributes are not valid.
Defining Mirror
The <mirror> element defines mirrors (RAID 1 volumes) to be
used in a volume configuration. It can contain combinations
of <concat> and <stripe> elements (to explicitly determine
which volumes are used as submirrors). Alternatively, it can
have a size attribute specified, along with the appropriate
combinations of available and unavailable elements to leave
the specific determination of components to the metassist
command.
The <mirror> element takes an optional name attribute to
specify a name. If the name isn't specified, an available
name is automatically selected.
The <mirror> element takes an optional size attribute that
specifies the size as value and units (for example, 10TB,
5GB). If <stripe> and <concat> elements for the mirror are
not specified, this attribute is required. Otherwise, it is
ignored.
The <mirror> element takes an optional nsubmirrors attribute
to define the number of submirrors (1-4) to include. Like
the size attribute, this attribute is ignored if the under-
lying <concat> and <stripe> submirrors are explicitly speci-
fied. The <mirror> element takes an optional read attribute
to define the mirror read options (ROUNDROBIN, GEOMETRIC, or
FIRST) for the mirror. If this attribute is not specified,
the Solaris Volume Manager default value is used.
The <mirror> element takes an optional write attribute to
define the mirror write options (PARALLEL, SERIAL, or FIRST)
for the mirror. If this attribute is not specified, the
Solaris Volume Manager default value is used.
The <mirror> element takes an optional usehsp attribute to
specify if a hot spare pool should be associated with each
submirror. This attribute is specified as a boolean value,
as usehsp="TRUE". If the usehsp attribute is specified in
the configuration of the <stripe> or <concat> element used
as a submirror, it overrides the value of usehsp attributes
for the mirror as a whole.
Defining Volume by Quality of Service
The <volume> element defines volumes (high-level) by the
quality of service they should provide. (The <volume> ele-
ment offers the same functionality that options on the
metassist command line can provide.)
The <volume> element can contain combinations of <available>
and <unavailable> elements to determine which components can
be included in the configuration.
The <volume> element takes an optional name attribute to
specify a name. If the name isn't specified, an available
name is automatically selected.
The <volume> element takes a required size attribute that
specifies the size as value and units (for example, 10TB,
5GB).
The <volume> element takes an optional redundancy attribute
to define the number of additional copies of data (1-4) to
include. In a worst-case scenario, a volume can suffer
failure of n-1 components without data loss, where
redundancy=n. With fault recovery options, the volume could
withstand up to n+hsps-1 non-concurrent failures without
data loss. Specifying redundancy=0 results in a RAID 0
volume being created (a stripe, specifically).
The <volume> element takes an optional faultrecovery attri-
bute to determine if additional components should be allo-
cated to recover from component failures in the volume. This
is a boolean attribute, with a default value of FALSE.
The <volume> element takes an optional datapaths attribute
to determine if multiple data paths should be required to
access the volume. The datapaths attribute should be set to
a numeric value.
Defining Default Values Globally
Global defaults can be set in /etc/default/metassist.xml.
This volume-defaults file can contain most of the same ele-
ments as a volume-request file, but differs structurally
from a volume-request file:
o The container element must be <volume-defaults>, not
<volume-request>.
o The <volume-defaults> element can contain <available>,
<unavailable>, <hsp>, <concat>, <stripe>, <mirror>, or
<volume> elements.
Attributes specified by these elements define global default
values, unless overridden by the corresponding attributes
and elements in a volume-request. None of these elements is
a container element.
o The <volume-defaults> element can contain one or more
<diskset> elements to provide disk set-specific
defaults. The <diskset> element can contain <avail-
able>, <unavailable>, <hsp>, <concat>, <stripe>, <mir-
ror>, or <volume> elements.
o Settings specified outside of a <diskset> element
apply to all disk sets, but can be overridden within
each <diskset> element.
EXAMPLES
Example 1: Creating a Redundant Volume
The following example shows a volume request file used to
create a redundant and fault tolerant volume of 1TB.
<volume-request>
<diskset name="sparestorage">
<volume size="1TB" redundancy="2" faultrecovery="TRUE">
<available name="c2" />
<available name="c3" />
<unavailable name="c2t2d0" />
</volume>
</volume-request>
Example 2: Creating a Complex Configuration
The following example shows a sample volume-request file
that specifis a disk set name, and specifically itemizes
characteristics of components to create.
<volume-request>
<!-- Specify the disk set to use -->
<diskset name="mailspool"/>
<!-- Generally available devices -->
<available name="c0"/>
<!-- Create a 3-way mirror with redundant datapaths and HSPs \
via QoS -->
<volume size="10GB" redundancy="3" datapaths="2" \
faultrecovery="TRUE"/>
<!-- Create a 1-way mirror with a HSP via QoS -->
<volume size="10GB" faultrecovery="TRUE"/>
<!-- Create a stripe via QoS -->
<volume size="100GB"/>
BOUNDARY VALUES
Attribute Minimum Maximum
mincomp 1 N/A
maxcomp N/A 32
nsubmirrors 1 4
passnum 0 9
datapaths 1 4
redundancy 0 4
FILES
/usr/share/lib/xml/dtd/volume-request.dtd
/usr/share/lib/xml/dtd/volume-defaults.dtd
/etc/lvm/volume-defaults.xml
SEE ALSO
metassist(1M), metaclear(1M), metadb(1M), metadetach(1M),
metahs(1M), metainit(1M), metaoffline(1M), metaonline(1M),
metaparam(1M), metarecover(1M), metareplace(1M),
metaroot(1M), metaset(1M), metasync(1M), metattach(1M),
mount_ufs(1M), mddb.cf(4)
Solaris Volume Manager Administration Guide
Man(1) output converted with
man2html