.\"	$OpenBSD: bioctl.8,v 1.96 2015/05/29 00:33:37 uebayasi Exp $
.\"
.\" Copyright (c) 2004, 2005 Marco Peereboom
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd $Mdocdate: May 29 2015 $
.Dt BIOCTL 8
.Os
.Sh NAME
.Nm bioctl
.Nd RAID management interface
.Sh SYNOPSIS
.Nm bioctl
.Bk -words
.Op Fl hiqv
.Op Fl a Ar alarm-function
.Op Fl b Ar channel:target[.lun]
.Op Fl H Ar channel:target[.lun]
.Op Fl R Ar device | channel:target[.lun]
.Op Fl t Ar patrol-function
.Op Fl u Ar channel:target[.lun]
.Ar device
.Ek
.Pp
.Nm bioctl
.Bk -words
.Op Fl dhiPqsv
.Op Fl C Ar flag[,flag,...]
.Op Fl c Ar raidlevel
.Op Fl k Ar keydisk
.Op Fl l Ar special[,special,...]
.Op Fl O Ar device | channel:target[.lun]
.Op Fl p Ar passfile
.Op Fl R Ar device | channel:target[.lun]
.Op Fl r Ar rounds
.Ar device
.Ek
.Sh DESCRIPTION
RAID device drivers which support management functionality can
register their services with the
.Xr bio 4
driver.
.Nm bioctl
then can be used to maintain RAID volumes.
.Pp
In the first synopsis,
RAID controllers are managed.
.Ar device
specifies either a drive (e.g. sd0) or a RAID controller (e.g. ami0).
For operations which will be performed against
.Xr ses 4
or
.Xr safte 4
enclosures, it is also possible to directly specify the enclosure name
(e.g. safte0).
.Pp
In the second synopsis,
.Xr softraid 4
devices are managed.
.Ar device
specifies either a drive (e.g. sd0) or a
.Xr softraid 4
device (e.g. softraid0).
.Pp
The options for RAID controllers are as follows:
.Bl -tag -width Ds
.It Fl a Ar alarm-function
Control the RAID card's alarm functionality, if supported.
.Ar alarm-function
may be one of:
.Pp
.Bl -tag -width disable -compact
.It Ar disable
Disable the alarm on the RAID controller.
.It Ar enable
Enable the alarm on the RAID controller.
.It Ar get
Retrieve the current alarm state (enabled or disabled).
.It Ar silence | Ar quiet
Silence the alarm if it is currently beeping.
.El
.Pp
The
.Ar alarm-function
may be specified as given above,
or by the first letter only
(e.g. -a e).
.It Fl b Ar channel:target[.lun]
Instruct the device at
.Ar channel:target[.lun]
to start blinking, if there is
.Xr ses 4
or
.Xr safte 4
support in the enclosure.
.It Fl H Ar channel:target[.lun]
If the device at
.Ar channel:target[.lun]
is currently marked
.Dq Unused ,
promote it to being a
.Dq Hot Spare .
.It Fl h
Where necessary, produce
.Dq human-readable
output.
Use unit suffixes: Byte, Kilobyte, Megabyte,
Gigabyte, Terabyte, Petabyte, Exabyte in order to reduce the number of
digits to four or less.
.It Fl i
Enumerate the selected RAID devices.
This is the default if no other option is given.
.It Fl q
Show vendor, product, revision, and serial number for the given disk.
.It Fl R Ar device | channel:target[.lun]
Manually kick off a rebuild of a RAID volume, using
.Ar device
or
.Ar channel:target[.lun]
as a new chunk (with
.Xr softraid 4 ,
a partition of fstype
.Dq RAID )
in the volume.
.Ar device
must be specified as a full path to the chunk device file (e.g. /dev/wd0d).
A RAID volume rather than a RAID controller is expected as the final argument.
.It Fl t Ar patrol-function
Control the RAID card's patrol functionality, if supported.
.Ar patrol-function
may be one of:
.Pp
.Bl -tag -width disable -compact
.It Ar stop
Stop the patrol on the RAID controller.
.It Ar start
Start the patrol on the RAID controller.
.It Ar get
Retrieve the current patrol configuration.
.It Ar disable
Disable the patrol functionality.
.It Ar manual
Enable the patrol functionality to start/stop manually.
.It Ar auto[.interval[.start]]
Enable the patrol functionality to start/stop automatically in every
.Ar interval
seconds, starting the first iteration after
.Ar start
seconds.
.El
.It Fl u Ar channel:target[.lun]
Instruct the device at
.Ar channel:target[.lun]
to cease blinking, if there is
.Xr ses 4
or
.Xr safte 4
support in the enclosure.
.It Fl v
Be more verbose in output.
.El
.Pp
In addition to the relevant options listed above,
the options for
.Xr softraid 4
devices are as follows:
.Bl -tag -width Ds
.It Fl C Ar flag[,flag,...]
Pass
.Ar flag
to
.Nm .
May be one of:
.Pp
.Bl -tag -width disable -compact
.It Ar force
Force the operation;
for example, force the creation of volumes
with unclean data in the metadata areas.
.It Ar noauto
Do not automatically assemble this volume at boot time.
.El
.It Fl c Ar raidlevel
Create a
.Xr softraid 4
device of level
.Ar raidlevel .
The device must begin with
.Dq softraid
followed by a number.
.Pp
Valid raidlevels are:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It 0
RAID 0:
A striping discipline.
.It 1
RAID 1:
A mirroring discipline.
.It 5
RAID 5:
A striping discipline with floating parity chunk.
.It C
CRYPTO:
An encrypting discipline.
.It c
CONCAT:
A concatenating discipline.
.El
.Pp
The RAID 0, RAID 1 and CONCAT disciplines require a minimum of two devices to
be provided via
.Fl l .
RAID 5 requires at least three devices
and the CRYPTO discipline requires exactly one.
.It Fl d
Delete volume specified by device.
.It Fl k Ar keydisk
Use special device
.Ar keydisk
as a key disk for a crypto volume.
.It Fl l Ar special[,special,...]
Use
.Ar special
device list to create within the
.Xr softraid 4
framework.
Requires
.Fl c .
.It Fl O Ar device | channel:target[.lun]
Set the state of
.Ar device
or
.Ar channel:target[.lun]
to offline.
The state of the RAID volume will change in the same way that it would if the
disk physically went offline.
.Ar device
must be specified as a full path to the chunk device file (e.g. /dev/wd0d).
A RAID volume rather than a RAID controller is expected as the final argument.
.It Fl P
Change the passphrase on the selected crypto volume.
.It Fl p Ar passfile
Passphrase file used when crypto volumes are brought up.
This file must be root owned and have 0600 permissions.
This option cannot be used during the initial creation of the crypto volume.
.It Fl r Ar rounds
When creating an encrypted volume, specifies the number of iterations of
the PBKDF2 algorithm used to convert a passphrase into a key.
Higher iteration counts take more time, but offer more resistance to key
guessing attacks.
The minimum is 1000 rounds and the default is 8192.
.It Fl s
Read the passphrase for the selected crypto volume from
.Pa /dev/stdin
rather than
.Pa /dev/tty .
This option cannot be used during the initial creation of the crypto volume.
.El
.Sh EXAMPLES
The following command, executed from the command line, would configure
the device softraid0 with 4 special devices
(/dev/sd2e, /dev/sd3e, /dev/sd4e, /dev/sd5e) and
a RAID level of 1:
.Bd -literal -offset 3n
# bioctl -c 1 -l /dev/sd2e,/dev/sd3e,/dev/sd4e,/dev/sd5e softraid0
.Ed
.Pp
The following command, executed from the command line, would configure the
device softraid0 with one special device (/dev/sd2e) and an encrypting
volume:
.Bd -literal -offset 3n
# bioctl -c C -l /dev/sd2e softraid0
.Ed
.Pp
.Nm
will ask for a passphrase, which will be needed to unlock the encrypted
disk.
After creating a newly encrypted disk, the first megabyte of it should be
zeroed, so tools like
.Xr fdisk 8
or
.Xr disklabel 8
don't get confused by the random data that appears on the new disk.
This can be done with the following command (assuming the new disk is sd3):
.Bd -literal -offset 3n
# dd if=/dev/zero of=/dev/rsd3c bs=1m count=1
.Ed
.Pp
Deleting a softraid volume requires the exact volume name.
For example:
.Bd -literal -offset 3n
# bioctl -d sd2
.Ed
.Pp
The following command starts a rebuild of the degraded softraid volume sd0
using a new chunk on wd0d:
.Bd -literal -offset 3n
# bioctl -R /dev/wd0d sd0
.Ed
.Sh SEE ALSO
.Xr bio 4 ,
.Xr scsi 4 ,
.Xr softraid 4
.Sh STANDARDS
.Rs
.%A B. Kaliski
.%D September 2000
.%R RFC 2898
.%T PKCS #5: Password-Based Cryptography Specification Version 2.0
.Re
.Sh HISTORY
The
.Nm
command first appeared in
.Ox 3.8 .
.Sh AUTHORS
The
.Nm
interface was written by
.An Marco Peereboom Aq Mt marco@openbsd.org .
.Sh CAVEATS
Only devices with 512-byte sectors are supported.