.\" $OpenBSD: softraid.4,v 1.54 2023/04/13 10:23:21 kn Exp $ .\" .\" Copyright (c) 2007 Todd T. Fries .\" Copyright (c) 2007 Marco Peereboom .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate: April 13 2023 $ .Dt SOFTRAID 4 .Os .Sh NAME .Nm softraid .Nd software RAID .Sh SYNOPSIS .Cd "softraid0 at root" .Sh DESCRIPTION The .Nm device emulates a Host Bus Adapter (HBA) that provides RAID and other I/O related services. The .Nm device provides a scaffold to implement more complex I/O transformation disciplines. For example, one can tie chunks together into a mirroring discipline. There really is no limit on what type of discipline one can write as long as it fits the SCSI model. .Pp .Nm supports a number of .Em disciplines . A discipline is a collection of functions that provides specific I/O functionality. This includes I/O path, bring-up, failure recovery, and statistical information gathering. Essentially a discipline is a lower level driver that provides the I/O transformation for the softraid device. .Pp A .Em volume is a virtual disk device that is made up of a collection of chunks. .Pp A .Em chunk is a partition or storage area of fstype .Dq RAID . .Xr disklabel 8 is used to alter the fstype. .Pp Currently .Nm supports the following disciplines: .Bl -ohang -offset indent .It RAID 0 A .Em striping discipline. It segments data over a number of chunks to increase performance. RAID 0 does not provide for data loss (redundancy). .It RAID 1 A .Em mirroring discipline. It copies data across more than one chunk to provide for data loss. Read performance is increased, though at the cost of write speed. Unlike traditional RAID 1, .Nm supports the use of more than two chunks in a RAID 1 setup. .It RAID 5 A striping discipline with .Em floating parity across all chunks. It stripes data across chunks and provides parity to prevent data loss of a single chunk failure. Read performance is increased; write performance does incur additional overhead. .It CRYPTO An .Em encrypting discipline. It encrypts data on a single chunk to provide for data confidentiality. CRYPTO does not provide redundancy. .It CONCAT A .Em concatenating discipline. It writes data to each chunk in sequence to provide increased capacity. CONCAT does not provide redundancy. .It RAID 1C A .Em mirroring and .Em encrypting discipline. It encrypts data to provide for data confidentiality and copies the encrypted data across more than one chunk to prevent data loss in case of a chunk failure. Unlike traditional RAID 1, .Nm supports the use of more than two chunks in a RAID 1C setup. .El .Pp .Xr installboot 8 may be used to install .Xr boot 8 in the boot storage area of the .Nm volume. Boot support is currently limited to the CRYPTO, RAID 1 disciplines on the amd64, arm64, i386, riscv64 and sparc64 platforms. amd64, arm64, riscv64 and sparc64 also have boot support for the RAID 1C discipline. On sparc64, bootable chunks must be RAID partitions using the letter .Sq a . At the .Xr boot 8 prompt, softraid volumes have names beginning with .Sq sr and can be booted from like a normal disk device. CRYPTO and 1C volumes will require a decryption passphrase or keydisk at boot time. .Pp The status of .Nm volumes is reported via .Xr sysctl 8 such that it can be monitored by .Xr sensorsd 8 . Each volume has one fourth level node named .Va hw.sensors.softraid0.drive Ns Ar N , where .Ar N is a small integer indexing the volume. The format of the volume status is: .Pp .D1 Ar value Po Ar device Pc , Ar status .Pp The .Ar device identifies the .Nm volume. The following combinations of .Ar value and .Ar status can occur: .Bl -tag -width Ds -offset indent .It Sy online , OK The volume is operating normally. .It Sy degraded , WARNING The volume as a whole is operational, but not all of its chunks are. In many cases, using .Xr bioctl 8 .Fl R to rebuild the failed chunk is advisable. .It Sy rebuilding , WARNING A rebuild operation was recently started and has not yet completed. .It Sy failed , CRITICAL The device is currently unable to process I/O. .It Sy unknown , UNKNOWN The status is unknown to the system. .El .Sh EXAMPLES An example to create a 3 chunk RAID 1 from scratch is as follows: .Pp Initialize the partition tables of all disks: .Bd -literal -offset indent # fdisk -iy wd1 # fdisk -iy wd2 # fdisk -iy wd3 .Ed .Pp Now create RAID partitions on all disks: .Bd -literal -offset indent # echo 'RAID *' | disklabel -wAT- wd1 # echo 'RAID *' | disklabel -wAT- wd2 # echo 'RAID *' | disklabel -wAT- wd3 .Ed .Pp Assemble the RAID volume: .Bd -literal -offset indent # bioctl -c 1 -l /dev/wd1a,/dev/wd2a,/dev/wd3a softraid0 .Ed .Pp The console will show what device was added to the system: .Bd -literal -offset indent scsibus0 at softraid0: 1 targets sd0 at scsibus0 targ 0 lun 0: SCSI2 sd0: 1MB, 0 cyl, 255 head, 63 sec, 512 bytes/sec, 3714 sec total .Ed .Pp It is good practice to wipe the front of the disk before using it: .Bd -literal -offset indent # dd if=/dev/zero of=/dev/rsd0c bs=1m count=1 .Ed .Pp Initialize the partition table and create a filesystem on the new RAID volume: .Bd -literal -offset indent # fdisk -iy sd0 # echo '/ *' | disklabel -wAT- sd0 # newfs /dev/rsd0a .Ed .Pp The RAID volume is now ready to be used as a normal disk device. See .Xr bioctl 8 for more information on configuration of RAID sets. .Pp Install .Xr boot 8 on the RAID volume: .Bd -literal -offset indent # installboot sd0 .Ed .Pp At the .Xr boot 8 prompt, load the /bsd kernel from the RAID volume: .Bd -literal -offset indent boot> boot sr0a:/bsd .Ed .Sh SEE ALSO .Xr bio 4 , .Xr bioctl 8 , .Xr boot_sparc64 8 , .Xr disklabel 8 , .Xr fdisk 8 , .Xr installboot 8 , .Xr newfs 8 .Sh HISTORY The .Nm driver first appeared in .Ox 4.2 . .Sh AUTHORS .An Marco Peereboom . .Sh CAVEATS The driver relies on underlying hardware to properly fail chunks. .Pp The RAID 1 discipline does not initialize the mirror upon creation. This is by design because all sectors that are read are written first. There is no point in wasting a lot of time syncing random data. .Pp The RAID 5 discipline does not initialize parity upon creation, instead parity is only updated upon write. .Pp Stacking disciplines (CRYPTO on top of RAID 1, for example) is not supported at this time. .Pp Currently there is no automated mechanism to recover from failed disks. .Pp Certain RAID levels can protect against some data loss due to component failure. RAID is .Em not a substitute for good backup practices.