| blob | fa12abdc90792e2dbd75f048d6e56aeb06fd906f |
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH METASSIST 1M "Feb 22, 2005"
7 .SH NAME
8 metassist \- automated volume creation utility to support Solaris Volume
9 Manager
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBmetassist\fR \fB-V\fR
14 .fi
16 .LP
17 .nf
18 \fBmetassist\fR \fB-?\fR
19 .fi
21 .LP
22 .nf
23 \fBmetassist\fR create [\fB-v\fR \fIn\fR] [\fB-c\fR] \fB-F\fR \fIconfig_file\fR
24 .fi
26 .LP
27 .nf
28 \fBmetassist\fR create [\fB-v\fR \fIn\fR] [\fB-c\fR | \fB-d\fR] \fB-F\fR \fIrequest_file\fR
29 .fi
31 .LP
32 .nf
33 \fBmetassist\fR create [\fB-v\fR \fIn\fR] [\fB-c\fR | \fB-d\fR] [\fB-f\fR] [\fB-n\fR \fIname\fR]
34 [\fB-p\fR \fIdatapaths\fR] [\fB-r\fR \fIredundancy\fR]
35 [\fB-a\fR \fIavailable\fR [,\fIavailable\fR,\&.\|.\|.]]
36 [\fB-u\fR \fIunavailable\fR [,\fIunavailable\fR,\&.\|.\|.]] \fB-s\fR \fIsetname\fR \fB-S\fR \fIsize\fR
37 .fi
39 .LP
40 .nf
41 \fBmetassist\fR create \fB-?\fR
42 .fi
44 .SH DESCRIPTION
45 .sp
46 .LP
47 The \fBmetassist\fR command provides assistance, through automation, with
48 common Solaris Volume Manager tasks.
49 .SS "SUBCOMMANDS"
50 .sp
51 .LP
52 The following subcommands are supported:
53 .sp
54 .ne 2
55 .na
56 \fB\fBcreate\fR\fR
57 .ad
58 .RS 10n
59 The \fBcreate\fR subcommand creates one or more Solaris Volume Manager volumes.
60 You can specify this request on the command line or in a file specified on the
61 command line.
62 .sp
63 If you create a volume using the command line, you can specify the
64 characteristics of the volume in terms of the desired quality of service it
65 will provide - its size, the number of redundant copies of the data it
66 contains, the number of data paths by which it is accessible, and whether
67 faulty components are replaced automatically. The diskset in which the volume
68 will reside and the volume's size must be specified on the command line in this
69 form of the command.
70 .sp
71 If you create a volume using a request in a file, you can specify the
72 characteristics of the volume in terms of the quality of service they provide,
73 as on the command line. Alternatively, the file can specify the types and
74 component parts of the volume, (for example, mirrors, stripes, concatenations,
75 and their component slices). The file may also specify volumes partly in terms
76 of their types and partly in terms of their component parts, and may specify
77 the characteristics of more than one volume. All volumes specified in a file
78 must reside in the same diskset, whose name must be specified in the file.
79 .sp
80 If you specify the \fB-c\fR or \fB-d\fR option on the command line, the command
81 runs without creating an actual volume or volumes. Instead, it outputs either a
82 a Bourne shell command script (\fB-c\fR option) or a volume configuration
83 (\fB-d\fR option). The command script, when run, creates the specified volume
84 or volumes. The volume configuration specifies the volume or volumes in
85 complete detail, naming all their components.
86 .sp
87 The input file given on the command line can take one of the following forms:
88 .RS +4
89 .TP
90 .ie t \(bu
91 .el o
92 a volume request, which specifies a request for a volume with explicit
93 attributes and components, or matching a given quality of service
94 .RE
95 .RS +4
96 .TP
97 .ie t \(bu
98 .el o
99 a volume configuration, produced by a previous execution of the command
100 .RE
101 .RE
103 .SH OPTIONS
104 .sp
105 .LP
106 The following option is mandatory if you specify a volume request or volume
107 configuration in a file:
108 .sp
109 .ne 2
110 .na
111 \fB\fB-F\fR \fIconfig_file\fR | \fIrequest_file\fR\fR
112 .ad
113 .sp .6
114 .RS 4n
115 Specify the volume request or volume configuration file to process. If
116 \fIconfig_file\fR or \fIrequest_file\fR is \fB-\fR, it is read from standard
117 input.
118 .sp
119 The \fB-d\fR option cannot be specified when \fIinputfile\fR is a volume
120 configuration file.
121 .RE
123 .sp
124 .LP
125 The following options are mandatory if you specify a volume request on the
126 command line:
127 .sp
128 .ne 2
129 .na
130 \fB\fB-s\fR \fIset\fR\fR
131 .ad
132 .RS 11n
133 Specify the disk set to use when creating volumes. All the volumes and hot
134 spare pools are created in this disk set. If necessary, disks are moved into
135 the diskset for use in the volumes and hot spare pools. If the diskset doesn't
136 exist the command creates it. This option is required. \fBmetassist\fR works
137 entirely within a named disk set. Use of the local, or unnamed disk set, is not
138 allowed.
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fB\fB-S\fR \fIsize\fR\fR
145 .ad
146 .RS 11n
147 Specify the size of the volume to be created. The size argument consists of a
148 numeric value (a decimal can be specified) followed by KB, MB, GB, or TB,
149 indicating kilobytes, megabytes, gigabytes, or terabytes, respectively. Case is
150 ignored when interpreting this option. This option is required.
151 .RE
153 .sp
154 .LP
155 The following options are optional command line parameters:
156 .sp
157 .ne 2
158 .na
159 \fB\fB-a\fR \fIdevice1\fR\fB,\fR\fIdevice2\fR\fB,...\fR\fR
160 .ad
161 .RS 26n
162 Explicitly specify the devices that can be used in the creation of this volume.
163 Named devices may be controllers or disks. Only used when specifying a volume
164 on the command line.
165 .RE
167 .sp
168 .ne 2
169 .na
170 \fB\fB-c\fR\fR
171 .ad
172 .RS 26n
173 Output the command script that would implement the specified or generated
174 volume configuration. The command script is not run, and processing stops at
175 this stage.
176 .RE
178 .sp
179 .ne 2
180 .na
181 \fB\fB-d\fR\fR
182 .ad
183 .RS 26n
184 Output the volume configuration that satisfies the specified or generated
185 volume request. No command script is generated or executed, and processing
186 stops at this stage.
187 .RE
189 .sp
190 .ne 2
191 .na
192 \fB\fB-f\fR\fR
193 .ad
194 .RS 26n
195 Specify whether the volume should support automatic component replacement after
196 a fault. If this option is specified, a mirror is created and its submirrors
197 are associated with a hot spare.
198 .RE
200 .sp
201 .ne 2
202 .na
203 \fB\fB-n\fR \fIname\fR\fR
204 .ad
205 .RS 26n
206 Specify the name of the new volume. See \fBmetainit\fR(1M) for naming
207 guidelines.
208 .RE
210 .sp
211 .ne 2
212 .na
213 \fB\fB-p\fR \fIn\fR\fR
214 .ad
215 .RS 26n
216 Specify the number of required paths to the storage volume. The value of
217 \fIn\fR cannot be greater than the number of different physical paths and
218 logical paths to attached storage. Only used when specifying a volume on the
219 command line.
220 .RE
222 .sp
223 .ne 2
224 .na
225 \fB\fB-r\fR \fIn\fR\fR
226 .ad
227 .RS 26n
228 Specify the redundancy level (\fB0\fR-\fB4\fR) of the data. The default is
229 \fB0\fR. Only used when specifying a volume on the command line. If redundancy
230 is \fB0\fR, a stripe is created. If redundancy is \fB1\fR or greater, a mirror
231 with this number of submirrors is created. In this case, the volume can suffer
232 a disk failure on \fIn\fR\fB-1\fR copies without data loss. With the use of hot
233 spares (see the \fB-f\fR option), a volume can suffer a disk failure on
234 \fIn\fR\fB+hsps-1\fR volumes without data loss, assuming non-concurrent
235 failures.
236 .RE
238 .sp
239 .ne 2
240 .na
241 \fB\fB-u\fR \fIdevice1\fR\fB,\fR\fIdevice2\fR\fB,...\fR\fR
242 .ad
243 .RS 26n
244 Explicitly specify devices to exclude in the creation of this volume. Named
245 devices can be controllers or disks. You can use this option alone, or to
246 exclude some of the devices listed as available with the \fB-a\fR option, Only
247 used when specifying a volume on the command line.
248 .RE
250 .sp
251 .ne 2
252 .na
253 \fB\fB-v\fR \fIvalue\fR\fR
254 .ad
255 .RS 26n
256 Specify the level of verbosity. Values from \fB0\fR to \fB2\fR are available,
257 with higher numbers specifying more verbose output when the command is run.
258 \fB-v\fR \fB0\fR indicates silent output, except for errors or other critical
259 messages. The default level is \fB1\fR.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fB-V\fR\fR
266 .ad
267 .RS 26n
268 Display program version information.
269 .RE
271 .sp
272 .ne 2
273 .na
274 \fB\fB-?\fR\fR
275 .ad
276 .RS 26n
277 Display help information. This option can follow a subcommand for
278 subcommand-specific help.
279 .RE
281 .SH EXAMPLES
282 .LP
283 \fBExample 1 \fRCreating a Mirror
284 .sp
285 .LP
286 The following example creates a two-way, 36Gb mirror on available devices from
287 controller 1 and controller 2. It places the volume in diskset \fBmirrorset\fR.
289 .sp
290 .in +2
291 .nf
292 # metassist create -r 2 -a c1,c2 -s mirrorset -S 36GB
293 .fi
294 .in -2
295 .sp
297 .LP
298 \fBExample 2 \fRCreating a Mirror with Additional Fault Tolerance
299 .sp
300 .LP
301 The following example creates a two-way, 36Gb mirror on available devices from
302 controller 1 and controller 2. It provides additional fault tolerance in the
303 form of a hot spare. It places the volume in diskset \fBmirrorset\fR.
305 .sp
306 .in +2
307 .nf
308 # metassist create -f -r 2 -a c1,c2 -s mirrorset -S 36GB
309 .fi
310 .in -2
311 .sp
313 .LP
314 \fBExample 3 \fRCreating a Three-way Mirror and Excluding Devices
315 .sp
316 .LP
317 The following example creates a three-way, 180Gb mirror from storage devices on
318 controller 1 or controller 2. It excludes the disks \fBc1t2d0\fR and
319 \fBc2t2d1\fR from the volume. It places the volume in diskset \fBmirrorset\fR.
321 .sp
322 .in +2
323 .nf
324 metassist create -r 3 -a c1,c2 -u c1t2d0, c2t2d1 \e
325 -s mirrorset -S 180GB
326 .fi
327 .in -2
328 .sp
330 .LP
331 \fBExample 4 \fRDetermining and Implementing a Configuration
332 .sp
333 .LP
334 The following example determines and implements a configuration satisfying the
335 request specified in a request file:
337 .sp
338 .in +2
339 .nf
340 # metassist create -F request.xml
341 .fi
342 .in -2
343 .sp
345 .LP
346 \fBExample 5 \fRDetermining a Configuration and Saving It in a volume-config
347 File
348 .sp
349 .LP
350 The following example determines a configuration which satisfies the given
351 request. It saves the configuration in a volume-config file without
352 implementing it:
354 .sp
355 .in +2
356 .nf
357 # metassist create -d -F request.xml > volume-config
358 .fi
359 .in -2
360 .sp
362 .LP
363 \fBExample 6 \fRDetermining a Configuration and Saving It in a Shell Script
364 .sp
365 .LP
366 The following example determines a configuration which satisfies the given
367 request. It saves the configuration in a shell script without implementing it:
369 .sp
370 .in +2
371 .nf
372 # metassist create -c -F request.xml > setupvols.sh
373 .fi
374 .in -2
375 .sp
377 .LP
378 \fBExample 7 \fRImplementing the Given volume-config
379 .sp
380 .LP
381 The following example implements the given volume-config:
383 .sp
384 .in +2
385 .nf
386 # metassist create -F config.xml
387 .fi
388 .in -2
389 .sp
391 .LP
392 \fBExample 8 \fRConverting the Given volume-config to a Shell Script
393 .sp
394 .LP
395 The following example converts the given volume-config to a shell script that
396 you can run later:
398 .sp
399 .in +2
400 .nf
401 # metassist create -c -F config.xml > setupvols.sh
402 .fi
403 .in -2
404 .sp
406 .SH EXIT STATUS
407 .sp
408 .LP
409 The following exit values are returned:
410 .sp
411 .ne 2
412 .na
413 \fB\fB0\fR\fR
414 .ad
415 .RS 6n
416 Successful completion.
417 .RE
419 .sp
420 .ne 2
421 .na
422 \fB>\fB0\fR\fR
423 .ad
424 .RS 6n
425 An error occurred.
426 .RE
428 .SH FILES
429 .sp
430 .ne 2
431 .na
432 \fB\fB/usr/share/lib/xml/dtd/volume-request.dtd\fR\fR
433 .ad
434 .sp .6
435 .RS 4n
437 .RE
439 .sp
440 .ne 2
441 .na
442 \fB\fB/usr/share/lib/xml/dtd/volume-defaults.dtd\fR\fR
443 .ad
444 .sp .6
445 .RS 4n
447 .RE
449 .sp
450 .ne 2
451 .na
452 \fB\fB/usr/share/lib/xml/dtd/volume-config.dtd\fR\fR
453 .ad
454 .sp .6
455 .RS 4n
457 .RE
459 .SH ATTRIBUTES
460 .sp
461 .LP
462 See \fBattributes\fR(5) for descriptions of the following attributes:
463 .sp
465 .sp
466 .TS
467 box;
468 c | c
469 l | l .
470 ATTRIBUTE TYPE ATTRIBUTE VALUE
471 _
472 Inteface Stability Stable
473 .TE
475 .SH SEE ALSO
476 .sp
477 .LP
478 \fBmdmonitord\fR(1M), \fBmetaclear\fR(1M), \fBmetadb\fR(1M),
479 \fBmetadetach\fR(1M), \fBmetahs\fR(1M), \fBmetainit\fR(1M),
480 \fBmetaoffline\fR(1M), \fBmetaonline\fR(1M), \fBmetaparam\fR(1M),
481 \fBmetarecover\fR(1M), \fBmetarename\fR(1M), \fBmetareplace\fR(1M),
482 \fBmetaroot\fR(1M), \fBmetaset\fR(1M), \fBmetastat\fR(1M), \fBmetasync\fR(1M),
483 \fBmetattach\fR(1M), \fBmd.tab\fR(4), \fBmd.cf\fR(4), \fBmddb.cf\fR(4),
484 \fBmd.tab\fR(4), \fBvolume-config\fR(4), \fBvolume-request\fR(4),
485 \fBattributes\fR(5), \fBmd\fR(7D)
486 .SH NOTES
487 .sp
488 .LP
489 The quality of service arguments are mutually exclusive with the \fB-F\fR
490 \fIinputfile\fR argument.
491 .sp
492 .LP
493 When specifying a request file or quality of service arguments on the command
494 line, the \fB/etc/default/metassist.xml\fR file is read for global and per-disk
495 set defaults.
496 .sp
497 .LP
498 Characteristics of this file are specified in the DTD, in
499 \fB/usr/share/lib/xml/dtd/volume-defaults.dtd\fR.
500 .sp
501 .LP
502 Characteristics of the XML request file are specified in the DTD, in
503 \fB/usr/share/lib/xml/dtd/volume-request.dtd\fR.
504 .sp
505 .LP
506 Characteristics of the XML configuration file are specified in the DTD, in
507 \fB/usr/share/lib/xml/dtd/volume-config.dtd\fR.
508 .sp
509 .LP
510 This command must be run as root.
511 .sp
512 .LP
513 This command requires a functional Solaris Volume Manager configuration before
514 it runs.