1.\" $OpenBSD: bioctl.8,v 1.100 2016/09/19 18:02:20 jsing 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 19 2016 $ 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 device | 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 flag Ns Op Pf , Ar ... 46.Op Fl c Ar raidlevel 47.Op Fl k Ar keydisk 48.Op Fl l Ar special Ns Op Pf , Ar special Ns Op Pf , Ar ... 49.Op Fl O Ar device | channel : Ns Ar target Ns Op Pf . Ar lun 50.Op Fl p Ar passfile 51.Op Fl R Ar device | 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 75devices are managed. 76.Ar device 77specifies either a drive (e.g. sd0) or a 78.Xr softraid 4 79device (e.g. 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 device | channel : Ns Ar target Ns Op Pf . Ar lun 132Manually kick off a rebuild of a RAID volume, using 133.Ar device 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 ) 140in the volume. 141.Ar device 142must be specified as a full path to the chunk device file (e.g. /dev/wd0d). 143A RAID volume rather than a RAID controller is expected as the final argument. 144.It Fl t Ar patrol-function 145Control the RAID card's patrol functionality, if supported. 146.Ar patrol-function 147may be one of: 148.Pp 149.Bl -tag -width disable -compact 150.It Cm stop 151Stop the patrol on the RAID controller. 152.It Cm start 153Start the patrol on the RAID controller. 154.It Cm get 155Retrieve the current patrol configuration. 156.It Cm disable 157Disable the patrol functionality. 158.It Cm manual 159Enable the patrol functionality to start/stop manually. 160.It Cm auto Ns Op Pf . Ar interval Ns Op Pf . Ar start 161Enable the patrol functionality to start/stop automatically in every 162.Ar interval 163seconds, starting the first iteration after 164.Ar start 165seconds. 166.El 167.It Fl u Ar channel : Ns Ar target Ns Op Pf . Ar lun 168Instruct the device at 169.Ar channel : Ns Ar target Ns Op Pf . Ar lun 170to cease blinking, if there is 171.Xr ses 4 172or 173.Xr safte 4 174support in the enclosure. 175.It Fl v 176Be more verbose in output. 177.El 178.Pp 179In addition to the relevant options listed above, 180the options for 181.Xr softraid 4 182devices are as follows: 183.Bl -tag -width Ds 184.It Fl C Ar flag Ns Op Pf , Ar flag Ns Op Pf , Ar ... 185Pass 186.Ar flag 187to 188.Nm . 189May be one of: 190.Pp 191.Bl -tag -width disable -compact 192.It Cm force 193Force the operation; 194for example, force the creation of volumes 195with unclean data in the metadata areas. 196.It Cm noauto 197Do not automatically assemble this volume at boot time. 198.El 199.It Fl c Ar raidlevel 200Create a 201.Xr softraid 4 202device of level 203.Ar raidlevel . 204The device must begin with 205.Dq softraid 206followed by a number. 207.Pp 208Valid raidlevels are: 209.Pp 210.Bl -tag -width 2n -offset 3n -compact 211.It Cm 0 212RAID 0: 213A striping discipline. 214.It Cm 1 215RAID 1: 216A mirroring discipline. 217.It Cm 5 218RAID 5: 219A striping discipline with floating parity chunk. 220.It Cm C 221CRYPTO: 222An encrypting discipline. 223.It Cm c 224CONCAT: 225A concatenating discipline. 226.El 227.Pp 228The RAID 0, RAID 1 and CONCAT disciplines require a minimum of two devices to 229be provided via 230.Fl l . 231RAID 5 requires at least three devices 232and the CRYPTO discipline requires exactly one. 233.It Fl d 234Delete volume specified by device. 235.It Fl k Ar keydisk 236Use special device 237.Ar keydisk 238as a key disk for a crypto volume. 239.It Fl l Ar special Ns Op Pf , Ar special Ns Op Pf , Ar ... 240Use 241.Ar special 242device list to create within the 243.Xr softraid 4 244framework. 245Requires 246.Fl c . 247.It Fl O Ar device | channel : Ns Ar target Ns Op Pf . Ar lun 248Set the state of 249.Ar device 250or 251.Ar channel : Ns Ar target Ns Op Pf . Ar lun 252to offline. 253The state of the RAID volume will change in the same way that it would if the 254disk physically went offline. 255.Ar device 256must be specified as a full path to the chunk device file (e.g. /dev/wd0d). 257A RAID volume rather than a RAID controller is expected as the final argument. 258.It Fl P 259Change the passphrase on the selected crypto volume. 260.It Fl p Ar passfile 261Passphrase file used when crypto volumes are brought up. 262This file must be root owned and have 0600 permissions. 263.It Fl r Ar rounds 264When creating an encrypted volume, specifies the number of iterations of 265the PBKDF algorithm used to convert a passphrase into a key. 266Higher iteration counts take more time, but offer more resistance to key 267guessing attacks. 268The minimum is 4 rounds and the default is 16. 269.It Fl s 270Read the passphrase for the selected crypto volume from 271.Pa /dev/stdin 272rather than 273.Pa /dev/tty . 274This option cannot be used during the initial creation of the crypto volume. 275.El 276.Sh EXAMPLES 277The following command, executed from the command line, would configure 278the device softraid0 with 4 special devices 279(/dev/sd2e, /dev/sd3e, /dev/sd4e, /dev/sd5e) and 280a RAID level of 1: 281.Bd -literal -offset 3n 282# bioctl -c 1 -l /dev/sd2e,/dev/sd3e,/dev/sd4e,/dev/sd5e softraid0 283.Ed 284.Pp 285The following command, executed from the command line, would configure the 286device softraid0 with one special device (/dev/sd2e) and an encrypting 287volume: 288.Bd -literal -offset 3n 289# bioctl -c C -l /dev/sd2e softraid0 290.Ed 291.Pp 292.Nm 293will ask for a passphrase, which will be needed to unlock the encrypted 294disk. 295After creating a newly encrypted disk, the first megabyte of it should be 296zeroed, so tools like 297.Xr fdisk 8 298or 299.Xr disklabel 8 300don't get confused by the random data that appears on the new disk. 301This can be done with the following command (assuming the new disk is sd3): 302.Bd -literal -offset 3n 303# dd if=/dev/zero of=/dev/rsd3c bs=1m count=1 304.Ed 305.Pp 306Deleting a softraid volume requires the exact volume name. 307For example: 308.Bd -literal -offset 3n 309# bioctl -d sd2 310.Ed 311.Pp 312The following command starts a rebuild of the degraded softraid volume sd0 313using a new chunk on wd0d: 314.Bd -literal -offset 3n 315# bioctl -R /dev/wd0d sd0 316.Ed 317.Sh SEE ALSO 318.Xr bio 4 , 319.Xr scsi 4 , 320.Xr softraid 4 321.Sh HISTORY 322The 323.Nm 324command first appeared in 325.Ox 3.8 . 326.Sh AUTHORS 327The 328.Nm 329interface was written by 330.An Marco Peereboom Aq Mt marco@openbsd.org . 331