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