1.\" 2.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 3.\" All rights reserved. 4.\" 5.\" This code is derived from software contributed to The NetBSD Foundation 6.\" by Greg Oster 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the NetBSD 19.\" Foundation, Inc. and its contributors. 20.\" 4. Neither the name of The NetBSD Foundation nor the names of its 21.\" contributors may be used to endorse or promote products derived 22.\" from this software without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 25.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 26.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 27.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 28.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34.\" POSSIBILITY OF SUCH DAMAGE. 35.\" 36.\" 37.\" Copyright (c) 1995 Carnegie-Mellon University. 38.\" All rights reserved. 39.\" 40.\" Author: Mark Holland 41.\" 42.\" Permission to use, copy, modify and distribute this software and 43.\" its documentation is hereby granted, provided that both the copyright 44.\" notice and this permission notice appear in all copies of the 45.\" software, derivative works or modified versions, and any portions 46.\" thereof, and that both notices appear in supporting documentation. 47.\" 48.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" 49.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND 50.\" FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. 51.\" 52.\" Carnegie Mellon requests users of this software to return to 53.\" 54.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU 55.\" School of Computer Science 56.\" Carnegie Mellon University 57.\" Pittsburgh PA 15213-3890 58.\" 59.\" any improvements or extensions that they make and grant Carnegie the 60.\" rights to redistribute these changes. 61.\" 62.Dd November 9, 1998 63.Dt RAID 4 64.Os NetBSD 65.Sh NAME 66.Nm raid 67.Nd RAIDframe Disk Driver 68.Sh SYNOPSIS 69.Cd "pseudo-device raid" Op Ar count 70.Sh DESCRIPTION 71The 72.Nm 73driver provides RAID 0, 1, 4, and 5 (and more!) capabilities to NetBSD. This 74document assumes that the reader has at least some familiarity with RAID 75and RAID concepts. The reader is also assumed to know how to configure 76disks and pseudo-devices into kernels, how to generate kernels, and how 77to partition disks. 78.Pp 79RAIDframe provides a number of different RAID levels including: 80.Bl -tag -width indent 81.It RAID 0 82provides simple data striping across the components. 83.It RAID 1 84provides mirroring. 85.It RAID 4 86provides data striping across the components, with parity 87stored on a dedicated drive (in this case, the last component). 88.It RAID 5 89provides data striping across the components, with parity 90distributed across all the components. 91.El 92.Pp 93There are a wide variety of other RAID levels supported by RAIDframe, 94including Even-Odd parity, RAID level 5 with rotated sparing, Chained 95declustering, and Interleaved declustering. The reader is referred 96to the RAIDframe documentation mentioned in the 97.Sx HISTORY 98section for more detail on these various RAID configurations. 99.Pp 100Depending on the parity level configured, the device driver can 101support the failure of component drives. The number of failures 102allowed depends on the parity level selected. If the driver is able 103to handle drive failures, and a drive does fail, then the system is 104operating in "degraded mode". In this mode, all missing data must be 105reconstructed from the data and parity present on the other 106components. This results in much slower data accesses, but 107does mean that a failure need not bring the system to a complete halt. 108.Pp 109The driver supports 110.Sq hot spares , 111disks which are on-line, but are not 112actively used in an existing filesystem. Should a disk fail, the 113driver is capable of reconstructing the failed disk onto a hot spare. 114If the components are hot swapable, the failed disk can then be 115removed, a new disk put in it's place, and a copyback operation 116performed. The copyback operation, as it's name indicates, will copy 117the reconstructed data from the hot spare to the previously failed 118(and now replaced) disk. 119.Pp 120If a component cannot be detected when the RAID device is configured, 121that component will be simply marked as 'failed'. 122.Pp 123The user-land utility for doing all 124.Nm 125configuration and other operations 126is 127.Xr raidctl 8 . 128For any of the RAID flavours which have parity data, 129.Xr raidctl 8 130must be used with the 131.Fl r 132option to re-write the data when either a) a new RAID device is 133brought up for the first time or b) after an un-clean shutdown of a 134RAID device. By performing this on-demand recomputation of all parity 135before doing a 136.Xr fsck 8 137or a 138.Xr newfs 8 139filesystem integrity and parity integrity can be ensured. It bears 140repeating again that parity recomputation is 141.Ar required 142before any filesystems are created or used on the RAID device. If the 143parity is not correct, then missing data cannot be correctly recovered. 144.Pp 145RAID levels may be combined in a hierarchical fashion. For example, a RAID 0 146device can be constructed out of a number of RAID 5 devices (which, in turn, 147may be constructed out of the physical disks, or of other RAID devices). 148.Pp 149At the time of this writing, it is 150.Ar imperative 151that drives be 152.Sq nailed down 153at their respective addresses (i.e. not left free-floating, where a 154drive with SCSI ID of 4 can end up as /dev/sd0c). Consider a system 155with three SCSI drives at SCSI ID's 4, 5, and 6, and which map to 156components /dev/sd0e, /dev/sd1e, and /dev/sd2e. If the drive with 157SCSI ID 5 fails, 158and the system reboots, the old /dev/sd2e will show up as /dev/sd1e. 159If the RAID driver is automatically configured, it will only detect 160that /dev/sd2e has failed, and will not notice that /dev/sd2e has 161actually become /dev/sd1e. Hopefully this will change within a few 162days of this writing with the addition of MD5 checksums to each of the 163components. 164.Pp 165The first step to using the 166.Nm 167driver is to ensure that it is suitably configured in the kernel. This is 168done by adding a line similar to: 169.Bd -unfilled -offset indent 170pseudo-device raid 4 # RAIDframe disk device 171.Ed 172.Pp 173to the kernel configuration file. The 174.Sq count 175argument ( 176.Sq 4 , 177in this case), specifies the number of RAIDframe drivers to configure. 178At the time of this writing, 4 is the MAXIMUM of 179.Nm 180devices which are supported. This will change as soon as kernel threads 181are available. 182.Pp 183In all cases the 184.Sq raw 185partitions of the disks 186.Pa must not 187be combined. Rather, each component parition should be offset by at least one 188cylinder from the beginning of that component disk. This ensures that 189the disklabels for the component disks do not conflict with the 190disklabel for the 191.Nm 192device. 193As well, all component paritions must be of the type 194.Dv FS_BSDFFS . 195.Pp 196A more detailed treatment of actually using a 197.Nm 198device is found in 199.Xr raidctl 8 . 200It is highly recommended that the steps to reconstruct, copyback, and 201re-compute parity are well understood by the system administrator(s) 202.Ar before 203a component failure. Doing the wrong thing when a component fails may 204result in data loss. 205.Pp 206.Sh WARNINGS 207Certain RAID levels (1, 4, 5, 6, and others) can protect against some 208data loss due to component failure. However the loss of two 209components of a RAID 4 or 5 system, or the loss of a single component 210of a RAID 0 system, will result in the entire filesystems on that RAID 211device being lost. 212RAID is 213.Ar NOT 214a substitute for good backup practices. 215.Pp 216Recomputation of parity 217.Ar MUST 218be performed whenever there is a chance that it may have been 219compromised. This includes after system crashes, or before a RAID 220device has been used for the first time. Failure to keep parity 221correct will be catastrophic should a component ever fail -- it is 222better to use RAID 0 and get the additional space and speed, than it 223is to use parity, but not keep the parity correct. At least with RAID 2240 there is no perception of increased data security. 225.Pp 226.Sh FILES 227.Bl -tag -width /dev/XXrXraidX -compact 228.It Pa /dev/{,r}raid* 229.Nm 230device special files. 231.El 232.Pp 233.Sh SEE ALSO 234.Xr MAKEDEV 8 , 235.Xr raidctl 8 , 236.Xr config 8 , 237.Xr fsck 8 , 238.Xr mount 8 , 239.Xr newfs 8 240.Sh HISTORY 241The 242.Nm 243driver in 244.Nx 245is a port of RAIDframe, a framework for rapid prototyping of RAID 246structures developed by the folks at the Parallel Data Laboratory at 247Carnegie Mellon University (CMU). RAIDframe, as originally distributed 248by CMU, provides a RAID simulator for a number of different 249architectures, and a user-level device driver and a kernel device 250driver for for Digital Unix. The 251.Nm 252driver is a kernelized version of RAIDframe v1.1. 253.Pp 254A more complete description of the internals and functionality of 255RAIDframe is found in the paper "RAIDframe: A Rapid Prototyping Tool 256for RAID Systems", by William V. Courtright II, Garth Gibson, Mark 257Holland, LeAnn Neal Reilly, and Jim Zelenka, and published by the 258Parallel Data Laboratory of Carnegie Mellon University. 259The 260.Nm 261driver first appeared in 262.Nx 1.4 . 263.Sh COPYRIGHT 264.Bd -unfilled 265 266The RAIDframe Copyright is as follows: 267 268Copyright (c) 1994-1996 Carnegie-Mellon University. 269All rights reserved. 270 271Permission to use, copy, modify and distribute this software and 272its documentation is hereby granted, provided that both the copyright 273notice and this permission notice appear in all copies of the 274software, derivative works or modified versions, and any portions 275thereof, and that both notices appear in supporting documentation. 276 277CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" 278CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND 279FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. 280 281Carnegie Mellon requests users of this software to return to 282 283 Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU 284 School of Computer Science 285 Carnegie Mellon University 286 Pittsburgh PA 15213-3890 287 288any improvements or extensions that they make and grant Carnegie the 289rights to redistribute these changes. 290 291.Ed 292