| blob | 4e6246af703eb6be36a751195eea0765ce8942e7 |
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 METATTACH 1M "Jun 20, 2006"
7 .SH NAME
8 metattach, metadetach \- attach or detach a metadevice
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/sbin/metattach\fR [\fB-h\fR]
13 .fi
15 .LP
16 .nf
17 \fB/usr/sbin/metattach\fR [\fB-s\fR \fIsetname\fR] \fImirror\fR [\fImetadevice\fR]
18 .fi
20 .LP
21 .nf
22 \fB/usr/sbin/metattach\fR [\fB-s\fR \fIsetname\fR] [\fB-i\fR \fIinterlace\fR] \fIconcat/stripe\fR \fIcomponent...\fR
23 .fi
25 .LP
26 .nf
27 \fB/usr/sbin/metattach\fR [\fB-s\fR \fIsetname\fR] \fIRAID\fR \fIcomponent...\fR
28 .fi
30 .LP
31 .nf
32 \fB/usr/sbin/metattach\fR [\fB-s\fR \fIsetname\fR] [\fB-A\fR \fIalignment\fR] \fIsoftpart\fR \fIsize\fR |\fI all\fR
33 .fi
35 .LP
36 .nf
37 \fB/usr/sbin/metadetach\fR [\fB-s\fR \fIsetname\fR] [\fB-f\fR] \fImirror\fR \fIsubmirror\fR
38 .fi
40 .LP
41 .nf
42 \fB/usr/sbin/metadetach\fR [\fB-s\fR \fIsetname\fR] [\fB-f\fR] \fItrans\fR
43 .fi
45 .SH DESCRIPTION
46 .sp
47 .LP
48 \fBmetattach\fR adds submirrors to a mirror, grows metadevices, or grows soft
49 partitions. Growing metadevices can be done without interrupting service. To
50 grow the size of a mirror or trans, the slices must be added to the submirrors
51 or to the master devices.
52 .sp
53 .LP
54 Solaris Volume Manager supports storage devices and logical volumes greater
55 than 1 terabyte (TB) when a system runs a 64-bit Solaris kernel. Support for
56 large volumes is automatic. If a device greater than 1 TB is created, Solaris
57 Volume Manager configures it appropriately and without user intervention.
58 .sp
59 .LP
60 If a system with large volumes is rebooted under a 32-bit Solaris kernel, the
61 large volumes are visible through \fBmetastat\fR output. Large volumes cannot
62 be accessed, modified or deleted, and no new large volumes can be created. Any
63 volumes or file systems on a large volume in this situation are also
64 unavailable. If a system with large volumes is rebooted under a version of
65 Solaris prior to the Solaris 9 4/03 release, Solaris Volume Manager does not
66 start. You must remove all large volumes before Solaris Volume Manager runs
67 under an earlier version of the Solaris Operating System.
68 .sp
69 .LP
70 Solaris Volume Manager supports one-to-four-way mirrors. You can only attach a
71 metadevice to a mirror if there are three or fewer submirrors beneath the
72 mirror. Once a new metadevice is attached to a mirror, \fBmetattach\fR
73 automatically starts a resync operation to the new submirror.
74 .sp
75 .LP
76 \fBmetadetach\fR detaches submirrors from mirrors and logging devices from
77 trans metadevices.
78 .sp
79 .LP
80 When a submirror is detached from a mirror, it is no longer part of the mirror,
81 thus reads and writes to and from that metadevice by way of the mirror are no
82 longer performed through the mirror. Detaching the only existing submirror is
83 not allowed. Detaching a submirror that has slices reported as needing
84 maintenance (by \fBmetastat\fR) is not allowed unless the \fB-f\fR (force) flag
85 is used.
86 .sp
87 .LP
88 \fBmetadetach\fR also detaches the logging device from a trans. This step is
89 necessary before you can clear the trans volume. Trans metadevices have been
90 replaced by UFS logging. Existing trans devices are not logging. They pass data
91 directly through to the underlying device. See \fBmount_ufs\fR(1M) for more
92 information about UFS logging.
93 .sp
94 .LP
95 Detaching the logging device from a busy trans device is not allowed unless the
96 \fB-f\fR (force) flag is used. Even so, the logging device is not actually
97 detached until the trans is idle. The trans is in the \fIDetaching\fR state
98 (\fBmetastat\fR) until the logging device is detached.
99 .SH OPTIONS
100 .sp
101 .LP
102 Root privileges are required for all of the following options except \fB-h\fR.
103 .sp
104 .LP
105 The following options are supported:
106 .sp
107 .ne 2
108 .na
109 \fB\fB-A\fR \fIalignment\fR\fR
110 .ad
111 .RS 16n
112 Set the value of the soft partition extent alignment. Use this option when it
113 is important specify a starting offset for the soft partition. It preserves the
114 data alignment between the metadevice address space and the address space of
115 the underlying physical device.
116 .sp
117 For example, a hardware device that does checksumming should not have its I/O
118 requests divided by Solaris Volume Manager. In this case, use a value from the
119 hardware configuration as the value for the alignment. When using this option
120 in conjunction with a software I/O load, the alignment value corresponds to the
121 I/O load of the application. This prevents I/O from being divided unnecessarily
122 and affecting performance.
123 .RE
125 .sp
126 .ne 2
127 .na
128 \fB\fB-f\fR\fR
129 .ad
130 .RS 16n
131 Force the detaching of metadevices that have components that need maintenance
132 or are busy. You can use this option only when a mirror is in a maintenance
133 state that can be fixed with \fBmetareplace\fR(1M). If the mirror is in a
134 maintenance state that can only be fixed with \fBmetasync\fR(1M) (as shown by
135 the output of \fBmetastat\fR(1M)), \fBmetadetach \fR\fB-f\fR has no effect,
136 because the mirrors must be resynchronized before one of them can be detached.
137 .RE
139 .sp
140 .ne 2
141 .na
142 \fB\fB-h\fR\fR
143 .ad
144 .RS 16n
145 Display a usage message.
146 .RE
148 .sp
149 .ne 2
150 .na
151 \fB\fB-i\fR \fIinterlace\fR\fR
152 .ad
153 .RS 16n
154 Specify the interlace value for stripes, where \fBsize\fR is a specified value
155 followed by either \fBk\fR for kilobytes, \fBm\fR for megabytes, or \fBb\fR for
156 blocks. The units can be either uppercase or lowercase. If \fIsize\fR is not
157 specified, the size defaults to the interlace size of the last stripe of the
158 metadevice. When an interlace size change is made on a stripe, it is carried
159 forward on all stripes that follow.
160 .RE
162 .sp
163 .ne 2
164 .na
165 \fB\fB-s\fR \fIsetname\fR\fR
166 .ad
167 .RS 16n
168 Specify the name of the diskset on which the \fBmetattach\fR command or the
169 \fBmetadetach\fR command works.. Using the \fB-s\fR option causes the command
170 to perform its administrative function within the specified diskset. Without
171 this option, the command performs its function on local metadevices.
172 .RE
174 .SH OPERANDS
175 .sp
176 .LP
177 The following operands are supported:
178 .sp
179 .ne 2
180 .na
181 \fB\fIcomponent\fR\fR
182 .ad
183 .RS 17n
184 The logical name for the physical slice (partition) on a disk drive, such as
185 \fB/dev/dsk/c0t0d0s2\fR, being added to the concatenation, stripe,
186 concatenation of stripes, or RAID5 metadevice.
187 .RE
189 .sp
190 .ne 2
191 .na
192 \fB\fIconcat/stripe\fR\fR
193 .ad
194 .RS 17n
195 The metadevice name of the concatenation, stripe, or concatenation of stripes.
196 .RE
198 .sp
199 .ne 2
200 .na
201 \fB\fIlog\fR\fR
202 .ad
203 .RS 17n
204 The metadevice name of the logging device to be attached to the trans
205 metadevice.
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fB\fImetadevice\fR\fR
212 .ad
213 .RS 17n
214 The metadevice name to be attached to the mirror as a submirror. This
215 metadevice must have been previously created by the \fBmetainit\fR command.
216 .RE
218 .sp
219 .ne 2
220 .na
221 \fB\fImirror\fR\fR
222 .ad
223 .RS 17n
224 The name of the mirror.
225 .RE
227 .sp
228 .ne 2
229 .na
230 \fB\fIRAID\fR\fR
231 .ad
232 .RS 17n
233 The metadevice name of the RAID5 metadevice.
234 .RE
236 .sp
237 .ne 2
238 .na
239 \fB\fIsize\fR | \fIall\fR\fR
240 .ad
241 .RS 17n
242 The amount of space to add to the soft partition in \fBK\fR or \fBk\fR for
243 kilobytes, \fBM\fR or \fBm\fR for megabytes, \fBG\fR or \fBg\fR for gigabytes,
244 \fBT\fR or \fBt\fR for terabytes, and \fBB\fR or \fBb\fR for blocks (sectors).
245 All values represent powers of 2, and upper and lower case options are
246 equivalent. Only integer values are permitted. The literal \fBall\fR specifies
247 that the soft partition should grow to occupy all available space on the
248 underlying volume.
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fIsoftpart\fR\fR
255 .ad
256 .RS 17n
257 The metadevice name of the existing soft partition.
258 .RE
260 .sp
261 .ne 2
262 .na
263 \fB\fIsubmirror\fR\fR
264 .ad
265 .RS 17n
266 The metadevice name of the submirror to be detached from the mirror.
267 .RE
269 .sp
270 .ne 2
271 .na
272 \fB\fItrans\fR\fR
273 .ad
274 .RS 17n
275 The metadevice name of the trans metadevice (not the master or logging device).
276 .RE
278 .SH EXAMPLES
279 .LP
280 \fBExample 1 \fRConcatenating a New Slice to a Metadevice
281 .sp
282 .LP
283 This example concatenates a single new slice to an existing metadevice,
284 \fBVolume.1\fR. Afterwards, you would use the \fBgrowfs\fR(1M) command to
285 expand the file system.
287 .sp
288 .in +2
289 .nf
290 # metattach Volume.1 /dev/dsk/c0t1d0s2
291 .fi
292 .in -2
293 .sp
295 .LP
296 \fBExample 2 \fRDetaching Logging Device from Trans Metadevice
297 .sp
298 .LP
299 This example detaches the logging device from a trans metadevice \fBd9\fR.
300 Notice that you do not have to specify the logging device itself, as there can
301 only be one.
303 .sp
304 .in +2
305 .nf
306 # metadetach d9
307 .fi
308 .in -2
309 .sp
311 .LP
312 \fBExample 3 \fRExpanding a RAID5 Metadevice
313 .sp
314 .LP
315 This example expands a RAID5 metadevice, \fBd45\fR, by attaching another slice.
317 .sp
318 .in +2
319 .nf
320 # metattach d45 /dev/dsk/c3t0d0s2
321 .fi
322 .in -2
323 .sp
325 .sp
326 .LP
327 When you add additional slices to a RAID5 metadevice, the additional space is
328 devoted to data. No new parity blocks are allocated. The data on the added
329 slices is, however, included in the overall parity calculations, so it is
330 protected against single-device failure.
332 .LP
333 \fBExample 4 \fRExpanding a Soft Partition
334 .sp
335 .LP
336 The following example expands a soft partition, \fBd42\fR, attaching all space
337 available on the underlying device.
339 .sp
340 .in +2
341 .nf
342 # metattach d42 all
343 .fi
344 .in -2
345 .sp
347 .sp
348 .LP
349 When you add additional space to a soft partition, the additional space is
350 taken from any available space on the slice and might not be contiguous with
351 the existing soft partition.
353 .LP
354 \fBExample 5 \fRAdding Space to Two-Way Mirror
355 .sp
356 .LP
357 This example adds space to a two-way mirror by adding a slice to each
358 submirror. Afterwards, you would use the \fBgrowfs\fR(1M) command to expand the
359 file system.
361 .sp
362 .in +2
363 .nf
364 # metattach d9 /dev/dsk/c0t2d0s5
365 # metattach d10 /dev/dsk/c0t3d0s5
366 .fi
367 .in -2
368 .sp
370 .sp
371 .LP
372 This example tells the mirror to grow to the size of the underlying devices
374 .sp
375 .in +2
376 .nf
377 # metattach d11
378 .fi
379 .in -2
380 .sp
382 .sp
383 .LP
384 This example increases the size of the UFS on the device so the space can be
385 used.
387 .sp
388 .in +2
389 .nf
390 # growfs -M /export /dev/md/rdsk/d11
391 .fi
392 .in -2
393 .sp
395 .LP
396 \fBExample 6 \fRDetaching a Submirror from a Mirror
397 .sp
398 .LP
399 This example detaches a submirror, \fBd2\fR, from a mirror, \fBd4\fR.
401 .sp
402 .in +2
403 .nf
404 # metadetach d4 d2
405 .fi
406 .in -2
407 .sp
409 .LP
410 \fBExample 7 \fRAdding Four Slices to Metadevice
411 .sp
412 .LP
413 This example adds four slices to an existing metadevice, \fBd9\fR. Afterwards,
414 you would use the \fBgrowfs\fR(1M) command to expand the file system.
416 .sp
417 .in +2
418 .nf
419 # metattach d9 /dev/dsk/c0t1d0s2 /dev/dsk/c0t2d0s2 \
420 /dev/dsk/c0t3d0s2 /dev/dsk/c0t4d0s2
421 .fi
422 .in -2
423 .sp
425 .LP
426 \fBExample 8 \fRSetting the Value of the Soft Partition Extent Alignment
427 .sp
428 .LP
429 This example shows how to set the alignment of the soft partition to 1mb when
430 the soft partition is expanded.
432 .sp
433 .in +2
434 .nf
435 # metattach -s red -A 2m d13 1m
436 .fi
437 .in -2
438 .sp
440 .SH EXIT STATUS
441 .sp
442 .LP
443 The following exit values are returned:
444 .sp
445 .ne 2
446 .na
447 \fB\fB0\fR\fR
448 .ad
449 .RS 6n
450 Successful completion.
451 .RE
453 .sp
454 .ne 2
455 .na
456 \fB\fB>0\fR\fR
457 .ad
458 .RS 6n
459 An error occurred.
460 .RE
462 .SH ATTRIBUTES
463 .sp
464 .LP
465 See \fBattributes\fR(5) for descriptions of the following attributes:
466 .sp
468 .sp
469 .TS
470 box;
471 c | c
472 l | l .
473 ATTRIBUTE TYPE ATTRIBUTE VALUE
474 _
475 Interface Stability Stable
476 .TE
478 .SH SEE ALSO
479 .sp
480 .LP
481 \fBmdmonitord\fR(1M), \fBmetaclear\fR(1M), \fBmetadb\fR(1M), \fBmetahs\fR(1M),
482 \fBmetainit\fR(1M), \fBmetaoffline\fR(1M), \fBmetaonline\fR(1M),
483 \fBmetaparam\fR(1M), \fBmetarecover\fR(1M), \fBmetarename\fR(1M),
484 \fBmetareplace\fR(1M), \fBmetaroot\fR(1M), \fBmetaset\fR(1M),
485 \fBmetassist\fR(1M), \fBmetastat\fR(1M), \fBmetasync\fR(1M), \fBmd.tab\fR(4),
486 \fBmd.cf\fR(4), \fBmddb.cf\fR(4), \fBmd.tab\fR(4), \fBattributes\fR(5),
487 \fBmd\fR(7D)
488 .sp
489 .LP
490 \fI\fR
491 .SH WARNINGS
492 .sp
493 .LP
494 This section provides information regarding warnings for devices greater than 1
495 TB and for multi-way mirrors.
496 .SS "Devices and Volumes Greater Than 1 TB"
497 .sp
498 .LP
499 Do not create large (>1 TB) volumes if you expect to run the Solaris Operating
500 System with a 32-bit kernel or if you expect to use a version of the Solaris
501 Operating System prior to Solaris 9 4/03.
502 .SS "Multi-Way Mirrors"
503 .sp
504 .LP
505 When a submirror is detached from its mirror, the data on the metadevice might
506 not be the same as the data that existed on the mirror prior to running
507 \fBmetadetach\fR. In particular, if the \fB-f\fR option was needed, the
508 metadevice and mirror probably do not contain the same data.
509 .SH NOTES
510 .sp
511 .LP
512 Trans metadevices have been replaced by UFS logging. Existing trans devices are
513 \fBnot\fR logging. They pass data directly through to the underlying device.
514 See \fBmount_ufs\fR(1M) for more information about UFS logging.