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