1.\" $OpenBSD: bioctl.8,v 1.116 2024/07/15 05:36:08 jmc 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: July 15 2024 $ 27.Dt BIOCTL 8 28.Os 29.Sh NAME 30.Nm bioctl 31.Nd storage 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 55.Nm bioctl 56is used to interact with device drivers that register with 57.Xr bio 4 . 58.Pp 59The 60.Fl h , 61.Fl i , 62.Fl q , 63and 64.Fl v 65options are used to display information about the specified 66.Ar device : 67.Bl -tag -width disable 68.It Fl h 69Where appropriate, produce 70.Dq human-readable 71output. 72Use unit suffixes: Byte, Kilobyte, Megabyte, 73Gigabyte, Terabyte, Petabyte, Exabyte in order to reduce the number of 74digits to four or less. 75.It Fl i 76Display default information for the specified device. 77For example, for hardware RAID controllers enumerate attached devices. 78This is the default if no options are specified. 79.It Fl q 80If 81.Ar device 82is an 83.Xr sd 4 , 84display its vendor, product, revision, and serial number. 85.It Fl v 86Be more verbose in output. 87.El 88.Pp 89The first synopsis shows options used to manage 90hardware RAID controllers. 91.Ar device 92specifies either a drive (e.g. sd1), a hardware RAID controller (e.g. ami0) or a 93.Xr ses 4 94or 95.Xr safte 4 96enclosure. 97.Pp 98The second synopsis shows options used to manage 99.Xr softraid 4 100volumes (e.g. sd0) 101or the softraid controller itself 102(always softraid0). 103.Pp 104The options for hardware RAID controllers are as follows: 105.Bl -tag -width Ds 106.It Fl a Ar alarm-function 107Control the RAID card's alarm functionality, if supported. 108.Ar alarm-function 109may be one of: 110.Pp 111.Bl -tag -width disable -compact 112.It Cm disable 113Disable the alarm on the RAID controller. 114.It Cm enable 115Enable the alarm on the RAID controller. 116.It Cm get 117Retrieve the current alarm state (enabled or disabled). 118.It Cm silence | quiet 119Silence the alarm if it is currently beeping. 120.El 121.Pp 122The 123.Ar alarm-function 124may be specified as given above, 125or by the first letter only 126(e.g. -a e). 127.It Fl b Ar channel : Ns Ar target Ns Op Pf . Ar lun 128Instruct the device at 129.Ar channel : Ns Ar target Ns Op Pf . Ar lun 130to start blinking, if there is 131.Xr ses 4 132or 133.Xr safte 4 134support in the enclosure. 135.It Fl H Ar channel : Ns Ar target Ns Op Pf . Ar lun 136If the device at 137.Ar channel : Ns Ar target Ns Op Pf . Ar lun 138is currently marked 139.Dq Unused , 140promote it to being a 141.Dq Hot Spare . 142.It Fl R Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun 143Manually kick off a rebuild of a degraded RAID volume, using 144.Ar chunk 145or 146.Ar channel : Ns Ar target Ns Op Pf . Ar lun 147as a new chunk replacing the offline chunk in the volume. 148It is not possible to change the number of chunks. 149The 150.Ar chunk 151must be specified as a full path to a device file (e.g. /dev/wd0d). 152A RAID volume rather than a RAID controller is expected as the final argument. 153.It Fl t Ar patrol-function 154Control the RAID card's patrol functionality, if supported. 155.Ar patrol-function 156may be one of: 157.Pp 158.Bl -tag -width disable -compact 159.It Cm stop 160Stop the patrol on the RAID controller. 161.It Cm start 162Start the patrol on the RAID controller. 163.It Cm get 164Retrieve the current patrol configuration. 165.It Cm disable 166Disable the patrol functionality. 167.It Cm manual 168Enable the patrol functionality to start/stop manually. 169.It Cm auto Ns Op Pf . Ar interval Ns Op Pf . Ar start 170Enable the patrol functionality to start/stop automatically in every 171.Ar interval 172seconds, starting the first iteration after 173.Ar start 174seconds. 175.El 176.It Fl u Ar channel : Ns Ar target Ns Op Pf . Ar lun 177Instruct the device at 178.Ar channel : Ns Ar target Ns Op Pf . Ar lun 179to cease blinking, if there is 180.Xr ses 4 181or 182.Xr safte 4 183support in the enclosure. 184.El 185.Pp 186The options for 187.Xr softraid 4 188devices are as follows: 189.Bl -tag -width Ds 190.It Fl C Ar flag Ns Op Pf , Ar ... 191Pass 192.Ar flag 193to 194.Nm . 195May be one of: 196.Pp 197.Bl -tag -width disable -compact 198.It Cm force 199Force the operation; 200for example, force the creation of volumes 201with unclean data in the metadata areas. 202.It Cm noauto 203Do not automatically assemble this volume at boot time. 204.El 205.It Fl c Ar raidlevel 206Create a new 207.Xr softraid 4 208volume of level 209.Ar raidlevel . 210The 211.Ar device 212must be 213.Dq softraid0 ; 214it supports multiple volumes. 215.Pp 216Valid raidlevels are: 217.Pp 218.Bl -tag -width 2n -offset 3n -compact 219.It Cm 0 220RAID 0: 221A striping discipline. 222.It Cm 1 223RAID 1: 224A mirroring discipline. 225.It Cm 5 226RAID 5: 227A striping discipline with floating parity chunk. 228.It Cm C 229CRYPTO: 230An encrypting discipline. 231.It Cm c 232CONCAT: 233A concatenating discipline. 234.It Cm 1C 235RAID 1 + CRYPTO: 236An encrypting and mirroring discipline. 237.El 238.Pp 239The CONCAT discipline requires a minimum of one chunk, RAID 0 and RAID 1 240disciplines require a minimum of two chunks, RAID 5 requires a minimum 241of three chunks and the CRYPTO discipline requires exactly one chunk to 242be provided via 243.Fl l . 244.Pp 245The RAID 1C discipline requires a minimum of two chunks when a new volume 246is created, and a minimum of one chunk when an existing volume is assembled. 247Missing RAID 1C chunks will be marked as offline and must be rebuilt before 248they become part of the array again. 249.It Fl d 250Detach volume specified by 251.Ar device . 252.It Fl k Ar keydisk 253Use special device 254.Ar keydisk 255as a key disk for a crypto volume. 256.It Fl l Ar chunk Ns Op Pf , Ar ... 257Use the 258.Ar chunk 259device list to create a new volume within the 260.Xr softraid 4 261framework. 262Requires 263.Fl c . 264.It Fl O Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun 265Set the state of 266.Ar chunk 267or 268.Ar channel : Ns Ar target Ns Op Pf . Ar lun 269to offline. 270The state of the RAID volume will change in the same way that it would if the 271disk physically went offline. 272The 273.Ar chunk 274must be specified as a full path to a device file (e.g. /dev/wd0d). 275A RAID volume rather than a RAID controller is expected as the 276.Ar device 277argument. 278.It Fl P 279Change the passphrase on the selected crypto volume. 280.It Fl p Ar passfile 281Passphrase file used when crypto volumes are brought up. 282This file must be root owned and have 0600 permissions. 283.It Fl R Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun 284Manually kick off a rebuild of a degraded volume, using 285.Ar chunk 286or 287.Ar channel : Ns Ar target Ns Op Pf . Ar lun 288as a new chunk, 289replacing the offline chunk in the volume. 290It is not possible to change the number of chunks. 291The 292.Ar chunk 293must be specified as a full path to a device file (e.g. /dev/sd0d) which 294refers to a partition of fstype RAID. 295A 296.Xr softraid 4 297volume rather than softraid0 is expected as the final argument. 298.It Fl r Ar rounds 299The number of iterations for the KDF algorithm to use when converting a 300passphrase into a key, in order to create a new encrypted volume or change the 301passphrase of an existing encrypted volume. 302A larger number of iterations takes more time, but offers increased resistance 303against passphrase guessing attacks. 304By default, or if 305.Ar rounds 306is specified as 307.Cm auto , 308the number of rounds will automatically be based on system performance. 309The minimum is 16 rounds. 310.It Fl s 311Read passphrases from 312.Pa /dev/stdin 313rather than 314.Pa /dev/tty , 315without prompts, confirmation or retry on mismatch. 316.El 317.Sh EXAMPLES 318Configure a new 319.Xr softraid 4 320volume with four chunks 321(/dev/sd2e, /dev/sd3e, /dev/sd4e, /dev/sd5e) 322and a RAID level of 1: 323.Bd -literal -offset 3n 324# bioctl -c 1 -l /dev/sd2e,/dev/sd3e,/dev/sd4e,/dev/sd5e softraid0 325.Ed 326.Pp 327Configure a new 328.Xr softraid 4 329volume with one chunk (/dev/sd2e) and an encrypting discipline: 330.Bd -literal -offset 3n 331# bioctl -c C -l /dev/sd2e softraid0 332.Ed 333.Pp 334.Nm 335will ask for a passphrase, which will be needed to unlock the encrypted 336disk. 337After creating a newly encrypted disk, the first megabyte of it should be 338zeroed, so tools like 339.Xr fdisk 8 340or 341.Xr disklabel 8 342don't get confused by the random data that appears on the new disk: 343.Bd -literal -offset 3n 344# dd if=/dev/zero of=/dev/rsd3c bs=1m count=1 345.Ed 346.Pp 347Detaching a softraid volume requires the exact volume name. 348For example: 349.Bd -literal -offset 3n 350# bioctl -d sd2 351.Ed 352.Pp 353Start a rebuild of the degraded softraid volume sd0 354using a new chunk on wd0d: 355.Bd -literal -offset 3n 356# bioctl -R /dev/wd0d sd0 357.Ed 358.Pp 359Show detailed information about the nvme0 controller: 360.Bd -literal -offset 3n 361# bioctl -v nvme0 362.Ed 363.Sh SEE ALSO 364.Xr bio 4 , 365.Xr scsi 4 , 366.Xr softraid 4 367.Sh HISTORY 368The 369.Nm 370command first appeared in 371.Ox 3.8 . 372.Sh AUTHORS 373The 374.Nm 375interface was written by 376.An Marco Peereboom Aq Mt marco@openbsd.org . 377