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