sbin/geom/class/raid3/graid3.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 January 15, 2012
  28 .Dt GRAID3 8
  29 .Os
  30 .Sh NAME
  31 .Nm graid3
  32 .Nd "control utility for RAID3 devices"
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Cm label
  36 .Op Fl Fhnrvw
  37 .Op Fl s Ar blocksize
  38 .Ar name
  39 .Ar prov prov prov ...
  40 .Nm
  41 .Cm clear
  42 .Op Fl v
  43 .Ar prov ...
  44 .Nm
  45 .Cm configure
  46 .Op Fl adfFhnrRvwW
  47 .Ar name
  48 .Nm
  49 .Cm rebuild
  50 .Op Fl v
  51 .Ar name
  52 .Ar prov
  53 .Nm
  54 .Cm insert
  55 .Op Fl hv
  56 .Op Fl n Ar number
  57 .Ar name
  58 .Ar prov
  59 .Nm
  60 .Cm remove
  61 .Op Fl v
  62 .Fl n Ar number
  63 .Ar name
  64 .Nm
  65 .Cm stop
  66 .Op Fl fv
  67 .Ar name ...
  68 .Nm
  69 .Cm list
  70 .Nm
  71 .Cm status
  72 .Nm
  73 .Cm load
  74 .Nm
  75 .Cm unload
  76 .Sh DESCRIPTION
  77 The
  78 .Nm
  79 utility is used for RAID3 array configuration.
  80 After a device is created, all components are detected and configured
  81 automatically.
  82 All operations such as failure detection, stale component detection, rebuild
  83 of stale components, etc.\& are also done automatically.
  84 The
  85 .Nm
  86 utility uses on-disk metadata (the provider's last sector) to store all needed
  87 information.
  88 .Pp
  89 The first argument to
  90 .Nm
  91 indicates an action to be performed:
  92 .Bl -tag -width ".Cm configure"
  93 .It Cm label
  94 Create a RAID3 device.
  95 The last given component will contain parity data, whilst the others
  96 will all contain regular data.
  97 The number of components must be equal to 3, 5, 9, 17, etc.\& (2^n + 1).
  98 .Pp
  99 Additional options include:
 100 .Bl -tag -width ".Fl h"
 101 .It Fl F
 102 Do not synchronize after a power failure or system crash.
 103 Assumes device is in consistent state.
 104 .It Fl h
 105 Hardcode providers' names in metadata.
 106 .It Fl n
 107 Turn off autosynchronization of stale components.
 108 .It Fl r
 109 Use parity component for reading in round-robin fashion.
 110 Without this option the parity component is not used at all for reading operations
 111 when the device is in a complete state.
 112 With this option specified random I/O read operations are even 40% faster,
 113 but sequential reads are slower.
 114 One cannot use this option if the
 115 .Fl w
 116 option is also specified.
 117 .It Fl s
 118 Manually specify array block size. Block size will be set equal to least
 119 common multiple of all component's sector sizes and specified value.
 120 Note that array sector size calculated as multiple of block size and number
 121 of regular data components. Big values may decrease performance and compatibility,
 122 as all I/O requests have to be multiple of sector size.
 123 .It Fl w
 124 Use verify reading feature.
 125 When reading from a device in a complete state, also read data from the parity component
 126 and verify the data by comparing XORed regular data with parity data.
 127 If verification fails, an
 128 .Er EIO
 129 error is returned and the value of the
 130 .Va kern.geom.raid3.stat.parity_mismatch
 131 sysctl is increased.
 132 One cannot use this option if the
 133 .Fl r
 134 option is also specified.
 135 .El
 136 .It Cm clear
 137 Clear metadata on the given providers.
 138 .It Cm configure
 139 Configure the given device.
 140 .Pp
 141 Additional options include:
 142 .Bl -tag -width ".Fl a"
 143 .It Fl a
 144 Turn on autosynchronization of stale components.
 145 .It Fl d
 146 Do not hardcode providers' names in metadata.
 147 .It Fl f
 148 Synchronize device after a power failure or system crash.
 149 .It Fl F
 150 Do not synchronize after a power failure or system crash.
 151 Assumes device is in consistent state.
 152 .It Fl h
 153 Hardcode providers' names in metadata.
 154 .It Fl n
 155 Turn off autosynchronization of stale components.
 156 .It Fl r
 157 Turn on round-robin reading.
 158 .It Fl R
 159 Turn off round-robin reading.
 160 .It Fl w
 161 Turn on verify reading.
 162 .It Fl W
 163 Turn off verify reading.
 164 .El
 165 .It Cm rebuild
 166 Rebuild the given component forcibly.
 167 If autosynchronization was not turned off for the given device, this command
 168 should be unnecessary.
 169 .It Cm insert
 170 Add the given component to the existing array, if one of the components was
 171 removed previously with the
 172 .Cm remove
 173 command or if one component is missing and will not be connected again.
 174 If no number is given, new component will be added instead of first missed
 175 component.
 176 .Pp
 177 Additional options include:
 178 .Bl -tag -width ".Fl h"
 179 .It Fl h
 180 Hardcode providers' names in metadata.
 181 .El
 182 .It Cm remove
 183 Remove the given component from the given array and clear metadata on it.
 184 .It Cm stop
 185 Stop the given arrays.
 186 .Pp
 187 Additional options include:
 188 .Bl -tag -width ".Fl f"
 189 .It Fl f
 190 Stop the given array even if it is opened.
 191 .El
 192 .It Cm list
 193 See
 194 .Xr geom 8 .
 195 .It Cm status
 196 See
 197 .Xr geom 8 .
 198 .It Cm load
 199 See
 200 .Xr geom 8 .
 201 .It Cm unload
 202 See
 203 .Xr geom 8 .
 204 .El
 205 .Pp
 206 Additional options include:
 207 .Bl -tag -width ".Fl v"
 208 .It Fl v
 209 Be more verbose.
 210 .El
 211 .Sh EXIT STATUS
 212 Exit status is 0 on success, and 1 if the command fails.
 213 .Sh EXAMPLES
 214 Use 3 disks to setup a RAID3 array (with the round-robin reading feature).
 215 Create a file system, mount it, then unmount it and stop device:
 216 .Bd -literal -offset indent
 217 graid3 label -v -r data da0 da1 da2
 218 newfs /dev/raid3/data
 219 mount /dev/raid3/data /mnt
 220 \&...
 221 umount /mnt
 222 graid3 stop data
 223 graid3 unload
 224 .Ed
 225 .Pp
 226 Create a RAID3 array, but do not use the automatic synchronization feature.
 227 Rebuild parity component:
 228 .Bd -literal -offset indent
 229 graid3 label -n data da0 da1 da2
 230 graid3 rebuild data da2
 231 .Ed
 232 .Pp
 233 Replace one data disk with a brand new one:
 234 .Bd -literal -offset indent
 235 graid3 remove -n 0 data
 236 graid3 insert -n 0 data da5
 237 .Ed
 238 .Sh SEE ALSO
 239 .Xr geom 4 ,
 240 .Xr geom 8 ,
 241 .Xr gvinum 8 ,
 242 .Xr mount 8 ,
 243 .Xr newfs 8 ,
 244 .Xr umount 8
 245 .Sh HISTORY
 246 The
 247 .Nm
 248 utility appeared in
 249 .Fx 5.3 .
 250 .Sh AUTHORS
 251 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
 252 .Sh BUGS
 253 There should be a section with an implementation description.
 254 .Pp
 255 Documentation for sysctls
 256 .Va kern.geom.raid3.*
 257 is missing.