sbin/geom/class/raid/graid.8

   1 .\" Copyright (c) 2010 Alexander Motin <mav@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 September 13, 2012
  28 .Dt GRAID 8
  29 .Os
  30 .Sh NAME
  31 .Nm graid
  32 .Nd "control utility for software RAID devices"
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Cm label
  36 .Op Fl f
  37 .Op Fl o Ar fmtopt
  38 .Op Fl S Ar size
  39 .Op Fl s Ar strip
  40 .Ar format
  41 .Ar label
  42 .Ar level
  43 .Ar prov ...
  44 .Nm
  45 .Cm add
  46 .Op Fl f
  47 .Op Fl S Ar size
  48 .Op Fl s Ar strip
  49 .Ar name
  50 .Ar label
  51 .Ar level
  52 .Nm
  53 .Cm delete
  54 .Op Fl f
  55 .Ar name
  56 .Op Ar label | Ar num
  57 .Nm
  58 .Cm insert
  59 .Ar name
  60 .Ar prov ...
  61 .Nm
  62 .Cm remove
  63 .Ar name
  64 .Ar prov ...
  65 .Nm
  66 .Cm fail
  67 .Ar name
  68 .Ar prov ...
  69 .Nm
  70 .Cm stop
  71 .Op Fl fv
  72 .Ar name ...
  73 .Nm
  74 .Cm list
  75 .Nm
  76 .Cm status
  77 .Nm
  78 .Cm load
  79 .Nm
  80 .Cm unload
  81 .Sh DESCRIPTION
  82 The
  83 .Nm
  84 utility is used to manage software RAID configurations, supported by the
  85 GEOM RAID class.
  86 GEOM RAID class uses on-disk metadata to provide access to software-RAID
  87 volumes defined by different RAID BIOSes.
  88 Depending on RAID BIOS type and its metadata format, different subsets of
  89 configurations and features are supported.
  90 To allow booting from RAID volume, the metadata format should match the
  91 RAID BIOS type and its capabilities.
  92 To guarantee that these match, it is recommended to create volumes via the
  93 RAID BIOS interface, while experienced users are free to do it using this
  94 utility.
  95 .Pp
  96 The first argument to
  97 .Nm
  98 indicates an action to be performed:
  99 .Bl -tag -width ".Cm destroy"
 100 .It Cm label
 101 Create an array with single volume.
 102 The
 103 .Ar format
 104 argument specifies the on-disk metadata format to use for this array,
 105 such as "Intel".
 106 The
 107 .Ar label
 108 argument specifies the label of the created volume.
 109 The
 110 .Ar level
 111 argument specifies the RAID level of the created volume, such as:
 112 "RAID0", "RAID1", etc.
 113 The subsequent list enumerates providers to use as array components.
 114 The special name "NONE" can be used to reserve space for absent disks.
 115 The order of components can be important, depending on specific RAID level
 116 and metadata format.
 117 .Pp
 118 Additional options include:
 119 .Bl -tag -width ".Fl s Ar strip"
 120 .It Fl f
 121 Enforce specified configuration creation if it is officially unsupported,
 122 but technically can be created.
 123 .It Fl o Ar fmtopt
 124 Specifies metadata format options.
 125 .It Fl S Ar size
 126 Use
 127 .Ar size
 128 bytes on each component for this volume.
 129 Should be used if several volumes per array are planned, or if smaller
 130 components going to be inserted later.
 131 Defaults to size of the smallest component.
 132 .It Fl s Ar strip
 133 Specifies strip size in bytes.
 134 Defaults to 131072.
 135 .El
 136 .It Cm add
 137 Create another volume on the existing array.
 138 The
 139 .Ar name
 140 argument is the name of the existing array, reported by label command.
 141 The rest of arguments are the same as for the label command.
 142 .It Cm delete
 143 Delete volume(s) from the existing array.
 144 When the last volume is deleted, the array is also deleted and its metadata
 145 erased.
 146 The
 147 .Ar name
 148 argument is the name of existing array.
 149 Optional
 150 .Ar label
 151 or
 152 .Ar num
 153 arguments allow specifying volume for deletion.
 154 .Pp
 155 Additional options include:
 156 .Bl -tag -width ".Fl f"
 157 .It Fl f
 158 Delete volume(s) even if it is still open.
 159 .El
 160 .It Cm insert
 161 Insert specified provider(s) into specified array instead of the first missing
 162 or failed components.
 163 If there are no such components, mark disk(s) as spare.
 164 .It Cm remove
 165 Remove the specified provider(s) from the specified array and erase metadata.
 166 If there are spare disks present, the removed disk(s) will be replaced by
 167 spares.
 168 .It Cm fail
 169 Mark the given disks(s) as failed, removing from active use unless absolutely
 170 necessary due to exhausted redundancy.
 171 If there are spare disks present - failed disk(s) will be replaced with one
 172 of them.
 173 .It Cm stop
 174 Stop the given array.
 175 The metadata will not be erased.
 176 .Pp
 177 Additional options include:
 178 .Bl -tag -width ".Fl f"
 179 .It Fl f
 180 Stop the given array even if some of its volumes are opened.
 181 .El
 182 .It Cm list
 183 See
 184 .Xr geom 8 .
 185 .It Cm status
 186 See
 187 .Xr geom 8 .
 188 .It Cm load
 189 See
 190 .Xr geom 8 .
 191 .It Cm unload
 192 See
 193 .Xr geom 8 .
 194 .El
 195 .Pp
 196 Additional options include:
 197 .Bl -tag -width ".Fl v"
 198 .It Fl v
 199 Be more verbose.
 200 .El
 201 .Sh SUPPORTED METADATA FORMATS
 202 The GEOM RAID class follows a modular design, allowing different metadata
 203 formats to be used.
 204 Support is currently implemented for the following formats:
 205 .Bl -tag -width "Intel"
 206 .It DDF
 207 The format defined by the SNIA Common RAID Disk Data Format v2.0 specification.
 208 Used by some Adaptec RAID BIOSes and some hardware RAID controllers.
 209 Because of high format flexibility different implementations support
 210 different set of features and have different on-disk metadata layouts.
 211 To provide compatibility, the GEOM RAID class mimics capabilities
 212 of the first detected DDF array.
 213 Respecting that, it may support different number of disks per volume,
 214 volumes per array, partitions per disk, etc.
 215 The following configurations are supported: RAID0 (2+ disks), RAID1 (2+ disks),
 216 RAID1E (3+ disks), RAID3 (3+ disks), RAID4 (3+ disks), RAID5 (3+ disks),
 217 RAID5E (4+ disks), RAID5EE (4+ disks), RAID5R (3+ disks), RAID6 (4+ disks),
 218 RAIDMDF (4+ disks), RAID10 (4+ disks), SINGLE (1 disk), CONCAT (2+ disks).
 219 .Pp
 220 Format supports two options "BE" and "LE", that mean big-endian byte order
 221 defined by specification (default) and little-endian used by some Adaptec
 222 controllers.
 223 .It Intel
 224 The format used by Intel RAID BIOS.
 225 Supports up to two volumes per array.
 226 Supports configurations: RAID0 (2+ disks), RAID1 (2 disks),
 227 RAID5 (3+ disks), RAID10 (4 disks).
 228 Configurations not supported by Intel RAID BIOS, but enforceable on your own
 229 risk: RAID1 (3+ disks), RAID1E (3+ disks), RAID10 (6+ disks).
 230 .It JMicron
 231 The format used by JMicron RAID BIOS.
 232 Supports one volume per array.
 233 Supports configurations: RAID0 (2+ disks), RAID1 (2 disks),
 234 RAID10 (4 disks), CONCAT (2+ disks).
 235 Configurations not supported by JMicron RAID BIOS, but enforceable on your own
 236 risk: RAID1 (3+ disks), RAID1E (3+ disks), RAID10 (6+ disks), RAID5 (3+ disks).
 237 .It NVIDIA
 238 The format used by NVIDIA MediaShield RAID BIOS.
 239 Supports one volume per array.
 240 Supports configurations: RAID0 (2+ disks), RAID1 (2 disks),
 241 RAID5 (3+ disks), RAID10 (4+ disks), SINGLE (1 disk), CONCAT (2+ disks).
 242 Configurations not supported by NVIDIA MediaShield RAID BIOS, but enforceable
 243 on your own risk: RAID1 (3+ disks).
 244 .It Promise
 245 The format used by Promise and AMD/ATI RAID BIOSes and FreeBSD ataraid(4)
 246 driver.
 247 Supports multiple volumes per array.
 248 Each disk can be split to be used by up to two arbitrary volumes.
 249 Supports configurations: RAID0 (2+ disks), RAID1 (2 disks),
 250 RAID5 (3+ disks), RAID10 (4 disks), SINGLE (1 disk), CONCAT (2+ disks).
 251 Configurations not supported by RAID BIOSes, but enforceable on your
 252 own risk: RAID1 (3+ disks), RAID10 (6+ disks).
 253 .It SiI
 254 The format used by SiliconImage RAID BIOS.
 255 Supports one volume per array.
 256 Supports configurations: RAID0 (2+ disks), RAID1 (2 disks),
 257 RAID5 (3+ disks), RAID10 (4 disks), SINGLE (1 disk), CONCAT (2+ disks).
 258 Configurations not supported by SiliconImage RAID BIOS, but enforceable on your
 259 own risk: RAID1 (3+ disks), RAID10 (6+ disks).
 260 .El
 261 .Sh SUPPORTED RAID LEVELS
 262 The GEOM RAID class follows a modular design, allowing different RAID levels
 263 to be used.
 264 Full support for the following RAID levels is currently implemented:
 265 RAID0, RAID1, RAID1E, RAID10, SINGLE, CONCAT.
 266 The following RAID levels supported as read-only for volumes in optimal
 267 state (without using redundancy): RAID4, RAID5, RAID5E, RAID5EE, RAID5R,
 268 RAID6, RAIDMDF.
 269 .Sh RAID LEVEL MIGRATION
 270 The GEOM RAID class has no support for RAID level migration, allowed by some
 271 metadata formats.
 272 If you started migration using BIOS or in some other way, make sure to
 273 complete it there.
 274 Do not run GEOM RAID class on migrating volumes under pain of possible data
 275 corruption!
 276 .Sh 2TiB BARRIERS
 277 Promise metadata format does not support disks above 2TiB.
 278 NVIDIA metadata format does not support volumes above 2TiB.
 279 .Sh SYSCTL VARIABLES
 280 The following
 281 .Xr sysctl 8
 282 variable can be used to control the behavior of the
 283 .Nm RAID
 284 GEOM class.
 285 .Bl -tag -width indent
 286 .It Va kern.geom.raid.aggressive_spare : No 0
 287 Use any disks without metadata connected to controllers of the vendor
 288 matching to volume metadata format as spare.
 289 Use it with much care to not lose data if connecting unrelated disk!
 290 .It Va kern.geom.raid.clean_time : No 5
 291 Mark volume as clean when idle for the specified number of seconds.
 292 .It Va kern.geom.raid.debug : No 0
 293 Debug level of the
 294 .Nm RAID
 295 GEOM class.
 296 .It Va kern.geom.raid.enable : No 1
 297 Enable on-disk metadata taste.
 298 .It Va kern.geom.raid.idle_threshold : No 1000000
 299 Time in microseconds to consider a volume idle for rebuild purposes.
 300 .It Va kern.geom.raid.name_format : No 0
 301 Providers name format: 0 -- raid/r{num}, 1 -- raid/{label}.
 302 .It Va kern.geom.raid.read_err_thresh : No 10
 303 Number of read errors equated to disk failure.
 304 Write errors are always considered as disk failures.
 305 .It Va kern.geom.raid.start_timeout : No 30
 306 Time to wait for missing array components on startup.
 307 .It Va kern.geom.raid. Ns Ar X Ns Va .enable : No 1
 308 Enable taste for specific metadata or transformation module.
 309 .El
 310 .Sh EXIT STATUS
 311 Exit status is 0 on success, and non-zero if the command fails.
 312 .Sh SEE ALSO
 313 .Xr geom 4 ,
 314 .Xr geom 8 ,
 315 .Xr vinum 8
 316 .Sh HISTORY
 317 The
 318 .Nm
 319 utility appeared in
 320 .Fx 9.0 .
 321 .Sh AUTHORS
 322 .An Alexander Motin Aq mav@FreeBSD.org
 323 .An M. Warner Losh Aq imp@FreeBSD.org