path: root/usr/src/man/man1m/metattach.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 metattach 1M "20 Jun 2006" "SunOS 5.11" "System Administration Commands"
.SH NAME
metattach, metadetach \- attach or detach a metadevice
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/metattach\fR [\fB-h\fR]
.fi

.LP
.nf
\fB/usr/sbin/metattach\fR [\fB-s\fR \fIsetname\fR] \fImirror\fR [\fImetadevice\fR]
.fi

.LP
.nf
\fB/usr/sbin/metattach\fR [\fB-s\fR \fIsetname\fR] [\fB-i\fR \fIinterlace\fR] \fIconcat/stripe\fR \fIcomponent...\fR
.fi

.LP
.nf
\fB/usr/sbin/metattach\fR [\fB-s\fR \fIsetname\fR] \fIRAID\fR \fIcomponent...\fR
.fi

.LP
.nf
\fB/usr/sbin/metattach\fR [\fB-s\fR \fIsetname\fR] [\fB-A\fR \fIalignment\fR] \fIsoftpart\fR \fIsize\fR |\fI all\fR
.fi

.LP
.nf
\fB/usr/sbin/metadetach\fR [\fB-s\fR \fIsetname\fR] [\fB-f\fR] \fImirror\fR \fIsubmirror\fR
.fi

.LP
.nf
\fB/usr/sbin/metadetach\fR [\fB-s\fR \fIsetname\fR] [\fB-f\fR] \fItrans\fR
.fi

.SH DESCRIPTION
.sp
.LP
\fBmetattach\fR adds submirrors to a mirror, grows metadevices, or grows soft
partitions. Growing metadevices can be done without interrupting service. To
grow the size of a mirror or trans, the slices must be added to the submirrors
or to the master devices.
.sp
.LP
Solaris Volume Manager supports storage devices and logical volumes greater
than 1 terabyte (TB) when a system runs a 64-bit Solaris kernel. Support for
large volumes is automatic. If a device greater than 1 TB is created, Solaris
Volume Manager configures it appropriately and without user intervention.
.sp
.LP
If a system with large volumes is rebooted under a 32-bit Solaris kernel, the
large volumes are visible through \fBmetastat\fR output. Large volumes cannot
be accessed, modified or deleted, and no new large volumes can be created. Any
volumes or file systems on a large volume in this situation are also
unavailable. If a system with large volumes is rebooted under a version of
Solaris prior to the Solaris 9 4/03 release, Solaris Volume Manager does not
start. You must remove all large volumes before Solaris Volume Manager runs
under an earlier version of the Solaris Operating System.
.sp
.LP
Solaris Volume Manager supports one-to-four-way mirrors. You can only attach a
metadevice to a mirror if there are three or fewer submirrors beneath the
mirror. Once a new metadevice is attached to a mirror, \fBmetattach\fR
automatically starts a resync operation to the new submirror.
.sp
.LP
\fBmetadetach\fR detaches submirrors from mirrors and logging devices from
trans metadevices.
.sp
.LP
When a submirror is detached from a mirror, it is no longer part of the mirror,
thus reads and writes to and from that metadevice by way of the mirror are no
longer performed through the mirror. Detaching the only existing submirror is
not allowed. Detaching a submirror that has slices reported as needing
maintenance (by \fBmetastat\fR) is not allowed unless the \fB-f\fR (force) flag
is used.
.sp
.LP
\fBmetadetach\fR also detaches the logging device from a trans. This step is
necessary before you can clear the trans volume. Trans metadevices have been
replaced by UFS logging. Existing trans devices are not logging. They pass data
directly through to the underlying device. See \fBmount_ufs\fR(1M) for more
information about UFS logging.
.sp
.LP
Detaching the logging device from a busy trans device is not allowed unless the
\fB-f\fR (force) flag is used. Even so, the logging device is not actually
detached until the trans is idle. The trans is in the \fIDetaching\fR state
(\fBmetastat\fR) until the logging device is detached.
.SH OPTIONS
.sp
.LP
Root privileges are required for all of the following options except \fB-h\fR.
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-A\fR \fIalignment\fR\fR
.ad
.RS 16n
.rt  
Set the value of the soft partition extent alignment. Use this option when it
is important specify a starting offset for the soft partition. It preserves the
data alignment between the metadevice address space and the address space of
the underlying physical device.
.sp
For example, a hardware device that does checksumming should not have its I/O
requests divided by Solaris Volume Manager. In this case, use a value from the
hardware configuration as the value for the alignment. When using this option
in conjunction with a software I/O load, the alignment value corresponds to the
I/O load of the application. This prevents I/O from being divided unnecessarily
and affecting performance.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-f\fR\fR
.ad
.RS 16n
.rt  
Force the detaching of metadevices that have components that need maintenance
or are busy. You can use this option only when a mirror is in a maintenance
state that can be fixed with \fBmetareplace\fR(1M). If the mirror is in a
maintenance state that can only be fixed with \fBmetasync\fR(1M) (as shown by
the output of \fBmetastat\fR(1M)), \fBmetadetach \fR\fB-f\fR has no effect,
because the mirrors must be resynchronized before one of them can be detached.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-h\fR\fR
.ad
.RS 16n
.rt  
Display a usage message.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-i\fR \fIinterlace\fR\fR
.ad
.RS 16n
.rt  
Specify the interlace value for stripes, where \fBsize\fR is a specified value
followed by either \fBk\fR for kilobytes, \fBm\fR for megabytes, or \fBb\fR for
blocks. The units can be either uppercase or lowercase. If \fIsize\fR is not
specified, the size defaults to the interlace size of the last stripe of the
metadevice. When an interlace size change is made on a stripe, it is carried
forward on all stripes that follow.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-s\fR \fIsetname\fR\fR
.ad
.RS 16n
.rt  
Specify the name of the diskset on which the \fBmetattach\fR command or the
\fBmetadetach\fR command works.. Using the \fB-s\fR option causes the command
to perform its administrative function within the specified diskset. Without
this option, the command performs its function on local metadevices.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.mk
.na
\fB\fIcomponent\fR\fR
.ad
.RS 17n
.rt  
The logical name for the physical slice (partition) on a disk drive, such as
\fB/dev/dsk/c0t0d0s2\fR, being added to the concatenation, stripe,
concatenation of stripes, or RAID5 metadevice.
.RE

.sp
.ne 2
.mk
.na
\fB\fIconcat/stripe\fR\fR
.ad
.RS 17n
.rt  
The metadevice name of the concatenation, stripe, or concatenation of stripes.
.RE

.sp
.ne 2
.mk
.na
\fB\fIlog\fR\fR
.ad
.RS 17n
.rt  
The metadevice name of the logging device to be attached to the trans
metadevice.
.RE

.sp
.ne 2
.mk
.na
\fB\fImetadevice\fR\fR
.ad
.RS 17n
.rt  
The metadevice name to be attached to the mirror as a submirror. This
metadevice must have been previously created by the \fBmetainit\fR command.
.RE

.sp
.ne 2
.mk
.na
\fB\fImirror\fR\fR
.ad
.RS 17n
.rt  
The name of the mirror.
.RE

.sp
.ne 2
.mk
.na
\fB\fIRAID\fR\fR
.ad
.RS 17n
.rt  
The metadevice name of the RAID5 metadevice.
.RE

.sp
.ne 2
.mk
.na
\fB\fIsize\fR | \fIall\fR\fR
.ad
.RS 17n
.rt  
The amount of space to add to the soft partition in \fBK\fR or \fBk\fR for
kilobytes, \fBM\fR or \fBm\fR for megabytes, \fBG\fR or \fBg\fR for gigabytes,
\fBT\fR or \fBt\fR for terabytes, and \fBB\fR or \fBb\fR for blocks (sectors).
All values represent powers of 2, and upper and lower case options are
equivalent. Only integer values are permitted. The literal \fBall\fR specifies
that the soft partition should grow to occupy all available space on the
underlying volume.
.RE

.sp
.ne 2
.mk
.na
\fB\fIsoftpart\fR\fR
.ad
.RS 17n
.rt  
The metadevice name of the existing soft partition.
.RE

.sp
.ne 2
.mk
.na
\fB\fIsubmirror\fR\fR
.ad
.RS 17n
.rt  
The metadevice name of the submirror to be detached from the mirror.
.RE

.sp
.ne 2
.mk
.na
\fB\fItrans\fR\fR
.ad
.RS 17n
.rt  
The metadevice name of the trans metadevice (not the master or logging device).
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRConcatenating a New Slice to a Metadevice
.sp
.LP
This example concatenates a single new slice to an existing metadevice,
\fBVolume.1\fR. Afterwards, you would use the \fBgrowfs\fR(1M) command to
expand the file system.

.sp
.in +2
.nf
# metattach Volume.1 /dev/dsk/c0t1d0s2
.fi
.in -2
.sp

.LP
\fBExample 2 \fRDetaching Logging Device from Trans Metadevice
.sp
.LP
This example detaches the logging device from a trans metadevice \fBd9\fR.
Notice that you do not have to specify the logging device itself, as there can
only be one.

.sp
.in +2
.nf
# metadetach d9
.fi
.in -2
.sp

.LP
\fBExample 3 \fRExpanding a RAID5 Metadevice
.sp
.LP
This example expands a RAID5 metadevice, \fBd45\fR, by attaching another slice.

.sp
.in +2
.nf
# metattach d45 /dev/dsk/c3t0d0s2
.fi
.in -2
.sp

.sp
.LP
When you add additional slices to a RAID5 metadevice, the additional space is
devoted to data. No new parity blocks are allocated. The data on the added
slices is, however, included in the overall parity calculations, so it is
protected against single-device failure.

.LP
\fBExample 4 \fRExpanding a Soft Partition
.sp
.LP
The following example expands a soft partition, \fBd42\fR, attaching all space
available on the underlying device.

.sp
.in +2
.nf
# metattach d42 all
.fi
.in -2
.sp

.sp
.LP
When you add additional space to a soft partition, the additional space is
taken from any available space on the slice and might not be contiguous with
the existing soft partition.

.LP
\fBExample 5 \fRAdding Space to Two-Way Mirror
.sp
.LP
This example adds space to a two-way mirror by adding a slice to each
submirror. Afterwards, you would use the \fBgrowfs\fR(1M) command to expand the
file system.

.sp
.in +2
.nf
# metattach d9 /dev/dsk/c0t2d0s5
# metattach d10 /dev/dsk/c0t3d0s5
.fi
.in -2
.sp

.sp
.LP
This example tells the mirror to grow to the size of the underlying devices

.sp
.in +2
.nf
# metattach d11
.fi
.in -2
.sp

.sp
.LP
This example increases the size of the UFS on the device so the space can be
used.

.sp
.in +2
.nf
# growfs -M /export /dev/md/rdsk/d11
.fi
.in -2
.sp

.LP
\fBExample 6 \fRDetaching a Submirror from a Mirror
.sp
.LP
This example detaches a submirror, \fBd2\fR, from a mirror, \fBd4\fR.

.sp
.in +2
.nf
# metadetach d4 d2
.fi
.in -2
.sp

.LP
\fBExample 7 \fRAdding Four Slices to Metadevice
.sp
.LP
This example adds four slices to an existing metadevice, \fBd9\fR. Afterwards,
you would use the \fBgrowfs\fR(1M) command to expand the file system.

.sp
.in +2
.nf
# metattach d9 /dev/dsk/c0t1d0s2 /dev/dsk/c0t2d0s2 \
     /dev/dsk/c0t3d0s2 /dev/dsk/c0t4d0s2
.fi
.in -2
.sp

.LP
\fBExample 8 \fRSetting the Value of the Soft Partition Extent Alignment
.sp
.LP
This example shows how to set the alignment of the soft partition to 1mb when
the soft partition is expanded.

.sp
.in +2
.nf
# metattach -s red -A 2m d13 1m
.fi
.in -2
.sp

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

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

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

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityStable
.TE

.SH SEE ALSO
.sp
.LP
\fBmdmonitord\fR(1M), \fBmetaclear\fR(1M), \fBmetadb\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),
\fBmetassist\fR(1M), \fBmetastat\fR(1M), \fBmetasync\fR(1M), \fBmd.tab\fR(4),
\fBmd.cf\fR(4), \fBmddb.cf\fR(4), \fBmd.tab\fR(4), \fBattributes\fR(5),
\fBmd\fR(7D)
.sp
.LP
\fI\fR
.SH WARNINGS
.sp
.LP
This section provides information regarding warnings for devices greater than 1
TB and for multi-way mirrors.
.SS "Devices and Volumes Greater Than 1 TB"
.sp
.LP
Do not create large (>1 TB) volumes if you expect to run the Solaris Operating
System with a 32-bit kernel or if you expect to use a version of the Solaris
Operating System prior to Solaris 9 4/03.
.SS "Multi-Way Mirrors"
.sp
.LP
When a submirror is detached from its mirror, the data on the metadevice might
not be the same as the data that existed on the mirror prior to running
\fBmetadetach\fR. In particular, if the \fB-f\fR option was needed, the
metadevice and mirror probably do not contain the same data.
.SH NOTES
.sp
.LP
Trans metadevices have been replaced by UFS logging. Existing trans devices are
\fBnot\fR logging. They pass data directly through to the underlying device.
See \fBmount_ufs\fR(1M) for more information about UFS logging.