1 .\" $OpenBSD: softraid.4,v 1.56 2025年04月13日 13:17:31 jmc Exp $ 2 .\" 3 .\" Copyright (c) 2007 Todd T. Fries <todd@OpenBSD.org> 4 .\" Copyright (c) 2007 Marco Peereboom <marco@OpenBSD.org> 5 .\" 6 .\" Permission to use, copy, modify, and distribute this software for any 7 .\" purpose with or without fee is hereby granted, provided that the above 8 .\" copyright notice and this permission notice appear in all copies. 9 .\" 10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17 .\" 18 .Dd $Mdocdate: April 13 2025 $ 19 .Dt SOFTRAID 4 20 .Os 21 .Sh NAME 22 .Nm softraid 23 .Nd software RAID 24 .Sh SYNOPSIS 25 .Cd "softraid0 at root" 26 .Sh DESCRIPTION 27The 28 .Nm 29device emulates a Host Bus Adapter (HBA) that provides RAID and other I/O 30related services. 31The 32 .Nm 33device provides a scaffold to implement more complex I/O transformation 34disciplines. 35For example, one can tie chunks together into a mirroring discipline. 36There really is no limit on what type of discipline one can write as long 37as it fits the SCSI model. 38 .Pp 39 .Nm 40supports a number of 41 .Em disciplines . 42A discipline is a collection of functions 43that provides specific I/O functionality. 44This includes I/O path, bring-up, failure recovery, and statistical 45information gathering. 46Essentially a discipline is a lower 47level driver that provides the I/O transformation for the softraid 48device. 49 .Pp 50A 51 .Em volume 52is a virtual disk device that is made up of a collection of chunks. 53 .Pp 54A 55 .Em chunk 56is a partition or storage area of fstype 57 .Dq RAID . 58 .Xr disklabel 8 59is used to alter the fstype. 60 .Pp 61Currently 62 .Nm 63supports the following disciplines: 64 .Bl -ohang -offset indent 65 .It RAID 0 66A 67 .Em striping 68discipline. 69It segments data over a number of chunks to increase performance. 70RAID 0 does not provide for data loss (redundancy). 71 .It RAID 1 72A 73 .Em mirroring 74discipline. 75It copies data across more than one chunk to provide for data loss. 76Read performance is increased, 77though at the cost of write speed. 78Unlike traditional RAID 1, 79 .Nm 80supports the use of more than two chunks in a RAID 1 setup. 81 .It RAID 5 82A 83 .Em striping 84discipline with 85 .Em floating parity 86across all chunks. 87It stripes data across chunks and provides parity to prevent data loss of 88a single chunk failure. 89Read performance is increased; 90write performance does incur additional overhead. 91 .It CRYPTO 92An 93 .Em encrypting 94discipline. 95It encrypts data on a single chunk to provide for data confidentiality. 96CRYPTO does not provide redundancy. 97 .It CONCAT 98A 99 .Em concatenating 100discipline. 101It writes data to each chunk in sequence to provide increased capacity. 102CONCAT does not provide redundancy. 103 .It RAID 1C 104A 105 .Em mirroring 106and 107 .Em encrypting 108discipline. 109It encrypts data to provide for data confidentiality and copies the 110encrypted data across more than one chunk to prevent data loss in 111case of a chunk failure. 112Unlike traditional RAID 1, 113 .Nm 114supports the use of more than two chunks in a RAID 1C setup. 115 .El 116 .Pp 117 .Xr installboot 8 118may be used to install 119 .Xr boot 8 120in the boot storage area of the 121 .Nm 122volume. 123All chunks in the volume will then be bootable. 124Boot support is currently limited to the CRYPTO, RAID 1, and RAID 1C disciplines 125on the amd64, arm64, riscv64 and sparc64 platforms. 126Boot support on i386 is limited to CRYPTO and RAID 1. 127On sparc64, bootable chunks must be RAID partitions using the letter 128 .Sq a . 129At the 130 .Xr boot 8 131prompt, softraid volumes have names beginning with 132 .Sq sr 133and can be booted from like a normal disk device. 134CRYPTO and 1C volumes will require a decryption passphrase or keydisk 135at boot time. 136 .Pp 137The status of 138 .Nm 139volumes is reported via 140 .Xr sysctl 8 141such that it can be monitored by 142 .Xr sensorsd 8 . 143Each volume has one fourth level node named 144 .Va hw.sensors.softraid0.drive Ns Ar N , 145where 146 .Ar N 147is a small integer indexing the volume. 148The format of the volume status is: 149 .Pp 150 .D1 Ar value Po Ar device Pc , Ar status 151 .Pp 152The 153 .Ar device 154identifies the 155 .Nm 156volume. 157The following combinations of 158 .Ar value 159and 160 .Ar status 161can occur: 162 .Bl -tag -width Ds -offset indent 163 .It Sy online , OK 164The volume is operating normally. 165 .It Sy degraded , WARNING 166The volume as a whole is operational, but not all of its chunks are. 167In many cases, using 168 .Xr bioctl 8 169 .Fl R 170to rebuild the failed chunk is advisable. 171 .It Sy rebuilding , WARNING 172A rebuild operation was recently started and has not yet completed. 173 .It Sy failed , CRITICAL 174The device is currently unable to process I/O. 175 .It Sy unknown , UNKNOWN 176The status is unknown to the system. 177 .El 178 .Sh EXAMPLES 179An example to create a 3 chunk RAID 1 from scratch is as follows: 180 .Pp 181Initialize the partition tables of all disks: 182 .Bd -literal -offset indent 183# fdisk -iy wd1 184# fdisk -iy wd2 185# fdisk -iy wd3 186 .Ed 187 .Pp 188Now create RAID partitions on all disks: 189 .Bd -literal -offset indent 190# echo 'RAID *' | disklabel -wAT- wd1 191# echo 'RAID *' | disklabel -wAT- wd2 192# echo 'RAID *' | disklabel -wAT- wd3 193 .Ed 194 .Pp 195Assemble the RAID volume: 196 .Bd -literal -offset indent 197# bioctl -c 1 -l /dev/wd1a,/dev/wd2a,/dev/wd3a softraid0 198 .Ed 199 .Pp 200The console will show what device was added to the system: 201 .Bd -literal -offset indent 202scsibus0 at softraid0: 1 targets 203sd0 at scsibus0 targ 0 lun 0: <OPENBSD, SR RAID 1, 001> SCSI2 204sd0: 1MB, 0 cyl, 255 head, 63 sec, 512 bytes/sec, 3714 sec total 205 .Ed 206 .Pp 207It is good practice to wipe the front of the disk before using it: 208 .Bd -literal -offset indent 209# dd if=/dev/zero of=/dev/rsd0c bs=1m count=1 210 .Ed 211 .Pp 212Initialize the partition table and create a filesystem on the 213new RAID volume: 214 .Bd -literal -offset indent 215# fdisk -iy sd0 216# echo '/ *' | disklabel -wAT- sd0 217# newfs /dev/rsd0a 218 .Ed 219 .Pp 220The RAID volume is now ready to be used as a normal disk device. 221See 222 .Xr bioctl 8 223for more information on configuration of RAID sets. 224 .Pp 225Install 226 .Xr boot 8 227on the RAID volume, writing boot loaders to all 3 chunks: 228 .Bd -literal -offset indent 229# installboot sd0 230 .Ed 231 .Pp 232At the 233 .Xr boot 8 234prompt, load the /bsd kernel from the RAID volume: 235 .Bd -literal -offset indent 236boot> boot sr0a:/bsd 237 .Ed 238 .Sh SEE ALSO 239 .Xr bio 4 , 240 .Xr bioctl 8 , 241 .Xr boot 8 , 242 .Xr boot_sparc64 8 , 243 .Xr disklabel 8 , 244 .Xr fdisk 8 , 245 .Xr installboot 8 , 246 .Xr newfs 8 247 .Sh HISTORY 248The 249 .Nm 250driver first appeared in 251 .Ox 4.2 . 252 .Sh AUTHORS 253 .An Marco Peereboom . 254 .Sh CAVEATS 255The driver relies on underlying hardware to properly fail chunks. 256 .Pp 257The RAID 1 discipline does not initialize the mirror upon creation. 258This is by design because all sectors that are read are written first. 259There is no point in wasting a lot of time syncing random data. 260 .Pp 261The RAID 5 discipline does not initialize parity upon creation, instead parity 262is only updated upon write. 263 .Pp 264Stacking disciplines (CRYPTO on top of RAID 5, for example) is not 265supported at this time. 266 .Pp 267Currently there is no automated mechanism to recover from failed disks. 268 .Pp 269Certain RAID levels can protect against some data loss 270due to component failure. 271RAID is 272 .Em not 273a substitute for good backup practices. 274