lib/geom/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 November 30, 2017
  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 create
  47 .Op Fl Fnv
  48 .Op Fl b Ar balance
  49 .Op Fl s Ar slice
  50 .Ar name
  51 .Ar prov ...
  52 .Nm
  53 .Cm configure
  54 .Op Fl adfFhnv
  55 .Op Fl b Ar balance
  56 .Op Fl s Ar slice
  57 .Ar name
  58 .Nm
  59 .Cm configure
  60 .Op Fl v
  61 .Fl p Ar priority
  62 .Ar name
  63 .Ar prov
  64 .Nm
  65 .Cm rebuild
  66 .Op Fl v
  67 .Ar name
  68 .Ar prov ...
  69 .Nm
  70 .Cm resize
  71 .Op Fl v
  72 .Op Fl s Ar size
  73 .Ar name
  74 .Nm
  75 .Cm insert
  76 .Op Fl hiv
  77 .Op Fl p Ar priority
  78 .Ar name
  79 .Ar prov ...
  80 .Nm
  81 .Cm remove
  82 .Op Fl v
  83 .Ar name
  84 .Ar prov ...
  85 .Nm
  86 .Cm activate
  87 .Op Fl v
  88 .Ar name
  89 .Ar prov ...
  90 .Nm
  91 .Cm deactivate
  92 .Op Fl v
  93 .Ar name
  94 .Ar prov ...
  95 .Nm
  96 .Cm destroy
  97 .Op Fl fv
  98 .Ar name ...
  99 .Nm
 100 .Cm forget
 101 .Op Fl v
 102 .Ar name ...
 103 .Nm
 104 .Cm stop
 105 .Op Fl fv
 106 .Ar name ...
 107 .Nm
 108 .Cm dump
 109 .Ar prov ...
 110 .Nm
 111 .Cm list
 112 .Nm
 113 .Cm status
 114 .Nm
 115 .Cm load
 116 .Nm
 117 .Cm unload
 118 .Sh DESCRIPTION
 119 The
 120 .Nm
 121 utility is used for mirror (RAID1) configurations.
 122 After a mirror's creation, all components are detected and configured
 123 automatically.
 124 All operations like failure detection, stale component detection, rebuild
 125 of stale components, etc.\& are also done automatically.
 126 The
 127 .Nm
 128 utility uses on-disk metadata (stored in the provider's last sector) to store all needed
 129 information.
 130 Since the last sector is used for this purpose, it is possible to place a root
 131 file system on a mirror.
 132 .Pp
 133 The first argument to
 134 .Nm
 135 indicates an action to be performed:
 136 .Bl -tag -width ".Cm deactivate"
 137 .It Cm label
 138 Create a mirror.
 139 The order of components is important, because a component's priority is based on its position
 140 (starting from 0 to 255).
 141 The component with the biggest priority is used by the
 142 .Cm prefer
 143 balance algorithm
 144 and is also used as a master component when resynchronization is needed,
 145 e.g.\& after a power failure when the device was open for writing.
 146 .Pp
 147 Additional options include:
 148 .Bl -tag -width ".Fl b Ar balance"
 149 .It Fl b Ar balance
 150 Specifies balance algorithm to use, one of:
 151 .Bl -tag -width ".Cm round-robin"
 152 .It Cm load
 153 Read from the component with the lowest load.
 154 This is the default balance algorithm.
 155 .It Cm prefer
 156 Read from the component with the biggest priority.
 157 .It Cm round-robin
 158 Use round-robin algorithm when choosing component to read.
 159 .It Cm split
 160 Split read requests, which are bigger than or equal to slice size on N pieces,
 161 where N is the number of active components.
 162 .El
 163 .It Fl F
 164 Do not synchronize after a power failure or system crash.
 165 Assumes device is in consistent state.
 166 .It Fl h
 167 Hardcode providers' names in metadata.
 168 .It Fl n
 169 Turn off autosynchronization of stale components.
 170 .It Fl s Ar slice
 171 When using the
 172 .Cm split
 173 balance algorithm and an I/O READ request is bigger than or equal to this value,
 174 the I/O request will be split into N pieces, where N is the number of active
 175 components.
 176 Defaults to 4096 bytes.
 177 .El
 178 .It Cm clear
 179 Clear metadata on the given providers.
 180 .It Cm create
 181 Similar to
 182 .Cm label ,
 183 but creates mirror without storing on-disk metadata in last sector.
 184 This special "manual" operation mode assumes some external control to manage
 185 mirror detection after reboot, device hot-plug and other external events.
 186 .It Cm configure
 187 Configure the given device.
 188 .Pp
 189 Additional options include:
 190 .Bl -tag -width ".Fl p Ar priority"
 191 .It Fl a
 192 Turn on autosynchronization of stale components.
 193 .It Fl b Ar balance
 194 Specifies balance algorithm to use.
 195 .It Fl d
 196 Do not hardcode providers' names in metadata.
 197 .It Fl f
 198 Synchronize device after a power failure or system crash.
 199 .It Fl F
 200 Do not synchronize after a power failure or system crash.
 201 Assumes device is in consistent state.
 202 .It Fl h
 203 Hardcode providers' names in metadata.
 204 .It Fl n
 205 Turn off autosynchronization of stale components.
 206 .It Fl p Ar priority
 207 Specifies priority for the given component
 208 .Ar prov .
 209 .It Fl s Ar slice
 210 Specifies slice size for
 211 .Cm split
 212 balance algorithm.
 213 .El
 214 .It Cm rebuild
 215 Rebuild the given mirror components forcibly.
 216 If autosynchronization was not turned off for the given device, this command
 217 should be unnecessary.
 218 .It Cm resize
 219 Change the size of the given mirror.
 220 .Pp
 221 Additional options include:
 222 .Bl -tag -width ".Fl s Ar size"
 223 .It Fl s Ar size
 224 New size of the mirror is expressed in logical block numbers.
 225 This option can be omitted, then it will be automatically calculated to
 226 maximum available size.
 227 .El
 228 .It Cm insert
 229 Add the given component(s) to the existing mirror.
 230 .Pp
 231 Additional options include:
 232 .Bl -tag -width ".Fl p Ar priority"
 233 .It Fl h
 234 Hardcode providers' names in metadata.
 235 .It Fl i
 236 Mark component(s) as inactive immediately after insertion.
 237 .It Fl p Ar priority
 238 Specifies priority of the given component(s).
 239 .El
 240 .It Cm remove
 241 Remove the given component(s) from the mirror and clear metadata on it.
 242 .It Cm activate
 243 Activate the given component(s), which were marked as inactive before.
 244 .It Cm deactivate
 245 Mark the given component(s) as inactive, so it will not be automatically
 246 connected to the mirror.
 247 .It Cm destroy
 248 Stop the given mirror and clear metadata on all its components.
 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 forget
 256 Forget about components which are not connected.
 257 This command is useful when a disk has failed and cannot be reconnected, preventing the
 258 .Cm remove
 259 command from being used to remove it.
 260 .It Cm stop
 261 Stop the given mirror.
 262 .Pp
 263 Additional options include:
 264 .Bl -tag -width ".Fl f"
 265 .It Fl f
 266 Stop the given mirror even if it is opened.
 267 .El
 268 .It Cm dump
 269 Dump metadata stored on the given providers.
 270 .It Cm list
 271 See
 272 .Xr geom 8 .
 273 .It Cm status
 274 See
 275 .Xr geom 8 .
 276 .It Cm load
 277 See
 278 .Xr geom 8 .
 279 .It Cm unload
 280 See
 281 .Xr geom 8 .
 282 .El
 283 .Pp
 284 Additional options include:
 285 .Bl -tag -width ".Fl v"
 286 .It Fl v
 287 Be more verbose.
 288 .El
 289 .Sh EXIT STATUS
 290 Exit status is 0 on success, and 1 if the command fails.
 291 .Sh EXAMPLES
 292 Use 3 disks to setup a mirror.
 293 Choose split balance algorithm, split only
 294 requests which are bigger than or equal to 2kB.
 295 Create file system,
 296 mount it, then unmount it and stop device:
 297 .Bd -literal -offset indent
 298 gmirror label -v -b split -s 2048 data da0 da1 da2
 299 newfs /dev/mirror/data
 300 mount /dev/mirror/data /mnt
 301 \&...
 302 umount /mnt
 303 gmirror stop data
 304 gmirror unload
 305 .Ed
 306 .Pp
 307 Create a mirror on disk with valid data (note that the last sector of the disk
 308 will be overwritten).
 309 Add another disk to this mirror,
 310 so it will be synchronized with existing disk:
 311 .Bd -literal -offset indent
 312 gmirror label -v -b round-robin data da0
 313 gmirror insert data da1
 314 .Ed
 315 .Pp
 316 Create a mirror, but do not use automatic synchronization feature.
 317 Add another disk and rebuild it:
 318 .Bd -literal -offset indent
 319 gmirror label -v -n -b load data da0 da1
 320 gmirror insert data da2
 321 gmirror rebuild data da2
 322 .Ed
 323 .Pp
 324 One disk failed.
 325 Replace it with a brand new one:
 326 .Bd -literal -offset indent
 327 gmirror forget data
 328 gmirror insert data da1
 329 .Ed
 330 .Pp
 331 Create a mirror, deactivate one component, do the backup and connect it again.
 332 It will not be resynchronized, if there is no need to do so (there were no writes in
 333 the meantime):
 334 .Bd -literal -offset indent
 335 gmirror label data da0 da1
 336 gmirror deactivate data da1
 337 dd if=/dev/da1 of=/backup/data.img bs=1m
 338 gmirror activate data da1
 339 .Ed
 340 .Sh SYSCTL VARIABLES
 341 The following
 342 .Xr sysctl 8
 343 variables can be used to configure behavior for all mirrors.
 344 .Bl -tag -width indent
 345 .It Va kern.geom.mirror.debug
 346 Control the verbosity of kernel logging related to mirrors.
 347 A value larger than 0 will enable debug logging.
 348 .It Va kern.geom.mirror.timeout
 349 The amount of time, in seconds, to wait for all copies of a mirror to
 350 appear before starting the mirror.
 351 Disks that appear after the mirror has been started are not automatically
 352 added to the mirror.
 353 .It Va kern.geom.mirror.idletime
 354 The amount of time, in seconds, which must elapse after the last write to
 355 a mirror before that mirror is marked clean.
 356 Clean mirrors do not need to be synchronized after a power failure or
 357 system crash.
 358 A small value may result in frequent overwrites of the disks' metadata
 359 sectors, and thus may reduce the longevity of the disks.
 360 .It Va kern.geom.mirror.disconnect_on_failure
 361 Determine whether a disk is automatically removed from its mirror when an
 362 I/O request to that disk fails.
 363 .It Va kern.geom.mirror.sync_requests
 364 The number of parallel I/O requests used while synchronizing a mirror.
 365 This parameter may only be configured as a
 366 .Xr loader.conf 5
 367 tunable.
 368 .It Va kern.geom.mirror.sync_update_period
 369 The period, in seconds, at which a synchronizing mirror's metadata is
 370 updated.
 371 Periodic updates are used to record a synchronization's progress so that
 372 an interrupted synchronization may be resumed starting at the recorded
 373 offset, rather than at the beginning.
 374 A smaller value results in more accurate progress tracking, but also
 375 increases the number of non-sequential writes to the disk being synchronized.
 376 If the sysctl value is 0, no updates are performed until the synchronization
 377 is complete.
 378 .El
 379 .Sh NOTES
 380 Doing kernel dumps to
 381 .Nm
 382 providers is possible, but some conditions have to be met.
 383 First of all, a kernel dump will go only to one component and
 384 .Nm
 385 always chooses the component with the highest priority.
 386 Reading a dump from the mirror on boot will only work if the
 387 .Cm prefer
 388 balance algorithm is used (that way
 389 .Nm
 390 will read only from the component with the highest priority).
 391 If you use a different balance algorithm, you should add:
 392 .Bd -literal -offset indent
 393 gmirror configure -b prefer data
 394 .Ed
 395 .Pp
 396 to the
 397 .Pa /etc/rc.early
 398 script and:
 399 .Bd -literal -offset indent
 400 gmirror configure -b round-robin data
 401 .Ed
 402 .Pp
 403 to the
 404 .Pa /etc/rc.local
 405 script.
 406 The decision which component to choose for dumping is made when
 407 .Xr dumpon 8
 408 is called.
 409 If on the next boot a component with a higher priority will be available,
 410 the prefer algorithm will choose to read from it and
 411 .Xr savecore 8
 412 will find nothing.
 413 If on the next boot a component with the highest priority will be synchronized,
 414 the prefer balance algorithm will read from the next one, thus will find nothing
 415 there.
 416 .Sh SEE ALSO
 417 .Xr geom 4 ,
 418 .Xr dumpon 8 ,
 419 .Xr geom 8 ,
 420 .Xr gvinum 8 ,
 421 .Xr mount 8 ,
 422 .Xr newfs 8 ,
 423 .Xr savecore 8 ,
 424 .Xr sysctl 8 ,
 425 .Xr umount 8
 426 .Sh HISTORY
 427 The
 428 .Nm
 429 utility appeared in
 430 .Fx 5.3 .
 431 .Sh AUTHORS
 432 .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org
 433 .Sh BUGS
 434 There should be a way to change a component's priority inside a running mirror.
 435 .Pp
 436 There should be a section with an implementation description.