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