1.\" $OpenBSD: bioctl.8,v 1.114 2023/09/02 09:14:47 kn Exp $ 2.\" 3.\" Copyright (c) 2004, 2005 Marco Peereboom 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR 18.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd $Mdocdate: September 2 2023 $ 27.Dt BIOCTL 8 28.Os 29.Sh NAME 30.Nm bioctl 31.Nd RAID management interface 32.Sh SYNOPSIS 33.Nm bioctl 34.Op Fl hiqv 35.Op Fl a Ar alarm-function 36.Op Fl b Ar channel : Ns Ar target Ns Op Pf . Ar lun 37.Op Fl H Ar channel : Ns Ar target Ns Op Pf . Ar lun 38.Op Fl R Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun 39.Op Fl t Ar patrol-function 40.Op Fl u Ar channel : Ns Ar target Ns Op Pf . Ar lun 41.Ar device 42.Pp 43.Nm bioctl 44.Op Fl dhiPqsv 45.Op Fl C Ar flag Ns Op Pf , Ar ... 46.Op Fl c Ar raidlevel 47.Op Fl k Ar keydisk 48.Op Fl l Ar chunk Ns Op Pf , Ar ... 49.Op Fl O Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun 50.Op Fl p Ar passfile 51.Op Fl R Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun 52.Op Fl r Ar rounds 53.Ar device 54.Sh DESCRIPTION 55RAID device drivers which support management functionality can 56register their services with the 57.Xr bio 4 58driver. 59.Nm bioctl 60then can be used to maintain RAID volumes. 61.Pp 62In the first synopsis, 63RAID controllers are managed. 64.Ar device 65specifies either a drive (e.g. sd0) or a RAID controller (e.g. ami0). 66For operations which will be performed against 67.Xr ses 4 68or 69.Xr safte 4 70enclosures, it is also possible to directly specify the enclosure name 71(e.g. safte0). 72.Pp 73In the second synopsis, 74.Xr softraid 4 75volumes are managed. 76.Ar device 77specifies either a volume (e.g. sd0) or the 78.Xr softraid 4 79controller (always softraid0). 80.Pp 81The options for RAID controllers are as follows: 82.Bl -tag -width Ds 83.It Fl a Ar alarm-function 84Control the RAID card's alarm functionality, if supported. 85.Ar alarm-function 86may be one of: 87.Pp 88.Bl -tag -width disable -compact 89.It Cm disable 90Disable the alarm on the RAID controller. 91.It Cm enable 92Enable the alarm on the RAID controller. 93.It Cm get 94Retrieve the current alarm state (enabled or disabled). 95.It Cm silence | quiet 96Silence the alarm if it is currently beeping. 97.El 98.Pp 99The 100.Ar alarm-function 101may be specified as given above, 102or by the first letter only 103(e.g. -a e). 104.It Fl b Ar channel : Ns Ar target Ns Op Pf . Ar lun 105Instruct the device at 106.Ar channel : Ns Ar target Ns Op Pf . Ar lun 107to start blinking, if there is 108.Xr ses 4 109or 110.Xr safte 4 111support in the enclosure. 112.It Fl H Ar channel : Ns Ar target Ns Op Pf . Ar lun 113If the device at 114.Ar channel : Ns Ar target Ns Op Pf . Ar lun 115is currently marked 116.Dq Unused , 117promote it to being a 118.Dq Hot Spare . 119.It Fl h 120Where necessary, produce 121.Dq human-readable 122output. 123Use unit suffixes: Byte, Kilobyte, Megabyte, 124Gigabyte, Terabyte, Petabyte, Exabyte in order to reduce the number of 125digits to four or less. 126.It Fl i 127Enumerate the selected RAID devices. 128This is the default if no other option is given. 129.It Fl q 130Show vendor, product, revision, and serial number for the given disk. 131.It Fl R Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun 132Manually kick off a rebuild of a degraded RAID volume, using 133.Ar chunk 134or 135.Ar channel : Ns Ar target Ns Op Pf . Ar lun 136as a new chunk (with 137.Xr softraid 4 , 138a partition of fstype 139.Dq RAID ) , 140replacing the offline chunk in the volume; 141it is not possible to change the number of chunks. 142The 143.Ar chunk 144must be specified as a full path to a device file (e.g. /dev/wd0d). 145A RAID volume rather than a RAID controller is expected as the final argument. 146.It Fl t Ar patrol-function 147Control the RAID card's patrol functionality, if supported. 148.Ar patrol-function 149may be one of: 150.Pp 151.Bl -tag -width disable -compact 152.It Cm stop 153Stop the patrol on the RAID controller. 154.It Cm start 155Start the patrol on the RAID controller. 156.It Cm get 157Retrieve the current patrol configuration. 158.It Cm disable 159Disable the patrol functionality. 160.It Cm manual 161Enable the patrol functionality to start/stop manually. 162.It Cm auto Ns Op Pf . Ar interval Ns Op Pf . Ar start 163Enable the patrol functionality to start/stop automatically in every 164.Ar interval 165seconds, starting the first iteration after 166.Ar start 167seconds. 168.El 169.It Fl u Ar channel : Ns Ar target Ns Op Pf . Ar lun 170Instruct the device at 171.Ar channel : Ns Ar target Ns Op Pf . Ar lun 172to cease blinking, if there is 173.Xr ses 4 174or 175.Xr safte 4 176support in the enclosure. 177.It Fl v 178Be more verbose in output. 179.El 180.Pp 181In addition to the relevant options listed above, 182the options for 183.Xr softraid 4 184devices are as follows: 185.Bl -tag -width Ds 186.It Fl C Ar flag Ns Op Pf , Ar ... 187Pass 188.Ar flag 189to 190.Nm . 191May be one of: 192.Pp 193.Bl -tag -width disable -compact 194.It Cm force 195Force the operation; 196for example, force the creation of volumes 197with unclean data in the metadata areas. 198.It Cm noauto 199Do not automatically assemble this volume at boot time. 200.El 201.It Fl c Ar raidlevel 202Create a new 203.Xr softraid 4 204volume of level 205.Ar raidlevel . 206The 207.Ar device 208must be 209.Dq softraid0 ; 210it supports multiple volumes. 211.Pp 212Valid raidlevels are: 213.Pp 214.Bl -tag -width 2n -offset 3n -compact 215.It Cm 0 216RAID 0: 217A striping discipline. 218.It Cm 1 219RAID 1: 220A mirroring discipline. 221.It Cm 5 222RAID 5: 223A striping discipline with floating parity chunk. 224.It Cm C 225CRYPTO: 226An encrypting discipline. 227.It Cm c 228CONCAT: 229A concatenating discipline. 230.It Cm 1C 231RAID 1 + CRYPTO: 232An encrypting and mirroring discipline. 233.El 234.Pp 235The CONCAT discipline requires a minimum of one chunk, RAID 0 and RAID 1 236disciplines require a minimum of two chunks, RAID 5 requires a minimum 237of three chunks and the CRYPTO discipline requires exactly one chunk to 238be provided via 239.Fl l . 240.Pp 241The RAID 1C discipline requires a minimum of two chunks when a new volume 242is created, and a minimum of one chunk when an existing volume is assembled. 243Missing RAID 1C chunks will be marked as offline and must be rebuilt before 244they become part of the array again. 245.It Fl d 246Detach volume specified by 247.Ar device . 248.It Fl k Ar keydisk 249Use special device 250.Ar keydisk 251as a key disk for a crypto volume. 252.It Fl l Ar chunk Ns Op Pf , Ar ... 253Use the 254.Ar chunk 255device list to create a new volume within the 256.Xr softraid 4 257framework. 258Requires 259.Fl c . 260.It Fl O Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun 261Set the state of 262.Ar chunk 263or 264.Ar channel : Ns Ar target Ns Op Pf . Ar lun 265to offline. 266The state of the RAID volume will change in the same way that it would if the 267disk physically went offline. 268The 269.Ar chunk 270must be specified as a full path to a device file (e.g. /dev/wd0d). 271A RAID volume rather than a RAID controller is expected as the 272.Ar device 273argument. 274.It Fl P 275Change the passphrase on the selected crypto volume. 276.It Fl p Ar passfile 277Passphrase file used when crypto volumes are brought up. 278This file must be root owned and have 0600 permissions. 279.It Fl r Ar rounds 280The number of iterations for the KDF algorithm to use when converting a 281passphrase into a key, in order to create a new encrypted volume or change the 282passphrase of an existing encrypted volume. 283A larger number of iterations takes more time, but offers increased resistance 284against passphrase guessing attacks. 285By default, or if 286.Ar rounds 287is specified as 288.Cm auto , 289the number of rounds will automatically be based on system performance. 290The minimum is 16 rounds. 291.It Fl s 292Read passphrases from 293.Pa /dev/stdin 294rather than 295.Pa /dev/tty , 296without prompts, confirmation or retry on mismatch. 297.El 298.Sh EXAMPLES 299Configure a new 300.Xr softraid 4 301volume with four chunks 302(/dev/sd2e, /dev/sd3e, /dev/sd4e, /dev/sd5e) 303and a RAID level of 1: 304.Bd -literal -offset 3n 305# bioctl -c 1 -l /dev/sd2e,/dev/sd3e,/dev/sd4e,/dev/sd5e softraid0 306.Ed 307.Pp 308Configure a new 309.Xr softraid 4 310volume with one chunk (/dev/sd2e) and an encrypting discipline: 311.Bd -literal -offset 3n 312# bioctl -c C -l /dev/sd2e softraid0 313.Ed 314.Pp 315.Nm 316will ask for a passphrase, which will be needed to unlock the encrypted 317disk. 318After creating a newly encrypted disk, the first megabyte of it should be 319zeroed, so tools like 320.Xr fdisk 8 321or 322.Xr disklabel 8 323don't get confused by the random data that appears on the new disk: 324.Bd -literal -offset 3n 325# dd if=/dev/zero of=/dev/rsd3c bs=1m count=1 326.Ed 327.Pp 328Detaching a softraid volume requires the exact volume name. 329For example: 330.Bd -literal -offset 3n 331# bioctl -d sd2 332.Ed 333.Pp 334Start a rebuild of the degraded softraid volume sd0 335using a new chunk on wd0d: 336.Bd -literal -offset 3n 337# bioctl -R /dev/wd0d sd0 338.Ed 339.Sh SEE ALSO 340.Xr bio 4 , 341.Xr scsi 4 , 342.Xr softraid 4 343.Sh HISTORY 344The 345.Nm 346command first appeared in 347.Ox 3.8 . 348.Sh AUTHORS 349The 350.Nm 351interface was written by 352.An Marco Peereboom Aq Mt marco@openbsd.org . 353