path: root/usr/src/man/man1m/metassist.1m

'\" te
.\" Copyright (c) 2004, 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 METASSIST 1M "Feb 22, 2005"
.SH NAME
metassist \- automated volume creation utility to support Solaris Volume
Manager
.SH SYNOPSIS
.LP
.nf
\fBmetassist\fR \fB-V\fR
.fi

.LP
.nf
\fBmetassist\fR \fB-?\fR
.fi

.LP
.nf
\fBmetassist\fR create [\fB-v\fR \fIn\fR] [\fB-c\fR] \fB-F\fR \fIconfig_file\fR
.fi

.LP
.nf
\fBmetassist\fR create [\fB-v\fR \fIn\fR] [\fB-c\fR | \fB-d\fR] \fB-F\fR \fIrequest_file\fR
.fi

.LP
.nf
\fBmetassist\fR create [\fB-v\fR \fIn\fR] [\fB-c\fR | \fB-d\fR] [\fB-f\fR] [\fB-n\fR \fIname\fR]
     [\fB-p\fR \fIdatapaths\fR] [\fB-r\fR \fIredundancy\fR]
     [\fB-a\fR \fIavailable\fR [,\fIavailable\fR,\&.\|.\|.]]
     [\fB-u\fR \fIunavailable\fR [,\fIunavailable\fR,\&.\|.\|.]] \fB-s\fR \fIsetname\fR \fB-S\fR \fIsize\fR
.fi

.LP
.nf
\fBmetassist\fR create \fB-?\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBmetassist\fR command provides assistance, through automation, with
common Solaris Volume Manager tasks.
.SS "SUBCOMMANDS"
.sp
.LP
The following subcommands are supported:
.sp
.ne 2
.na
\fB\fBcreate\fR\fR
.ad
.RS 10n
The \fBcreate\fR subcommand creates one or more Solaris Volume Manager volumes.
You can specify this request on the command line or in a file specified on the
command line.
.sp
If you create a volume using the command line, you can specify the
characteristics of the volume in terms of the desired quality of service it
will provide - its size, the number of redundant copies of the data it
contains, the number of data paths by which it is accessible, and whether
faulty components are replaced automatically. The diskset in which the volume
will reside and the volume's size must be specified on the command line in this
form of the command.
.sp
If you create a volume using a request in a file, you can specify the
characteristics of the volume in terms of the quality of service they provide,
as on the command line. Alternatively, the file can specify the types and
component parts of the volume, (for example, mirrors, stripes, concatenations,
and their component slices). The file may also specify volumes partly in terms
of their types and partly in terms of their component parts, and may specify
the characteristics of more than one volume. All volumes specified in a file
must reside in the same diskset, whose name must be specified in the file.
.sp
If you specify the \fB-c\fR or \fB-d\fR option on the command line, the command
runs without creating an actual volume or volumes. Instead, it outputs either a
a Bourne shell command script (\fB-c\fR option) or a volume configuration
(\fB-d\fR option). The command script, when run, creates the specified volume
or volumes. The volume configuration specifies the volume or volumes in
complete detail, naming all their components.
.sp
The input file given on the command line can take one of the following forms:
.RS +4
.TP
.ie t \(bu
.el o
a volume request, which specifies a request for a volume with explicit
attributes and components, or matching a given quality of service
.RE
.RS +4
.TP
.ie t \(bu
.el o
a volume configuration, produced by a previous execution of the command
.RE
.RE

.SH OPTIONS
.sp
.LP
The following option is mandatory if you specify a volume request or volume
configuration in a file:
.sp
.ne 2
.na
\fB\fB-F\fR \fIconfig_file\fR | \fIrequest_file\fR\fR
.ad
.sp .6
.RS 4n
Specify the volume request or volume configuration file to process. If
\fIconfig_file\fR or \fIrequest_file\fR is \fB-\fR, it is read from standard
input.
.sp
The \fB-d\fR option cannot be specified when \fIinputfile\fR is a volume
configuration file.
.RE

.sp
.LP
The following options are mandatory if you specify a volume request on the
command line:
.sp
.ne 2
.na
\fB\fB-s\fR \fIset\fR\fR
.ad
.RS 11n
Specify the disk set to use when creating volumes. All the volumes and hot
spare pools are created in this disk set. If necessary, disks are moved into
the diskset for use in the volumes and hot spare pools. If the diskset doesn't
exist the command creates it. This option is required. \fBmetassist\fR works
entirely within a named disk set. Use of the local, or unnamed disk set, is not
allowed.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR \fIsize\fR\fR
.ad
.RS 11n
Specify the size of the volume to be created. The size argument consists of a
numeric value (a decimal can be specified) followed by KB, MB, GB, or TB,
indicating kilobytes, megabytes, gigabytes, or terabytes, respectively. Case is
ignored when interpreting this option. This option is required.
.RE

.sp
.LP
The following options are optional command line parameters:
.sp
.ne 2
.na
\fB\fB-a\fR \fIdevice1\fR\fB,\fR\fIdevice2\fR\fB,...\fR\fR
.ad
.RS 26n
Explicitly specify the devices that can be used in the creation of this volume.
Named devices may be controllers or disks. Only used when specifying a volume
on the command line.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR\fR
.ad
.RS 26n
Output the command script that would implement the specified or generated
volume configuration. The command script is not run, and processing stops at
this stage.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 26n
Output the volume configuration that satisfies the specified or generated
volume request. No command script is generated or executed, and processing
stops at this stage.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 26n
Specify whether the volume should support automatic component replacement after
a fault. If this option is specified, a mirror is created and its submirrors
are associated with a hot spare.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR \fIname\fR\fR
.ad
.RS 26n
Specify the name of the new volume. See \fBmetainit\fR(1M) for naming
guidelines.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIn\fR\fR
.ad
.RS 26n
Specify the number of required paths to the storage volume. The value of
\fIn\fR cannot be greater than the number of different physical paths and
logical paths to attached storage. Only used when specifying a volume on the
command line.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR \fIn\fR\fR
.ad
.RS 26n
Specify the redundancy level (\fB0\fR-\fB4\fR) of the data. The default is
\fB0\fR. Only used when specifying a volume on the command line. If redundancy
is \fB0\fR, a stripe is created. If redundancy is \fB1\fR or greater, a mirror
with this number of submirrors is created. In this case, the volume can suffer
a disk failure on \fIn\fR\fB-1\fR copies without data loss. With the use of hot
spares (see the \fB-f\fR option), a volume can suffer a disk failure on
\fIn\fR\fB+hsps-1\fR volumes without data loss, assuming non-concurrent
failures.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR \fIdevice1\fR\fB,\fR\fIdevice2\fR\fB,...\fR\fR
.ad
.RS 26n
Explicitly specify devices to exclude in the creation of this volume. Named
devices can be controllers or disks. You can use this option alone, or to
exclude some of the devices listed as available with the \fB-a\fR option, Only
used when specifying a volume on the command line.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR \fIvalue\fR\fR
.ad
.RS 26n
Specify the level of verbosity. Values from \fB0\fR to \fB2\fR are available,
with higher numbers specifying more verbose output when the command is run.
\fB-v\fR \fB0\fR indicates silent output, except for errors or other critical
messages. The default level is \fB1\fR.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.RS 26n
Display program version information.
.RE

.sp
.ne 2
.na
\fB\fB-?\fR\fR
.ad
.RS 26n
Display help information. This option can follow a subcommand for
subcommand-specific help.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreating a Mirror
.sp
.LP
The following example creates a two-way, 36Gb mirror on available devices from
controller 1 and controller 2. It places the volume in diskset \fBmirrorset\fR.

.sp
.in +2
.nf
# metassist create -r 2 -a c1,c2 -s mirrorset -S 36GB
.fi
.in -2
.sp

.LP
\fBExample 2 \fRCreating a Mirror with Additional Fault Tolerance
.sp
.LP
The following example creates a two-way, 36Gb mirror on available devices from
controller 1 and controller 2. It provides additional fault tolerance in the
form of a hot spare. It places the volume in diskset \fBmirrorset\fR.

.sp
.in +2
.nf
# metassist create -f -r 2 -a c1,c2 -s mirrorset -S 36GB
.fi
.in -2
.sp

.LP
\fBExample 3 \fRCreating a Three-way Mirror and Excluding Devices
.sp
.LP
The following example creates a three-way, 180Gb mirror from storage devices on
controller 1 or controller 2. It excludes the disks \fBc1t2d0\fR and
\fBc2t2d1\fR from the volume. It places the volume in diskset \fBmirrorset\fR.

.sp
.in +2
.nf
metassist create -r 3 -a c1,c2 -u c1t2d0, c2t2d1 \e
	-s mirrorset -S 180GB
.fi
.in -2
.sp

.LP
\fBExample 4 \fRDetermining and Implementing a Configuration
.sp
.LP
The following example determines and implements a configuration satisfying the
request specified in a request file:

.sp
.in +2
.nf
# metassist create -F request.xml
.fi
.in -2
.sp

.LP
\fBExample 5 \fRDetermining a Configuration and Saving It in a volume-config
File
.sp
.LP
The following example determines a configuration which satisfies the given
request. It saves the configuration in a volume-config file without
implementing it:

.sp
.in +2
.nf
# metassist create -d -F request.xml > volume-config
.fi
.in -2
.sp

.LP
\fBExample 6 \fRDetermining a Configuration and Saving It in a Shell Script
.sp
.LP
The following example determines a configuration which satisfies the given
request. It saves the configuration in a shell script without implementing it:

.sp
.in +2
.nf
# metassist create -c -F request.xml > setupvols.sh
.fi
.in -2
.sp

.LP
\fBExample 7 \fRImplementing the Given volume-config
.sp
.LP
The following example implements the given volume-config:

.sp
.in +2
.nf
# metassist create -F config.xml
.fi
.in -2
.sp

.LP
\fBExample 8 \fRConverting the Given volume-config to a Shell Script
.sp
.LP
The following example converts the given volume-config to a shell script that
you can run later:

.sp
.in +2
.nf
# metassist create -c -F config.xml > setupvols.sh
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB>\fB0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH FILES
.sp
.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/usr/share/lib/xml/dtd/volume-config.dtd\fR\fR
.ad
.sp .6
.RS 4n

.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Inteface Stability	Stable
.TE

.SH SEE ALSO
.sp
.LP
\fBmdmonitord\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), \fBmetarename\fR(1M), \fBmetareplace\fR(1M),
\fBmetaroot\fR(1M), \fBmetaset\fR(1M), \fBmetastat\fR(1M), \fBmetasync\fR(1M),
\fBmetattach\fR(1M), \fBmd.tab\fR(4), \fBmd.cf\fR(4), \fBmddb.cf\fR(4),
\fBmd.tab\fR(4), \fBvolume-config\fR(4), \fBvolume-request\fR(4),
\fBattributes\fR(5), \fBmd\fR(7D)
.SH NOTES
.sp
.LP
The quality of service arguments are mutually exclusive with the \fB-F\fR
\fIinputfile\fR argument.
.sp
.LP
When specifying a request file or quality of service arguments on the command
line, the \fB/etc/default/metassist.xml\fR file is read for global and per-disk
set defaults.
.sp
.LP
Characteristics of this file are specified in the DTD, in
\fB/usr/share/lib/xml/dtd/volume-defaults.dtd\fR.
.sp
.LP
Characteristics of the XML request file are specified in the DTD, in
\fB/usr/share/lib/xml/dtd/volume-request.dtd\fR.
.sp
.LP
Characteristics of the XML configuration file are specified in the DTD, in
\fB/usr/share/lib/xml/dtd/volume-config.dtd\fR.
.sp
.LP
This command must be run as root.
.sp
.LP
This command requires a functional Solaris Volume Manager configuration before
it runs.