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 insert
  64 .Op Fl hiv
  65 .Op Fl p Ar priority
  66 .Ar name
  67 .Ar prov ...
  68 .Nm
  69 .Cm remove
  70 .Op Fl v
  71 .Ar name
  72 .Ar prov ...
  73 .Nm
  74 .Cm activate
  75 .Op Fl v
  76 .Ar name
  77 .Ar prov ...
  78 .Nm
  79 .Cm deactivate
  80 .Op Fl v
  81 .Ar name
  82 .Ar prov ...
  83 .Nm
  84 .Cm destroy
  85 .Op Fl fv
  86 .Ar name ...
  87 .Nm
  88 .Cm forget
  89 .Op Fl v
  90 .Ar name ...
  91 .Nm
  92 .Cm stop
  93 .Op Fl fv
  94 .Ar name ...
  95 .Nm
  96 .Cm dump
  97 .Ar prov ...
  98 .Nm
  99 .Cm list
 100 .Nm
 101 .Cm status
 102 .Nm
 103 .Cm load
 104 .Nm
 105 .Cm unload
 106 .Sh DESCRIPTION
 107 The
 108 .Nm
 109 utility is used for mirror (RAID1) configurations.
 110 After a mirror's creation, all components are detected and configured
 111 automatically.
 112 All operations like failure detection, stale component detection, rebuild
 113 of stale components, etc.\& are also done automatically.
 114 The
 115 .Nm
 116 utility uses on-disk metadata (stored in the provider's last sector) to store all needed
 117 information.
 118 Since the last sector is used for this purpose, it is possible to place a root
 119 file system on a mirror.
 120 .Pp
 121 The first argument to
 122 .Nm
 123 indicates an action to be performed:
 124 .Bl -tag -width ".Cm deactivate"
 125 .It Cm label
 126 Create a mirror.
 127 The order of components is important, because a component's priority is based on its position
 128 (starting from 0 to 255).
 129 The component with the biggest priority is used by the
 130 .Cm prefer
 131 balance algorithm
 132 and is also used as a master component when resynchronization is needed,
 133 e.g.\& after a power failure when the device was open for writing.
 134 .Pp
 135 Additional options include:
 136 .Bl -tag -width ".Fl b Ar balance"
 137 .It Fl b Ar balance
 138 Specifies balance algorithm to use, one of:
 139 .Bl -tag -width ".Cm round-robin"
 140 .It Cm load
 141 Read from the component with the lowest load.
 142 This is the default balance algorithm.
 143 .It Cm prefer
 144 Read from the component with the biggest priority.
 145 .It Cm round-robin
 146 Use round-robin algorithm when choosing component to read.
 147 .It Cm split
 148 Split read requests, which are bigger than or equal to slice size on N pieces,
 149 where N is the number of active components.
 150 .El
 151 .It Fl F
 152 Do not synchronize after a power failure or system crash.
 153 Assumes device is in consistent state.
 154 .It Fl h
 155 Hardcode providers' names in metadata.
 156 .It Fl n
 157 Turn off autosynchronization of stale components.
 158 .It Fl s Ar slice
 159 When using the
 160 .Cm split
 161 balance algorithm and an I/O READ request is bigger than or equal to this value,
 162 the I/O request will be split into N pieces, where N is the number of active
 163 components.
 164 Defaults to 4096 bytes.
 165 .El
 166 .It Cm clear
 167 Clear metadata on the given providers.
 168 .It Cm configure
 169 Configure the given device.
 170 .Pp
 171 Additional options include:
 172 .Bl -tag -width ".Fl p Ar priority"
 173 .It Fl a
 174 Turn on autosynchronization of stale components.
 175 .It Fl b Ar balance
 176 Specifies balance algorithm to use.
 177 .It Fl d
 178 Do not hardcode providers' names in metadata.
 179 .It Fl f
 180 Synchronize device after a power failure or system crash.
 181 .It Fl F
 182 Do not synchronize after a power failure or system crash.
 183 Assumes device is in consistent state.
 184 .It Fl h
 185 Hardcode providers' names in metadata.
 186 .It Fl n
 187 Turn off autosynchronization of stale components.
 188 .It Fl p Ar priority
 189 Specifies priority for the given component
 190 .Ar prov .
 191 .It Fl s Ar slice
 192 Specifies slice size for
 193 .Cm split
 194 balance algorithm.
 195 .El
 196 .It Cm rebuild
 197 Rebuild the given mirror components forcibly.
 198 If autosynchronization was not turned off for the given device, this command
 199 should be unnecessary.
 200 .It Cm insert
 201 Add the given component(s) to the existing mirror.
 202 .Pp
 203 Additional options include:
 204 .Bl -tag -width ".Fl p Ar priority"
 205 .It Fl h
 206 Hardcode providers' names in metadata.
 207 .It Fl i
 208 Mark component(s) as inactive immediately after insertion.
 209 .It Fl p Ar priority
 210 Specifies priority of the given component(s).
 211 .El
 212 .It Cm remove
 213 Remove the given component(s) from the mirror and clear metadata on it.
 214 .It Cm activate
 215 Activate the given component(s), which were marked as inactive before.
 216 .It Cm deactivate
 217 Mark the given component(s) as inactive, so it will not be automatically
 218 connected to the mirror.
 219 .It Cm destroy
 220 Stop the given mirror and clear metadata on all its components.
 221 .Pp
 222 Additional options include:
 223 .Bl -tag -width ".Fl f"
 224 .It Fl f
 225 Stop the given mirror even if it is opened.
 226 .El
 227 .It Cm forget
 228 Forget about components which are not connected.
 229 This command is useful when a disk has failed and cannot be reconnected, preventing the
 230 .Cm remove
 231 command from being used to remove it.
 232 .It Cm stop
 233 Stop the given mirror.
 234 .Pp
 235 Additional options include:
 236 .Bl -tag -width ".Fl f"
 237 .It Fl f
 238 Stop the given mirror even if it is opened.
 239 .El
 240 .It Cm dump
 241 Dump metadata stored on the given providers.
 242 .It Cm list
 243 See
 244 .Xr geom 8 .
 245 .It Cm status
 246 See
 247 .Xr geom 8 .
 248 .It Cm load
 249 See
 250 .Xr geom 8 .
 251 .It Cm unload
 252 See
 253 .Xr geom 8 .
 254 .El
 255 .Pp
 256 Additional options include:
 257 .Bl -tag -width ".Fl v"
 258 .It Fl v
 259 Be more verbose.
 260 .El
 261 .Sh EXIT STATUS
 262 Exit status is 0 on success, and 1 if the command fails.
 263 .Sh EXAMPLES
 264 Use 3 disks to setup a mirror.
 265 Choose split balance algorithm, split only
 266 requests which are bigger than or equal to 2kB.
 267 Create file system,
 268 mount it, then unmount it and stop device:
 269 .Bd -literal -offset indent
 270 gmirror label -v -b split -s 2048 data da0 da1 da2
 271 newfs /dev/mirror/data
 272 mount /dev/mirror/data /mnt
 273 \&...
 274 umount /mnt
 275 gmirror stop data
 276 gmirror unload
 277 .Ed
 278 .Pp
 279 Create a mirror on disk with valid data (note that the last sector of the disk
 280 will be overwritten).
 281 Add another disk to this mirror,
 282 so it will be synchronized with existing disk:
 283 .Bd -literal -offset indent
 284 gmirror label -v -b round-robin data da0
 285 gmirror insert data da1
 286 .Ed
 287 .Pp
 288 Create a mirror, but do not use automatic synchronization feature.
 289 Add another disk and rebuild it:
 290 .Bd -literal -offset indent
 291 gmirror label -v -n -b load data da0 da1
 292 gmirror insert data da2
 293 gmirror rebuild data da2
 294 .Ed
 295 .Pp
 296 One disk failed.
 297 Replace it with a brand new one:
 298 .Bd -literal -offset indent
 299 gmirror forget data
 300 gmirror insert data da1
 301 .Ed
 302 .Pp
 303 Create a mirror, deactivate one component, do the backup and connect it again.
 304 It will not be resynchronized, if there is no need to do so (there were no writes in
 305 the meantime):
 306 .Bd -literal -offset indent
 307 gmirror label data da0 da1
 308 gmirror deactivate data da1
 309 dd if=/dev/da1 of=/backup/data.img bs=1m
 310 gmirror activate data da1
 311 .Ed
 312 .Sh NOTES
 313 Doing kernel dumps to
 314 .Nm
 315 providers.
 316 .Pp
 317 This is possible, but some conditions have to be met.
 318 First of all, a kernel dump will go only to one component and
 319 .Nm
 320 always chooses the component with the highest priority.
 321 Reading a dump from the mirror on boot will only work if the
 322 .Cm prefer
 323 balance algorithm is used (that way
 324 .Nm
 325 will read only from the component with the highest priority).
 326 If you use a different balance algorithm, you should add:
 327 .Bd -literal -offset indent
 328 gmirror configure -b prefer data
 329 .Ed
 330 .Pp
 331 to the
 332 .Pa /etc/rc.early
 333 script and:
 334 .Bd -literal -offset indent
 335 gmirror configure -b round-robin data
 336 .Ed
 337 .Pp
 338 to the
 339 .Pa /etc/rc.local
 340 script.
 341 The decision which component to choose for dumping is made when
 342 .Xr dumpon 8
 343 is called.
 344 If on the next boot a component with a higher priority will be available,
 345 the prefer algorithm will choose to read from it and
 346 .Xr savecore 8
 347 will find nothing.
 348 If on the next boot a component with the highest priority will be synchronized,
 349 the prefer balance algorithm will read from the next one, thus will find nothing
 350 there.
 351 .Sh SEE ALSO
 352 .Xr geom 4 ,
 353 .Xr dumpon 8 ,
 354 .Xr geom 8 ,
 355 .Xr mount 8 ,
 356 .Xr newfs 8 ,
 357 .Xr savecore 8 ,
 358 .Xr umount 8 ,
 359 .Xr vinum 8
 360 .Sh HISTORY
 361 The
 362 .Nm
 363 utility appeared in
 364 .Fx 5.3 .
 365 .Sh AUTHORS
 366 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
 367 .Sh BUGS
 368 There should be a way to change a component's priority inside a running mirror.
 369 .Pp
 370 There should be a section with an implementation description.
 371 .Pp
 372 Documentation for sysctls
 373 .Va kern.geom.mirror.*
 374 is missing.