usr/src/man/man1m/metarename.1m

   1 '\" te
   2 .\" Copyright (c) 2003, 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 METARENAME 1M "Mar 26, 2006"
   7 .SH NAME
   8 metarename \- rename metadevice or switch layered metadevice names
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/usr/sbin/metarename\fR [\fB-s\fR \fIsetname\fR] \fImetadevice1\fR \fImetadevice2\fR
  13 .fi
  14
  15 .LP
  16 .nf
  17 \fB/usr/sbin/metarename\fR [\fB-s\fR \fIsetname\fR] [\fB-f\fR] \fB-x\fR \fImetadevice1\fR \fImetadevice2\fR
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fB/usr/sbin/metarename\fR \fB-h\fR
  23 .fi
  24
  25 .SH DESCRIPTION
  26 .sp
  27 .LP
  28 There are two ways to use \fBmetarename\fR, one with and one without the
  29 \fB-x\fR option. The first method (without \fB-x\fR) renames an existing
  30 metadevice to a new name. This makes managing the metadevice namespace easier.
  31 The metadevice being renamed cannot be mounted or open, nor can the new name
  32 already exist. For example, to rename a metadevice that contains a mounted file
  33 system, you would first need to unmount the file system.
  34 .sp
  35 .LP
  36 With the second way to use \fBmetarename\fR, using the \fB-x\fR option,
  37 \fBmetarename\fR switches (exchanges) the names of an existing layered
  38 metadevice and one of its subdevices. In Solaris Volume Manager terms, a
  39 layered metadevice can be either a mirror or a trans metadevice. The \fB-x\fR
  40 option enables you to switch the metadevice names of a mirror and one of its
  41 submirrors, or a trans metadevice and its master device.
  42 .sp
  43 .LP
  44 \fBmetarename\fR \fB-x\fR makes it easier to mirror or unmirror an existing
  45 stripe or concatenation, and to remove a trans device.
  46 .sp
  47 .LP
  48 When used to mirror an existing stripe or concatenatation, you must stop access
  49 to the device. For example, if the device contains a mounted file system, you
  50 must first unmount the file system before doing the rename.
  51 .sp
  52 .LP
  53 You can also use the \fBmetarename\fR \fB-x\fR command to untrans a trans
  54 metadevice from an existing device. This applies only to the master device. You
  55 cannot remove a logging device with \fBmetarename\fR. Before you can rename a
  56 trans device, you must detach the logging device. Then you must stop access to
  57 the trans metadevice itself.
  58 .sp
  59 .LP
  60 You cannot rename or switch metadevices that are in an error state or that have
  61 subcomponents in an error state, or metadevices actively using a hot spare
  62 replacement.
  63 .sp
  64 .LP
  65 You can only switch metadevices that have a direct child/parent relationship.
  66 You could not, for example, directly exchange a stripe in a mirror that is a
  67 master device with the trans metadevice.
  68 .sp
  69 .LP
  70 You must use the \fB-f\fR flag when switching members of a trans metadevice.
  71 .sp
  72 .LP
  73 Only metadevices can be switched, not slices.
  74 .SH OPTIONS
  75 .sp
  76 .LP
  77 The following options are supported:
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fB-f\fR\fR
  82 .ad
  83 .RS 15n
  84 Force the switching of trans metadevice members.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fB-h\fR\fR
  91 .ad
  92 .RS 15n
  93 Display a help message.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fB-s\fR \fB\fIsetname\fR\fR\fR
 100 .ad
 101 .RS 15n
 102 Specifies the name of the diskset on which \fBmetarename\fR will work. Using
 103 the \fB-s\fR option will cause the command to perform its administrative
 104 function within the specified diskset. Without this option, the command will
 105 perform its function on the local metadevices.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fB-x\fR\fR
 112 .ad
 113 .RS 15n
 114 Exchange the metadevice names \fImetadevice1\fR and \fImetadevice2\fR.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fImetadevice1\fR\fR
 121 .ad
 122 .RS 15n
 123 Specifies the metadevice to be renamed or switched.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fImetadevice2\fR\fR
 130 .ad
 131 .RS 15n
 132 Specifies the target metadevice name for the rename or switch operation.
 133 .RE
 134
 135 .SH EXAMPLES
 136 .LP
 137 \fBExample 1 \fRRenaming a Metadevice
 138 .sp
 139 .LP
 140 This example renames a metadevice named \fBd10\fR to \fBaccount_records\fR.
 141 Note that \fBaccount_records\fR must not exist for the rename to succeed.
 142
 143 .sp
 144 .in +2
 145 .nf
 146 # metarename d10 account_records
 147 .fi
 148 .in -2
 149 .sp
 150
 151 .LP
 152 \fBExample 2 \fRCreating a Two-Way Mirror
 153 .sp
 154 .LP
 155 This example creates a two-way mirror from an existing stripe named \fBd1\fR
 156 with a mounted file system, \fB/home2\fR.
 157
 158 .sp
 159 .in +2
 160 .nf
 161 # metainit d2 1 1 c13d0s1
 162 # metainit -f d20 -m d1
 163 # umount /home2
 164 # metarename -x d20 d1
 165 # metattach d1 d2
 166 # mount /home2
 167 .fi
 168 .in -2
 169 .sp
 170
 171 .sp
 172 .LP
 173 First, a second concatenation \fBd2\fR, is created. (\fBd1\fR already exists.)
 174 The \fBmetainit\fR command creates a one-way mirror, \fBd20\fR, from \fBd1\fR.
 175 Next, you umount the file system and switch \fBd1\fR for \fBd20\fR, making
 176 \fBd1\fR the top-level device (mirror). You attach the second submirror,
 177 \fBd2\fR, to create a two-way mirror. Lastly, you remount the file system.
 178
 179 .LP
 180 \fBExample 3 \fRMounting a Mirrored File System on Stripe
 181 .sp
 182 .LP
 183 This example takes an existing mirror named \fBd1\fR with a mounted file
 184 system, and ends up with the file system mounted on a stripe \fBd1\fR.
 185
 186 .sp
 187 .in +2
 188 .nf
 189 # umount /fs2
 190 # metarename -x d1 d20
 191 # metadetach d20 d1
 192 # metaclear -r d20
 193 # mount /fs2
 194 .fi
 195 .in -2
 196 .sp
 197
 198 .sp
 199 .LP
 200 First, you unmount the file system, then switch the mirror \fBd1\fR and its
 201 submirror \fBd20\fR. This makes the mirror into \fBd20\fR. Next, you detach
 202 \fBd1\fR from \fBd20\fR, then delete the mirror \fBd20\fR and its other
 203 submirror. You then remount the file system.
 204
 205 .LP
 206 \fBExample 4 \fRDeleting a Trans Metadevice
 207 .sp
 208 .LP
 209 This example deletes a trans metadevice named \fBd10\fR while its mount point
 210 is \fB/myhome\fR. The master device, which is a stripe, is named \fBd2\fR. The
 211 logging device, also a stripe, is named \fBd5\fR.
 212
 213 .sp
 214 .in +2
 215 .nf
 216 # umount /myhome
 217 # metadetach d10
 218 # metarename -f -x d10 d2
 219 # metaclear d2
 220 # metaclear d5
 221 # fsck /dev/md/dsk/d10
 222 # mount /myhome
 223 .fi
 224 .in -2
 225 .sp
 226
 227 .sp
 228 .LP
 229 You umount the file system first, then detach the trans metadevice's logging
 230 device. The trans metadevice is switched with the master device, making the
 231 trans metadevice \fBd2\fR and the underlying stripe \fBd10\fR. You clear the
 232 trans metadevice \fBd2\fR and the logging device \fBd5\fR. \fBd10\fR must be
 233 \fBfsck\fR'd, and then the file system is remounted.
 234
 235 .SH EXIT STATUS
 236 .sp
 237 .LP
 238 The following exit values are returned:
 239 .sp
 240 .ne 2
 241 .na
 242 \fB\fB0\fR\fR
 243 .ad
 244 .RS 6n
 245 Successful completion.
 246 .RE
 247
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fB>0\fR\fR
 252 .ad
 253 .RS 6n
 254 An error occurred.
 255 .RE
 256
 257 .SH ATTRIBUTES
 258 .sp
 259 .LP
 260 See \fBattributes\fR(5) for descriptions of the following attributes:
 261 .sp
 262
 263 .sp
 264 .TS
 265 box;
 266 c | c
 267 l | l .
 268 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 269 _
 270 Interface Stability     Stable
 271 .TE
 272
 273 .SH SEE ALSO
 274 .sp
 275 .LP
 276 \fBmdmonitord\fR(1M), \fBmetaclear\fR(1M), \fBmetadb\fR(1M),
 277 \fBmetadetach\fR(1M), \fBmetahs\fR(1M), \fBmetainit\fR(1M),
 278 \fBmetaoffline\fR(1M), \fBmetaonline\fR(1M), \fBmetaparam\fR(1M),
 279 \fBmetarecover\fR(1M), \fBmetareplace\fR(1M), \fBmetaroot\fR(1M),
 280 \fBmetaset\fR(1M), \fBmetassist\fR(1M), \fBmetastat\fR(1M), \fBmetasync\fR(1M),
 281 \fBmetattach\fR(1M), \fBmd.tab\fR(4), \fBmd.cf\fR(4), \fBmddb.cf\fR(4),
 282 \fBmd.tab\fR(4), \fBattributes\fR(5), \fBmd\fR(7D)
 283 .sp
 284 .LP
 285 \fI\fR
 286 .SH LIMITATIONS
 287 .sp
 288 .LP
 289 Renaming and exchanging metadevice names can only be used for metadevices. A
 290 physical slice cannot be renamed to a metadevice, nor can a metadevice be
 291 exchanged with a physical slice name.
 292 .sp
 293 .LP
 294 Metadevice names are strings of the pattern \fId\fR\fB<\fR\fIxyz\fR\fB>\fR
 295 where \fIxyz\fR is a value between \fB0\fR and \fB8192\fR. You cannot use
 296 logical names for metadevices.
 297 .SH NOTES
 298 .sp
 299 .LP
 300 Trans metadevices have been replaced by UFS logging. Existing trans devices are
 301 \fBnot\fR logging--they pass data directly through to the underlying device.
 302 See \fBmount_ufs\fR(1M) for more information about UFS logging.