path: root/sbin/bioctl/bioctl.8

.\"	$OpenBSD: bioctl.8,v 1.114 2023/09/02 09:14:47 kn 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: September 2 2023 $
.Dt BIOCTL 8
.Os
.Sh NAME
.Nm bioctl
.Nd RAID management interface
.Sh SYNOPSIS
.Nm bioctl
.Op Fl hiqv
.Op Fl a Ar alarm-function
.Op Fl b Ar channel : Ns Ar target Ns Op Pf . Ar lun
.Op Fl H Ar channel : Ns Ar target Ns Op Pf . Ar lun
.Op Fl R Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun
.Op Fl t Ar patrol-function
.Op Fl u Ar channel : Ns Ar target Ns Op Pf . Ar lun
.Ar device
.Pp
.Nm bioctl
.Op Fl dhiPqsv
.Op Fl C Ar flag Ns Op Pf , Ar ...
.Op Fl c Ar raidlevel
.Op Fl k Ar keydisk
.Op Fl l Ar chunk Ns Op Pf , Ar ...
.Op Fl O Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun
.Op Fl p Ar passfile
.Op Fl R Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun
.Op Fl r Ar rounds
.Ar device
.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
volumes are managed.
.Ar device
specifies either a volume (e.g. sd0) or the
.Xr softraid 4
controller (always 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 Cm disable
Disable the alarm on the RAID controller.
.It Cm enable
Enable the alarm on the RAID controller.
.It Cm get
Retrieve the current alarm state (enabled or disabled).
.It Cm silence | 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 : Ns Ar target Ns Op Pf . Ar lun
Instruct the device at
.Ar channel : Ns Ar target Ns Op Pf . Ar lun
to start blinking, if there is
.Xr ses 4
or
.Xr safte 4
support in the enclosure.
.It Fl H Ar channel : Ns Ar target Ns Op Pf . Ar lun
If the device at
.Ar channel : Ns Ar target Ns Op Pf . Ar 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 chunk | channel : Ns Ar target Ns Op Pf . Ar lun
Manually kick off a rebuild of a degraded RAID volume, using
.Ar chunk
or
.Ar channel : Ns Ar target Ns Op Pf . Ar lun
as a new chunk (with
.Xr softraid 4 ,
a partition of fstype
.Dq RAID ) ,
replacing the offline chunk in the volume;
it is not possible to change the number of chunks.
The
.Ar chunk
must be specified as a full path to a 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 Cm stop
Stop the patrol on the RAID controller.
.It Cm start
Start the patrol on the RAID controller.
.It Cm get
Retrieve the current patrol configuration.
.It Cm disable
Disable the patrol functionality.
.It Cm manual
Enable the patrol functionality to start/stop manually.
.It Cm auto Ns Op Pf . Ar interval Ns Op Pf . Ar 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 : Ns Ar target Ns Op Pf . Ar lun
Instruct the device at
.Ar channel : Ns Ar target Ns Op Pf . Ar 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 Ns Op Pf , Ar ...
Pass
.Ar flag
to
.Nm .
May be one of:
.Pp
.Bl -tag -width disable -compact
.It Cm force
Force the operation;
for example, force the creation of volumes
with unclean data in the metadata areas.
.It Cm noauto
Do not automatically assemble this volume at boot time.
.El
.It Fl c Ar raidlevel
Create a new
.Xr softraid 4
volume of level
.Ar raidlevel .
The
.Ar device
must be
.Dq softraid0 ;
it supports multiple volumes.
.Pp
Valid raidlevels are:
.Pp
.Bl -tag -width 2n -offset 3n -compact
.It Cm 0
RAID 0:
A striping discipline.
.It Cm 1
RAID 1:
A mirroring discipline.
.It Cm 5
RAID 5:
A striping discipline with floating parity chunk.
.It Cm C
CRYPTO:
An encrypting discipline.
.It Cm c
CONCAT:
A concatenating discipline.
.It Cm 1C
RAID 1 + CRYPTO:
An encrypting and mirroring discipline.
.El
.Pp
The CONCAT discipline requires a minimum of one chunk, RAID 0 and RAID 1
disciplines require a minimum of two chunks, RAID 5 requires a minimum
of three chunks and the CRYPTO discipline requires exactly one chunk to
be provided via
.Fl l .
.Pp
The RAID 1C discipline requires a minimum of two chunks when a new volume
is created, and a minimum of one chunk when an existing volume is assembled.
Missing RAID 1C chunks will be marked as offline and must be rebuilt before
they become part of the array again.
.It Fl d
Detach volume specified by
.Ar device .
.It Fl k Ar keydisk
Use special device
.Ar keydisk
as a key disk for a crypto volume.
.It Fl l Ar chunk Ns Op Pf , Ar ...
Use the
.Ar chunk
device list to create a new volume within the
.Xr softraid 4
framework.
Requires
.Fl c .
.It Fl O Ar chunk | channel : Ns Ar target Ns Op Pf . Ar lun
Set the state of
.Ar chunk
or
.Ar channel : Ns Ar target Ns Op Pf . Ar lun
to offline.
The state of the RAID volume will change in the same way that it would if the
disk physically went offline.
The
.Ar chunk
must be specified as a full path to a device file (e.g. /dev/wd0d).
A RAID volume rather than a RAID controller is expected as the
.Ar device
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.
.It Fl r Ar rounds
The number of iterations for the KDF algorithm to use when converting a
passphrase into a key, in order to create a new encrypted volume or change the
passphrase of an existing encrypted volume.
A larger number of iterations takes more time, but offers increased resistance
against passphrase guessing attacks.
By default, or if
.Ar rounds
is specified as
.Cm auto ,
the number of rounds will automatically be based on system performance.
The minimum is 16 rounds.
.It Fl s
Read passphrases from
.Pa /dev/stdin
rather than
.Pa /dev/tty ,
without prompts, confirmation or retry on mismatch.
.El
.Sh EXAMPLES
Configure a new
.Xr softraid 4
volume with four chunks
(/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
Configure a new
.Xr softraid 4
volume with one chunk (/dev/sd2e) and an encrypting discipline:
.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:
.Bd -literal -offset 3n
# dd if=/dev/zero of=/dev/rsd3c bs=1m count=1
.Ed
.Pp
Detaching a softraid volume requires the exact volume name.
For example:
.Bd -literal -offset 3n
# bioctl -d sd2
.Ed
.Pp
Start 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 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 .