sbin/geom/class/mirror/gmirror.8

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