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