'\" 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 METARENAME 1M "Mar 26, 2006"
.SH NAME
metarename \- rename metadevice or switch layered metadevice names
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/metarename\fR [\fB-s\fR \fIsetname\fR] \fImetadevice1\fR \fImetadevice2\fR
.fi

.LP
.nf
\fB/usr/sbin/metarename\fR [\fB-s\fR \fIsetname\fR] [\fB-f\fR] \fB-x\fR \fImetadevice1\fR \fImetadevice2\fR
.fi

.LP
.nf
\fB/usr/sbin/metarename\fR \fB-h\fR
.fi

.SH DESCRIPTION
.sp
.LP
There are two ways to use \fBmetarename\fR, one with and one without the
\fB-x\fR option. The first method (without \fB-x\fR) renames an existing
metadevice to a new name. This makes managing the metadevice namespace easier.
The metadevice being renamed cannot be mounted or open, nor can the new name
already exist. For example, to rename a metadevice that contains a mounted file
system, you would first need to unmount the file system.
.sp
.LP
With the second way to use \fBmetarename\fR, using the \fB-x\fR option,
\fBmetarename\fR switches (exchanges) the names of an existing layered
metadevice and one of its subdevices. In Solaris Volume Manager terms, a
layered metadevice can be either a mirror or a trans metadevice. The \fB-x\fR
option enables you to switch the metadevice names of a mirror and one of its
submirrors, or a trans metadevice and its master device.
.sp
.LP
\fBmetarename\fR \fB-x\fR makes it easier to mirror or unmirror an existing
stripe or concatenation, and to remove a trans device.
.sp
.LP
When used to mirror an existing stripe or concatenatation, you must stop access
to the device. For example, if the device contains a mounted file system, you
must first unmount the file system before doing the rename.
.sp
.LP
You can also use the \fBmetarename\fR \fB-x\fR command to untrans a trans
metadevice from an existing device. This applies only to the master device. You
cannot remove a logging device with \fBmetarename\fR. Before you can rename a
trans device, you must detach the logging device. Then you must stop access to
the trans metadevice itself.
.sp
.LP
You cannot rename or switch metadevices that are in an error state or that have
subcomponents in an error state, or metadevices actively using a hot spare
replacement.
.sp
.LP
You can only switch metadevices that have a direct child/parent relationship.
You could not, for example, directly exchange a stripe in a mirror that is a
master device with the trans metadevice.
.sp
.LP
You must use the \fB-f\fR flag when switching members of a trans metadevice.
.sp
.LP
Only metadevices can be switched, not slices.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 15n
Force the switching of trans metadevice members.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.RS 15n
Display a help message.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fB\fIsetname\fR\fR\fR
.ad
.RS 15n
Specifies the name of the diskset on which \fBmetarename\fR will work. Using
the \fB-s\fR option will cause the command to perform its administrative
function within the specified diskset. Without this option, the command will
perform its function on the local metadevices.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 15n
Exchange the metadevice names \fImetadevice1\fR and \fImetadevice2\fR.
.RE

.sp
.ne 2
.na
\fB\fImetadevice1\fR\fR
.ad
.RS 15n
Specifies the metadevice to be renamed or switched.
.RE

.sp
.ne 2
.na
\fB\fImetadevice2\fR\fR
.ad
.RS 15n
Specifies the target metadevice name for the rename or switch operation.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRRenaming a Metadevice
.sp
.LP
This example renames a metadevice named \fBd10\fR to \fBaccount_records\fR.
Note that \fBaccount_records\fR must not exist for the rename to succeed.

.sp
.in +2
.nf
# metarename d10 account_records
.fi
.in -2
.sp

.LP
\fBExample 2 \fRCreating a Two-Way Mirror
.sp
.LP
This example creates a two-way mirror from an existing stripe named \fBd1\fR
with a mounted file system, \fB/home2\fR.

.sp
.in +2
.nf
# metainit d2 1 1 c13d0s1
# metainit -f d20 -m d1
# umount /home2
# metarename -x d20 d1
# metattach d1 d2
# mount /home2
.fi
.in -2
.sp

.sp
.LP
First, a second concatenation \fBd2\fR, is created. (\fBd1\fR already exists.)
The \fBmetainit\fR command creates a one-way mirror, \fBd20\fR, from \fBd1\fR.
Next, you umount the file system and switch \fBd1\fR for \fBd20\fR, making
\fBd1\fR the top-level device (mirror). You attach the second submirror,
\fBd2\fR, to create a two-way mirror. Lastly, you remount the file system.

.LP
\fBExample 3 \fRMounting a Mirrored File System on Stripe
.sp
.LP
This example takes an existing mirror named \fBd1\fR with a mounted file
system, and ends up with the file system mounted on a stripe \fBd1\fR.

.sp
.in +2
.nf
# umount /fs2
# metarename -x d1 d20
# metadetach d20 d1
# metaclear -r d20
# mount /fs2
.fi
.in -2
.sp

.sp
.LP
First, you unmount the file system, then switch the mirror \fBd1\fR and its
submirror \fBd20\fR. This makes the mirror into \fBd20\fR. Next, you detach
\fBd1\fR from \fBd20\fR, then delete the mirror \fBd20\fR and its other
submirror. You then remount the file system.

.LP
\fBExample 4 \fRDeleting a Trans Metadevice
.sp
.LP
This example deletes a trans metadevice named \fBd10\fR while its mount point
is \fB/myhome\fR. The master device, which is a stripe, is named \fBd2\fR. The
logging device, also a stripe, is named \fBd5\fR.

.sp
.in +2
.nf
# umount /myhome
# metadetach d10
# metarename -f -x d10 d2
# metaclear d2
# metaclear d5
# fsck /dev/md/dsk/d10
# mount /myhome
.fi
.in -2
.sp

.sp
.LP
You umount the file system first, then detach the trans metadevice's logging
device. The trans metadevice is switched with the master device, making the
trans metadevice \fBd2\fR and the underlying stripe \fBd10\fR. You clear the
trans metadevice \fBd2\fR and the logging device \fBd5\fR. \fBd10\fR must be
\fBfsck\fR'd, and then the file system is remounted.

.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\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.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
_
Interface 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), \fBmetareplace\fR(1M), \fBmetaroot\fR(1M),
\fBmetaset\fR(1M), \fBmetassist\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), \fBattributes\fR(5), \fBmd\fR(7D)
.sp
.LP
\fI\fR
.SH LIMITATIONS
.sp
.LP
Renaming and exchanging metadevice names can only be used for metadevices. A
physical slice cannot be renamed to a metadevice, nor can a metadevice be
exchanged with a physical slice name.
.sp
.LP
Metadevice names are strings of the pattern \fId\fR\fB<\fR\fIxyz\fR\fB>\fR
where \fIxyz\fR is a value between \fB0\fR and \fB8192\fR. You cannot use
logical names for metadevices.
.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.