RAID(4)                   OpenBSD Programmer's Manual                  RAID(4)

NAME
     raid - RAIDframe Disk Driver

SYNOPSIS
     pseudo-device raid [count]

DESCRIPTION
     The raid driver provides RAID 0, 1, 4, and 5 (and more!) capabilities.
     This document assumes that the reader has at least some familiarity with
     RAID and RAID concepts.  The reader is also assumed to know how to con-
     figure disks and pseudo-devices into kernels, how to generate kernels,
     and how to partition disks.

     RAIDframe provides a number of different RAID levels including:

     RAID 0  provides simple data striping across the components.

     RAID 1  provides mirroring.

     RAID 4  provides data striping across the components, with parity stored
             on a dedicated drive (in this case, the last component).

     RAID 5  provides data striping across the components, with parity dis-
             tributed across all the components.

     There are a wide variety of other RAID levels supported by RAIDframe, in-
     cluding Even-Odd parity, RAID level 5 with rotated sparing, Chained
     declustering, and Interleaved declustering.  The reader is referred to
     the RAIDframe documentation mentioned in the HISTORY section for more de-
     tail on these various RAID configurations.

     Depending on the parity level configured, the device driver can support
     the failure of component drives.  The number of failures allowed depends
     on the parity level selected.  If the driver is able to handle drive
     failures, and a drive does fail, then the system is operating in "degrad-
     ed mode".  In this mode, all missing data must be reconstructed from the
     data and parity present on the other components.  This results in much
     slower data accesses, but does mean that a failure need not bring the
     system to a complete halt.

     The RAID driver supports and enforces the use of `component labels'. A
     `component label' contains important information about the component, in-
     cluding a user-specified serial number, the row and column of that compo-
     nent in the RAID set, and whether the data (and parity) on the component
     is `clean'. If the driver determines that the labels are very inconsis-
     tent with respect to each other (e.g. two or more serial numbers do not
     match) or that the component label is not consistent with its assigned
     place in the set (e.g. the component label claims the component should be
     the 3rd one a 6-disk set, but the RAID set has it as the 3rd component in
     a 5-disk set) then the device will fail to configure.  If the driver de-
     termines that exactly one component label seems to be incorrect, and the
     RAID set is being configured as a set that supports a single failure,
     then the RAID set will be allowed to configure, but the incorrectly la-
     beled component will be marked as `failed', and the RAID set will begin
     operation in degraded mode.  If all of the components are consistent
     among themselves, the RAID set will configure normally.

     The driver supports `hot spares', disks which are on-line, but are not
     actively used in an existing filesystem.  Should a disk fail, the driver
     is capable of reconstructing the failed disk onto a hot spare or back on-
     to a replacement drive.  If the components are hot swapable, the failed
     disk can then be removed, a new disk put in its place, and a copyback op-
     eration performed.  The copyback operation, as its name indicates, will
     copy the reconstructed data from the hot spare to the previously failed
     (and now replaced) disk.  Hot spares can also be hot-added using
     raidctl(8).

     If a component cannot be detected when the RAID device is configured,
     that component will be simply marked as 'failed'.

     The user-land utility for doing all raid configuration and other opera-
     tions is raidctl(8). For any of the RAID flavours which have parity data,
     raidctl(8) must be used with the -i option to re-write the data when ei-
     ther a) a new RAID device is brought up for the first time or b) after an
     un-clean shutdown of a RAID device.  By performing this on-demand recom-
     putation of all parity before doing a fsck(8) or a newfs(8) filesystem
     integrity and parity integrity can be ensured.  It bears repeating again
     that parity recomputation is required before any filesystems are created
     or used on the RAID device.  If the parity is not correct, then missing
     data cannot be correctly recovered.

     RAID levels may be combined in a hierarchical fashion.  For example, a
     RAID 0 device can be constructed out of a number of RAID 5 devices
     (which, in turn, may be constructed out of the physical disks, or of oth-
     er RAID devices).

     It is important that drives be hard-coded at their respective addresses
     (i.e. not left free-floating, where a drive with SCSI ID of 4 can end up
     as /dev/sd0c) for well-behaved functioning of the RAID device.  For nor-
     mal SCSI drives, for example, the following can be used to fix the device
     addresses:

           sd0     at scsibus0 target 0 lun ?      # SCSI disk drives
           sd1     at scsibus0 target 1 lun ?      # SCSI disk drives
           sd2     at scsibus0 target 2 lun ?      # SCSI disk drives
           sd3     at scsibus0 target 3 lun ?      # SCSI disk drives
           sd4     at scsibus0 target 4 lun ?      # SCSI disk drives
           sd5     at scsibus0 target 5 lun ?      # SCSI disk drives
           sd6     at scsibus0 target 6 lun ?      # SCSI disk drives

     See sd(4) for more information.  The rationale for fixing the device ad-
     dresses is as follows: Consider a system with three SCSI drives at SCSI
     IDs 4, 5, and 6, and which map to components /dev/sd0e, /dev/sd1e, and
     /dev/sd2e of a RAID 5 set.  If the drive with SCSI ID 5 fails, and the
     system reboots, the old /dev/sd2e will show up as /dev/sd1e.  The RAID
     driver is able to detect that component positions have changed, and will
     not allow normal configuration.  If the device addresses are hard coded,
     however, the RAID driver would detect that the middle component is un-
     available, and bring the RAID 5 set up in degraded mode.

     The first step to using the raid driver is to ensure that it is suitably
     configured in the kernel.  This is done by adding a line similar to:

           pseudo-device   raid   4       # RAIDframe disk device

     to the kernel configuration file.  The `count' argument (`4', in this
     case), specifies the number of RAIDframe drivers to configure.  At the
     time of this writing, 4 is the MAXIMUM of raid devices which are support-
     ed.  This will change as soon as kernel threads are available.

     In all cases the `raw' partitions of the disks must not be combined.
     Rather, each component partition should be offset by at least one cylin-
     der from the beginning of that component disk.  This ensures that the
     disklabels for the component disks do not conflict with the disklabel for
     the raid device.  As well, all component partitions must be of the type
     FS_BSDFFS.

     A more detailed treatment of actually using a raid device is found in
     raidctl(8). It is highly recommended that the steps to reconstruct, copy-
     back, and re-compute parity are well understood by the system administra-
     tor(s) before a component failure.  Doing the wrong thing when a compo-
     nent fails may result in data loss.

WARNINGS
     Certain RAID levels (1, 4, 5, 6, and others) can protect against some da-
     ta loss due to component failure.  However the loss of two components of
     a RAID 4 or 5 system, or the loss of a single component of a RAID 0 sys-
     tem, will result in the entire filesystems on that RAID device being
     lost.  RAID is not a substitute for good backup practices.

     Recomputation of parity must be performed whenever there is a chance that
     it may have been compromised.  This includes after system crashes, or be-
     fore a RAID device has been used for the first time.  Failure to keep
     parity correct will be catastrophic should a component ever fail -- it is
     better to use RAID 0 and get the additional space and speed, than it is
     to use parity, but not keep the parity correct.  At least with RAID 0
     there is no perception of increased data security.

FILES
     /dev/{,r}raid*  raid device special files.

SEE ALSO
     sd(4), MAKEDEV(8), config(8), fsck(8), mount(8), newfs(8), raidctl(8)

HISTORY
     The raid driver in OpenBSD is a port of RAIDframe, a framework for rapid
     prototyping of RAID structures developed by the folks at the Parallel Da-
     ta Laboratory at Carnegie Mellon University (CMU).  RAIDframe, as origi-
     nally distributed by CMU, provides a RAID simulator for a number of dif-
     ferent architectures, and a user-level device driver and a kernel device
     driver for Digital Unix.  The raid driver is a kernelized version of
     RAIDframe v1.1.

     A more complete description of the internals and functionality of RAID-
     frame is found in the paper "RAIDframe: A Rapid Prototyping Tool for RAID
     Systems", by William V.  Courtright II, Garth Gibson, Mark Holland, LeAnn
     Neal Reilly, and Jim Zelenka, and published by the Parallel Data Labora-
     tory of Carnegie Mellon University.  The raid driver first appeared in
     NetBSD 1.4 from where it was ported to OpenBSD 2.5.

COPYRIGHT
     The RAIDframe Copyright is as follows:

     Copyright (c) 1994-1996 Carnegie-Mellon University.
     All rights reserved.

     Permission to use, copy, modify and distribute this software and
     its documentation is hereby granted, provided that both the copyright
     notice and this permission notice appear in all copies of the
     software, derivative works or modified versions, and any portions
     thereof, and that both notices appear in supporting documentation.

     CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
     CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND
     FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.

     Carnegie Mellon requests users of this software to return to

      Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
      School of Computer Science
      Carnegie Mellon University
      Pittsburgh PA 15213-3890

     any improvements or extensions that they make and grant Carnegie the
     rights to redistribute these changes.

OpenBSD 3.0                    November 9, 1998                              3
