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