path: root/usr/src/man/man4/volume-request.4

'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH VOLUME-REQUEST 4 "April 9, 2016"
.SH NAME
volume-request, volume-defaults \- Solaris Volume Manager configuration
information for top down volume creation with metassist
.SH SYNOPSIS
.LP
.nf
\fB/usr/share/lib/xml/dtd/volume-request.dtd\fR
.fi

.LP
.nf
\fB/usr/share/lib/xml/dtd/volume-defaults.dtd\fR
.fi

.LP
.nf
\fB/etc/defaults/metassist.xml\fR
.fi

.SH DESCRIPTION
.LP
A volume request file, XML-based and compliant with the
\fBvolume-request.dtd\fR Document Type Definition, describes the
characteristics of the volumes that \fBmetassist\fR should produce.
.sp
.LP
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. A volume request file can request
more than one volume, but all requested volumes must reside in the same disk
set.
.sp
.LP
If you start \fBmetassist\fR by providing a volume-request file as input,
\fBmetassist\fR 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.
.sp
.LP
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
characteristics.
.sp
.LP
Volume request files must be valid XML that complies with the document type
definition in the volume-request.dtd file, located at
\fB/usr/share/lib/xml/dtd/volume-request.dtd\fR. You create a volume request
file, and provide it as input to metassist to create volumes from the top down.
.SS "Defining Volume Request"
.LP
The top level element \fB<volume-request>\fR 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
\fB<volume-request>\fR\&.
.sp
.LP
Optionally, the \fB<volume-request>\fR element can include one or more
\fB<available>\fR and \fB<unavailable>\fR elements to specify which controllers
or disks associated with a specific controller can or cannot be used to create
the volume.
.sp
.LP
Optionally, the \fB<volume-request>\fR element can include a \fB<hsp>\fR
element to specify characteristics of a hot spare pool if fault recovery is
used.
.sp
.LP
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.
.sp
.LP
Optionally, the volume-request can include one or more \fB<concat>\fR,
\fB<stripe>\fR, \fB<mirror>\fR, \fB<volume>\fR elements to specify volumes to
create.
.SS "Defining Disk Set"
.LP
Within the \fB<volume-request>\fR element, a \fB<diskset>\fR element must
exist. The \fB<diskset>\fR 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.
.SS "Defining Availability"
.LP
Within the \fB<volume-request>\fR element and within other elements, 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.
.sp
.LP
The \fB<available>\fR and \fB<unavailable>\fR elements require a name attribute
which specifies either a full \fBctd\fR name, or a partial \fBctd\fR name that
is used with the implied wildcard to complete the expression. For example,
specifying \fBc3t2d\fR0 as available would look like:
.sp
.in +2
.nf
<available name="/dev/dsk/c3t2d0">
.fi
.in -2

.sp
.LP
The \fB<available>\fR element also makes any unnamed components unavailable.
Specifying all controllers except \fBc1\fR unavailable would look like:
.sp
.in +2
.nf
<available name="c1">
.fi
.in -2

.sp
.LP
Specifying all disks on controller 2 as unavailable would look like:
.sp
.in +2
.nf
<unavailable name="c2">
.fi
.in -2

.sp
.LP
The \fB<unavailable>\fR element can also be used to further restrict the list
of available components. For example, specifying all controllers except \fBc1\fR
unavailable, and making all devices associated with c1t2 unavailable as well
would look like this:
.sp
.in +2
.nf
<available name="c1">
<unavailable name="c1t2">
.fi
.in -2

.sp
.LP
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, but are not in the specified diskset, the
\fBmetassist\fR command automatically adds them to the diskset.
.sp
.LP
It is unnecessary to specify components that are in other disk sets as
unavailable. \fBmetassist\fR automatically excludes them from consideration.
However, unused components or components that are not obviously used (for
example, an unmounted slice that is reserved for different uses) must be
explicitly specified as unavailable, or the \fBmetassist\fR command can include
them in the configuration.
.SS "Defining Hot Spare Pool"
.LP
The next element within the <volume-request> element, after the \fB<diskset>\fR
and, optionally, \fB<available>\fR and \fB<unavailable>\fR elements, is the
\fB<hsp>\fR element. Its sole attribute specifies the name of the hot spare
pool:
.sp
.in +2
.nf
<hsp name="hsp001">
.fi
.in -2

.sp
.LP
The hot spare pool names must start with \fBhsp\fR and conclude with a number,
thus following the existing Solaris Volume Manager hot spare pool naming
requirements.
.sp
.LP
Within the \fB<hsp>\fR element, you can specify one or more \fB<available>\fR
and \fB<unavailable>\fR 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.
.sp
.LP
Also within the \fB<hsp>\fR element, you can use the \fB<slice>\fR element to
specify hot spares to be included in the hot spare pool (see \fBDEFINING
SLICE\fR). 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.
.SS "Defining Slice"
.LP
The \fB<slice>\fR 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 context of the \fB<slice>\fR element determines the function
of the element. Sample slice elements might look like:
.sp
.in +2
.nf
<slice name="c0t1d0s2" />
<slice name="c0t12938567201lkj29561sllkj381d0s2" />
.fi
.in -2

.SS "Defining Stripe"
.LP
The \fB<stripe>\fR 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 elements if the specific determination of slices is to be left to
the metassist command.
.sp
.LP
The \fB<stripe>\fR element takes an optional name attribute to specify a name.
If the name is not specified, an available name is automatically selected from
available Solaris Volume Manager names. If possible, names for related
components are related.
.sp
.LP
The \fB<stripe>\fR element takes an optional size attribute that specifies the
size as value and units (for example, 10TB, 5GB). If slices for the
\fB<stripe>\fR are explicitly specified, the size attribute is ignored. The
\fB<available>\fR and \fB<unavailable>\fR elements can be used to constrain
slices for use in a stripe.
.sp
.LP
The \fB<stripe>\fR elements takes optional \fBmincomp\fR and \fBmaxcomp\fR
attributes to specify both the minimum and maximum number of components that
can be included in it. As with size, if slices for the \fB<stripe>\fR are
explicitly specified, the \fBmincomp\fR and \fBmaxcomp\fR attributes are
ignored.
.sp
.LP
The \fB<stripe>\fR elements takes an optional interlace attribute as value and
units (for example, \fB16KB, 5BLOCKS, 20KB\fR). If this value is not specified,
the Solaris Volume Manager default value is used.
.sp
.LP
The \fB<stripe>\fR 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 \fBusehsp="TRUE"\fR. If the component is not a
submirror, this attribute is ignored.
.SS "Defining Concat"
.LP
The \fB<concat>\fR element defines concats (non-interlaced RAID 0 volumes) to
be used in a configuration. It is specified in the same way as a \fB<stripe>\fR
element, except that the \fBmincomp\fR, \fBmaxcomp\fR, and interlace attributes
are not valid.
.SS "Defining Mirror"
.LP
The \fB<mirror>\fR element defines mirrors (RAID 1 volumes) to be used in a
volume configuration. It can contain combinations of \fB<concat>\fR and
\fB<stripe>\fR 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 \fBmetassist\fR command.
.sp
.LP
The \fB<mirror>\fR element takes an optional name attribute to specify a name.
If the name is not specified, an available name is automatically selected.
.sp
.LP
The \fB<mirror>\fR element takes an optional size attribute that specifies the
size as value and units (for example, 10TB, 5GB). If \fB<stripe>\fR and
\fB<concat>\fR elements for the mirror are not specified, this attribute is
required. Otherwise, it is ignored.
.sp
.LP
The \fB<mirror>\fR 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 underlying \fB<concat>\fR and \fB<stripe\fR>
submirrors are explicitly specified. The \fB<mirror>\fR element takes an
optional read attribute to define the mirror read options (\fBROUNDROBIN\fR,
\fBGEOMETRIC\fR, or \fBFIRST\fR) for the mirror. If this attribute is not
specified, the Solaris Volume Manager default value is used.
.sp
.LP
The \fB<mirror>\fR element takes an optional write attribute to define the
mirror write options (\fBPARALLEL\fR, \fBSERIAL\fR, or \fBFIRST\fR) for the
mirror. If this attribute is not specified, the Solaris Volume Manager default
value is used.
.sp
.LP
The \fB<mirror>\fR 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 \fBusehsp="TRUE"\fR. If the \fBusehsp\fR
attribute is specified in the configuration of the \fB<stripe>\fR or
\fB<concat>\fR element used as a submirror, it overrides the value of
\fBusehsp\fR attributes for the mirror as a whole.
.SS "Defining Volume by Quality of Service"
.LP
The \fB<volume>\fR element defines volumes (high-level) by the quality of
service they should provide. (The \fB<volume>\fR element offers the same
functionality that options on the metassist command line can provide.)
.sp
.LP
The \fB<volume>\fR element can contain combinations of \fB<available>\fR and
\fB<unavailable>\fR elements to determine which components can be included in
the configuration.
.sp
.LP
The \fB<volume>\fR element takes an optional name attribute to specify a name.
If the name is not specified, an available name is automatically selected.
.sp
.LP
The \fB<volume>\fR element takes a required size attribute that specifies the
size as value and units (for example, 10TB, 5GB).
.sp
.LP
The \fB<volume>\fR 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 \fIn\fR\fB-1\fR components without data loss,
where \fBredundancy=\fR\fIn\fR. With fault recovery options, the volume could
withstand up to \fIn\fR\fB+hsps-1\fR non-concurrent failures without data loss.
Specifying \fBredundancy=0\fR results in a RAID 0 volume being created (a
stripe, specifically).
.sp
.LP
The \fB<volume>\fR element takes an optional faultrecovery attribute to
determine if additional components should be allocated to recover from
component failures in the volume. This is used to determine whether the volume
is associated with a hot spare pool. The faultrecovery attribute is a boolean
attribute, with a default value of \fBFALSE\fR.
.sp
.LP
The \fB<volume>\fR 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.
.SS "Defining Default Values Globally"
.LP
Global defaults can be set in \fB/etc/default/metassist.xml\fR. This
volume-defaults file can contain most of the same elements as a volume-request
file, but differs structurally from a volume-request file:
.RS +4
.TP
.ie t \(bu
.el o
The container element must be \fB<volume-defaults>\fR, not
\fB<volume-request>\fR\&.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fB<volume-defaults>\fR element can contain \fB<available>\fR,
\fB<unavailable>\fR, \fB<hsp>\fR, \fB<concat>\fR, \fB<stripe>\fR,
\fB<mirror>\fR, or \fB<volume>\fR elements.
.sp
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.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fB<volume-defaults>\fR element can contain one or more \fB<diskset>\fR
elements to provide disk set-specific defaults. The \fB<diskset>\fR element can
contain \fB<available>\fR, \fB<unavailable>\fR, \fB<hsp>\fR, \fB<concat>\fR,
\fB<stripe>\fR, \fB<mirror>\fR, or \fB<volume>\fR elements.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Settings specified outside of a \fB<diskset>\fR element apply to all disk sets,
but can be overridden within each \fB<diskset>\fR element.
.RE
.SH EXAMPLES
.LP
\fBExample 1 \fRCreating a Redundant Volume
.sp
.LP
The following example shows a volume request file used to create a redundant
and fault tolerant volume of 1TB.

.sp
.in +2
.nf
<volume-request>
  <diskset name="sparestorage"/>
  <volume size="1TB" redundancy="2" faultrecovery="TRUE">
    <available name="c2" />
    <available name="c3" />
    <unavailable name="c2t2d0" />
  </volume>
</volume-request>
.fi
.in -2

.LP
\fBExample 2 \fRCreating a Complex Configuration
.sp
.LP
The following example shows a sample volume-request file that specifies a disk
set name, and specifically itemizes characteristics of components to create.

.sp
.in +2
.nf
<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"/>

</volume-request>
.fi
.in -2

.SH BOUNDARY VALUES
.in +2
.nf
Attribute       Minimum         Maximum
mincomp         1               N/A
maxcomp         N/A             32
nsubmirrors     1               4
passnum         0               9
datapaths       1               4
redundancy      0               4
.fi
.in -2
.sp

.SH FILES
.ne 2
.na
\fB\fB/usr/share/lib/xml/dtd/volume-request.dtd\fR\fR
.ad
.sp .6
.RS 4n

.RE

.sp
.ne 2
.na
\fB\fB/usr/share/lib/xml/dtd/volume-defaults.dtd\fR\fR
.ad
.sp .6
.RS 4n

.RE

.sp
.ne 2
.na
\fB\fB/etc/defaults/metassist.xml\fR\fR
.ad
.sp .6
.RS 4n

.RE

.SH SEE ALSO
.LP
\fBmetassist\fR(1M), \fBmetaclear\fR(1M), \fBmetadb\fR(1M),
\fBmetadetach\fR(1M), \fBmetahs\fR(1M), \fBmetainit\fR(1M),
\fBmetaoffline\fR(1M), \fBmetaonline\fR(1M), \fBmetaparam\fR(1M),
\fBmetarecover\fR(1M), \fBmetareplace\fR(1M), \fBmetaroot\fR(1M),
\fBmetaset\fR(1M), \fBmetasync\fR(1M), \fBmetattach\fR(1M),
\fBmount_ufs\fR(1M), \fBmddb.cf\fR(4)
.sp
.LP
\fISolaris Volume Manager Administration Guide\fR