sbin/geom/class/mirror/gmirror.8

   1 .\" Copyright (c) 2004-2009 Pawel Jakub Dawidek <pjd@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd December 27, 2013
  28 .Dt GMIRROR 8
  29 .Os
  30 .Sh NAME
  31 .Nm gmirror
  32 .Nd "control utility for mirrored devices"
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Cm label
  36 .Op Fl Fhnv
  37 .Op Fl b Ar balance
  38 .Op Fl s Ar slice
  39 .Ar name
  40 .Ar prov ...
  41 .Nm
  42 .Cm clear
  43 .Op Fl v
  44 .Ar prov ...
  45 .Nm
  46 .Cm configure
  47 .Op Fl adfFhnv
  48 .Op Fl b Ar balance
  49 .Op Fl s Ar slice
  50 .Ar name
  51 .Nm
  52 .Cm configure
  53 .Op Fl v
  54 .Fl p Ar priority
  55 .Ar name
  56 .Ar prov
  57 .Nm
  58 .Cm rebuild
  59 .Op Fl v
  60 .Ar name
  61 .Ar prov ...
  62 .Nm
  63 .Cm resize
  64 .Op Fl v
  65 .Op Fl s Ar size
  66 .Ar name
  67 .Nm
  68 .Cm insert
  69 .Op Fl hiv
  70 .Op Fl p Ar priority
  71 .Ar name
  72 .Ar prov ...
  73 .Nm
  74 .Cm remove
  75 .Op Fl v
  76 .Ar name
  77 .Ar prov ...
  78 .Nm
  79 .Cm activate
  80 .Op Fl v
  81 .Ar name
  82 .Ar prov ...
  83 .Nm
  84 .Cm deactivate
  85 .Op Fl v
  86 .Ar name
  87 .Ar prov ...
  88 .Nm
  89 .Cm destroy
  90 .Op Fl fv
  91 .Ar name ...
  92 .Nm
  93 .Cm forget
  94 .Op Fl v
  95 .Ar name ...
  96 .Nm
  97 .Cm stop
  98 .Op Fl fv
  99 .Ar name ...
 100 .Nm
 101 .Cm dump
 102 .Ar prov ...
 103 .Nm
 104 .Cm list
 105 .Nm
 106 .Cm status
 107 .Nm
 108 .Cm load
 109 .Nm
 110 .Cm unload
 111 .Sh DESCRIPTION
 112 The
 113 .Nm
 114 utility is used for mirror (RAID1) configurations.
 115 After a mirror's creation, all components are detected and configured
 116 automatically.
 117 All operations like failure detection, stale component detection, rebuild
 118 of stale components, etc.\& are also done automatically.
 119 The
 120 .Nm
 121 utility uses on-disk metadata (stored in the provider's last sector) to store all needed
 122 information.
 123 Since the last sector is used for this purpose, it is possible to place a root
 124 file system on a mirror.
 125 .Pp
 126 The first argument to
 127 .Nm
 128 indicates an action to be performed:
 129 .Bl -tag -width ".Cm deactivate"
 130 .It Cm label
 131 Create a mirror.
 132 The order of components is important, because a component's priority is based on its position
 133 (starting from 0 to 255).
 134 The component with the biggest priority is used by the
 135 .Cm prefer
 136 balance algorithm
 137 and is also used as a master component when resynchronization is needed,
 138 e.g.\& after a power failure when the device was open for writing.
 139 .Pp
 140 Additional options include:
 141 .Bl -tag -width ".Fl b Ar balance"
 142 .It Fl b Ar balance
 143 Specifies balance algorithm to use, one of:
 144 .Bl -tag -width ".Cm round-robin"
 145 .It Cm load
 146 Read from the component with the lowest load.
 147 This is the default balance algorithm.
 148 .It Cm prefer
 149 Read from the component with the biggest priority.
 150 .It Cm round-robin
 151 Use round-robin algorithm when choosing component to read.
 152 .It Cm split
 153 Split read requests, which are bigger than or equal to slice size on N pieces,
 154 where N is the number of active components.
 155 .El
 156 .It Fl F
 157 Do not synchronize after a power failure or system crash.
 158 Assumes device is in consistent state.
 159 .It Fl h
 160 Hardcode providers' names in metadata.
 161 .It Fl n
 162 Turn off autosynchronization of stale components.
 163 .It Fl s Ar slice
 164 When using the
 165 .Cm split
 166 balance algorithm and an I/O READ request is bigger than or equal to this value,
 167 the I/O request will be split into N pieces, where N is the number of active
 168 components.
 169 Defaults to 4096 bytes.
 170 .El
 171 .It Cm clear
 172 Clear metadata on the given providers.
 173 .It Cm configure
 174 Configure the given device.
 175 .Pp
 176 Additional options include:
 177 .Bl -tag -width ".Fl p Ar priority"
 178 .It Fl a
 179 Turn on autosynchronization of stale components.
 180 .It Fl b Ar balance
 181 Specifies balance algorithm to use.
 182 .It Fl d
 183 Do not hardcode providers' names in metadata.
 184 .It Fl f
 185 Synchronize device after a power failure or system crash.
 186 .It Fl F
 187 Do not synchronize after a power failure or system crash.
 188 Assumes device is in consistent state.
 189 .It Fl h
 190 Hardcode providers' names in metadata.
 191 .It Fl n
 192 Turn off autosynchronization of stale components.
 193 .It Fl p Ar priority
 194 Specifies priority for the given component
 195 .Ar prov .
 196 .It Fl s Ar slice
 197 Specifies slice size for
 198 .Cm split
 199 balance algorithm.
 200 .El
 201 .It Cm rebuild
 202 Rebuild the given mirror components forcibly.
 203 If autosynchronization was not turned off for the given device, this command
 204 should be unnecessary.
 205 .It Cm resize
 206 Change the size of the given mirror.
 207 .Pp
 208 Additional options include:
 209 .Bl -tag -width ".Fl s Ar size"
 210 .It Fl s Ar size
 211 New size of the mirror is expressed in logical block numbers.
 212 This option can be omitted, then it will be automatically calculated to
 213 maximum available size.
 214 .El
 215 .It Cm insert
 216 Add the given component(s) to the existing mirror.
 217 .Pp
 218 Additional options include:
 219 .Bl -tag -width ".Fl p Ar priority"
 220 .It Fl h
 221 Hardcode providers' names in metadata.
 222 .It Fl i
 223 Mark component(s) as inactive immediately after insertion.
 224 .It Fl p Ar priority
 225 Specifies priority of the given component(s).
 226 .El
 227 .It Cm remove
 228 Remove the given component(s) from the mirror and clear metadata on it.
 229 .It Cm activate
 230 Activate the given component(s), which were marked as inactive before.
 231 .It Cm deactivate
 232 Mark the given component(s) as inactive, so it will not be automatically
 233 connected to the mirror.
 234 .It Cm destroy
 235 Stop the given mirror and clear metadata on all its components.
 236 .Pp
 237 Additional options include:
 238 .Bl -tag -width ".Fl f"
 239 .It Fl f
 240 Stop the given mirror even if it is opened.
 241 .El
 242 .It Cm forget
 243 Forget about components which are not connected.
 244 This command is useful when a disk has failed and cannot be reconnected, preventing the
 245 .Cm remove
 246 command from being used to remove it.
 247 .It Cm stop
 248 Stop the given mirror.
 249 .Pp
 250 Additional options include:
 251 .Bl -tag -width ".Fl f"
 252 .It Fl f
 253 Stop the given mirror even if it is opened.
 254 .El
 255 .It Cm dump
 256 Dump metadata stored on the given providers.
 257 .It Cm list
 258 See
 259 .Xr geom 8 .
 260 .It Cm status
 261 See
 262 .Xr geom 8 .
 263 .It Cm load
 264 See
 265 .Xr geom 8 .
 266 .It Cm unload
 267 See
 268 .Xr geom 8 .
 269 .El
 270 .Pp
 271 Additional options include:
 272 .Bl -tag -width ".Fl v"
 273 .It Fl v
 274 Be more verbose.
 275 .El
 276 .Sh EXIT STATUS
 277 Exit status is 0 on success, and 1 if the command fails.
 278 .Sh EXAMPLES
 279 Use 3 disks to setup a mirror.
 280 Choose split balance algorithm, split only
 281 requests which are bigger than or equal to 2kB.
 282 Create file system,
 283 mount it, then unmount it and stop device:
 284 .Bd -literal -offset indent
 285 gmirror label -v -b split -s 2048 data da0 da1 da2
 286 newfs /dev/mirror/data
 287 mount /dev/mirror/data /mnt
 288 \&...
 289 umount /mnt
 290 gmirror stop data
 291 gmirror unload
 292 .Ed
 293 .Pp
 294 Create a mirror on disk with valid data (note that the last sector of the disk
 295 will be overwritten).
 296 Add another disk to this mirror,
 297 so it will be synchronized with existing disk:
 298 .Bd -literal -offset indent
 299 gmirror label -v -b round-robin data da0
 300 gmirror insert data da1
 301 .Ed
 302 .Pp
 303 Create a mirror, but do not use automatic synchronization feature.
 304 Add another disk and rebuild it:
 305 .Bd -literal -offset indent
 306 gmirror label -v -n -b load data da0 da1
 307 gmirror insert data da2
 308 gmirror rebuild data da2
 309 .Ed
 310 .Pp
 311 One disk failed.
 312 Replace it with a brand new one:
 313 .Bd -literal -offset indent
 314 gmirror forget data
 315 gmirror insert data da1
 316 .Ed
 317 .Pp
 318 Create a mirror, deactivate one component, do the backup and connect it again.
 319 It will not be resynchronized, if there is no need to do so (there were no writes in
 320 the meantime):
 321 .Bd -literal -offset indent
 322 gmirror label data da0 da1
 323 gmirror deactivate data da1
 324 dd if=/dev/da1 of=/backup/data.img bs=1m
 325 gmirror activate data da1
 326 .Ed
 327 .Sh NOTES
 328 Doing kernel dumps to
 329 .Nm
 330 providers.
 331 .Pp
 332 This is possible, but some conditions have to be met.
 333 First of all, a kernel dump will go only to one component and
 334 .Nm
 335 always chooses the component with the highest priority.
 336 Reading a dump from the mirror on boot will only work if the
 337 .Cm prefer
 338 balance algorithm is used (that way
 339 .Nm
 340 will read only from the component with the highest priority).
 341 If you use a different balance algorithm, you should add:
 342 .Bd -literal -offset indent
 343 gmirror configure -b prefer data
 344 .Ed
 345 .Pp
 346 to the
 347 .Pa /etc/rc.early
 348 script and:
 349 .Bd -literal -offset indent
 350 gmirror configure -b round-robin data
 351 .Ed
 352 .Pp
 353 to the
 354 .Pa /etc/rc.local
 355 script.
 356 The decision which component to choose for dumping is made when
 357 .Xr dumpon 8
 358 is called.
 359 If on the next boot a component with a higher priority will be available,
 360 the prefer algorithm will choose to read from it and
 361 .Xr savecore 8
 362 will find nothing.
 363 If on the next boot a component with the highest priority will be synchronized,
 364 the prefer balance algorithm will read from the next one, thus will find nothing
 365 there.
 366 .Sh SEE ALSO
 367 .Xr geom 4 ,
 368 .Xr dumpon 8 ,
 369 .Xr geom 8 ,
 370 .Xr gvinum 8 ,
 371 .Xr mount 8 ,
 372 .Xr newfs 8 ,
 373 .Xr savecore 8 ,
 374 .Xr umount 8
 375 .Sh HISTORY
 376 The
 377 .Nm
 378 utility appeared in
 379 .Fx 5.3 .
 380 .Sh AUTHORS
 381 .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org
 382 .Sh BUGS
 383 There should be a way to change a component's priority inside a running mirror.
 384 .Pp
 385 There should be a section with an implementation description.
 386 .Pp
 387 Documentation for sysctls
 388 .Va kern.geom.mirror.*
 389 is missing.