xref: /freebsd/share/man/man4/ccd.4 (revision 066ef2aec187ae93a9df01d25fa8e47d67ff972b)
1edc3aeecSSatoshi Asami.\"	$NetBSD: ccd.4,v 1.5 1995/10/09 06:09:09 thorpej Exp $
2edc3aeecSSatoshi Asami.\"
3edc3aeecSSatoshi Asami.\" Copyright (c) 1994 Jason Downs.
4edc3aeecSSatoshi Asami.\" Copyright (c) 1994, 1995 Jason R. Thorpe.
5edc3aeecSSatoshi Asami.\" All rights reserved.
6edc3aeecSSatoshi Asami.\"
7edc3aeecSSatoshi Asami.\" Redistribution and use in source and binary forms, with or without
8edc3aeecSSatoshi Asami.\" modification, are permitted provided that the following conditions
9edc3aeecSSatoshi Asami.\" are met:
10edc3aeecSSatoshi Asami.\" 1. Redistributions of source code must retain the above copyright
11edc3aeecSSatoshi Asami.\"    notice, this list of conditions and the following disclaimer.
12edc3aeecSSatoshi Asami.\" 2. Redistributions in binary form must reproduce the above copyright
13edc3aeecSSatoshi Asami.\"    notice, this list of conditions and the following disclaimer in the
14edc3aeecSSatoshi Asami.\"    documentation and/or other materials provided with the distribution.
15edc3aeecSSatoshi Asami.\" 3. All advertising materials mentioning features or use of this software
16edc3aeecSSatoshi Asami.\"    must display the following acknowledgement:
17edc3aeecSSatoshi Asami.\"	This product includes software developed for the NetBSD Project
18edc3aeecSSatoshi Asami.\"	by Jason Downs and Jason R. Thorpe.
19edc3aeecSSatoshi Asami.\" 4. Neither the name of the author nor the names of its contributors
20edc3aeecSSatoshi Asami.\"    may be used to endorse or promote products derived from this software
21edc3aeecSSatoshi Asami.\"    without specific prior written permission.
22edc3aeecSSatoshi Asami.\"
23edc3aeecSSatoshi Asami.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
24edc3aeecSSatoshi Asami.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
25edc3aeecSSatoshi Asami.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
26edc3aeecSSatoshi Asami.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
27edc3aeecSSatoshi Asami.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
28edc3aeecSSatoshi Asami.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
29edc3aeecSSatoshi Asami.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
30edc3aeecSSatoshi Asami.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
31edc3aeecSSatoshi Asami.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32edc3aeecSSatoshi Asami.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33edc3aeecSSatoshi Asami.\" SUCH DAMAGE.
34edc3aeecSSatoshi Asami.\"
3527bd6c32SJohn Baldwin.Dd January 23, 2025
36edc3aeecSSatoshi Asami.Dt CCD 4
373d45e180SRuslan Ermilov.Os
38edc3aeecSSatoshi Asami.Sh NAME
39edc3aeecSSatoshi Asami.Nm ccd
40eb083802SRuslan Ermilov.Nd Concatenated Disk driver
41edc3aeecSSatoshi Asami.Sh SYNOPSIS
42efacde1bSBrooks Davis.Cd "device ccd"
43edc3aeecSSatoshi Asami.Sh DESCRIPTION
44edc3aeecSSatoshi AsamiThe
45edc3aeecSSatoshi Asami.Nm
46edc3aeecSSatoshi Asamidriver provides the capability of combining one or more disks/partitions
47edc3aeecSSatoshi Asamiinto one virtual disk.
48edc3aeecSSatoshi Asami.Pp
49328b06b9SRuslan ErmilovThis document assumes that you are familiar with how to generate kernels,
50ec09ef4fSJens Schweikhardthow to properly configure disks and devices in a kernel
51edc3aeecSSatoshi Asamiconfiguration file, and how to partition disks.
52edc3aeecSSatoshi Asami.Pp
53328b06b9SRuslan ErmilovIn order to compile in support for the
54328b06b9SRuslan Ermilov.Nm ,
55328b06b9SRuslan Ermilovyou must add a line similar
56edc3aeecSSatoshi Asamito the following to your kernel configuration file:
57edc3aeecSSatoshi Asami.Pp
58328b06b9SRuslan Ermilov.Dl "device	ccd		# concatenated disk devices"
59328b06b9SRuslan Ermilov.Pp
60328b06b9SRuslan ErmilovAs of the
61e55373e2SMatthew Dillon.Fx 3.0
62e55373e2SMatthew Dillonrelease, you do not need to
63328b06b9SRuslan Ermilovconfigure your kernel with
64328b06b9SRuslan Ermilov.Nm
65328b06b9SRuslan Ermilovbut may instead use it as a kernel loadable
66328b06b9SRuslan Ermilovmodule.
67328b06b9SRuslan ErmilovSimply running
68328b06b9SRuslan Ermilov.Xr ccdconfig 8
692d2409d6SMatthew Dillonwill load the module into the kernel.
70edc3aeecSSatoshi Asami.Pp
71edc3aeecSSatoshi AsamiA
724b66483fSRuslan Ermilov.Nm
73328b06b9SRuslan Ermilovmay be either serially concatenated or interleaved.
74328b06b9SRuslan ErmilovTo serially
75bee9cbfdSSatoshi Asamiconcatenate the partitions, specify the interleave factor of 0.
762d2409d6SMatthew DillonNote that mirroring may not be used with an interleave factor of 0.
77edc3aeecSSatoshi Asami.Pp
78edc3aeecSSatoshi AsamiThere is a run-time utility that is used for configuring
794b66483fSRuslan Ermilov.Nm Ns s .
80edc3aeecSSatoshi AsamiSee
81edc3aeecSSatoshi Asami.Xr ccdconfig 8
82edc3aeecSSatoshi Asamifor more information.
83bee9cbfdSSatoshi Asami.Ss The Interleave Factor
84bee9cbfdSSatoshi AsamiIf a
854b66483fSRuslan Ermilov.Nm
86bee9cbfdSSatoshi Asamiis interleaved correctly, a
87bee9cbfdSSatoshi Asami.Dq striping
88bee9cbfdSSatoshi Asamieffect is achieved, which can increase sequential read/write
89328b06b9SRuslan Ermilovperformance.
90328b06b9SRuslan ErmilovThe interleave factor is expressed in units of
91328b06b9SRuslan Ermilov.Dv DEV_BSIZE
92328b06b9SRuslan Ermilov(usually 512 bytes).
93328b06b9SRuslan ErmilovFor large writes, the optimum interleave factor
94bee9cbfdSSatoshi Asamiis typically the size of a track, while for large reads, it is about a
954e86fcacSSheldon Hearnquarter of a track.
964e86fcacSSheldon Hearn(Note that this changes greatly depending on the
97328b06b9SRuslan Ermilovnumber and speed of disks.)
98328b06b9SRuslan ErmilovFor instance, with eight 7,200 RPM drives
99bee9cbfdSSatoshi Asamion two Fast-Wide SCSI buses, this translates to about 128 for writes
100328b06b9SRuslan Ermilovand 32 for reads.
101328b06b9SRuslan ErmilovA larger interleave tends to work better when the
1022d2409d6SMatthew Dillondisk is taking a multitasking load by localizing the file I/O from
103328b06b9SRuslan Ermilovany given process onto a single disk.
104328b06b9SRuslan ErmilovYou lose sequential performance when
1052d2409d6SMatthew Dillonyou do this, but sequential performance is not usually an issue with a
1062d2409d6SMatthew Dillonmultitasking load.
1072d2409d6SMatthew Dillon.Pp
1082d2409d6SMatthew DillonAn interleave factor must be specified when using a mirroring configuration,
1095203edcdSRuslan Ermiloveven when you have only two disks (i.e., the layout winds up being the same
110328b06b9SRuslan Ermilovno matter what the interleave factor).
111328b06b9SRuslan ErmilovThe interleave factor will determine
1122d2409d6SMatthew Dillonhow I/O is broken up, however, and a value 128 or greater is recommended.
1132d2409d6SMatthew Dillon.Pp
114328b06b9SRuslan Ermilov.Nm
115328b06b9SRuslan Ermilovhas an option for a parity disk, but does not currently implement it.
116bee9cbfdSSatoshi Asami.Pp
117bee9cbfdSSatoshi AsamiThe best performance is achieved if all component disks have the same
118328b06b9SRuslan Ermilovgeometry and size.
119328b06b9SRuslan ErmilovOptimum striping cannot occur with different
120bee9cbfdSSatoshi Asamidisk types.
121bee9cbfdSSatoshi Asami.Pp
122bee9cbfdSSatoshi AsamiFor random-access oriented workloads, such as news servers, a larger
123328b06b9SRuslan Ermilovinterleave factor (e.g., 65,536) is more desirable.
124328b06b9SRuslan ErmilovNote that there
125328b06b9SRuslan Ermilovis not much
1264b66483fSRuslan Ermilov.Nm
127328b06b9SRuslan Ermilovcan do to speed up applications that are seek-time limited.
128328b06b9SRuslan ErmilovLarger
129bee9cbfdSSatoshi Asamiinterleave factors will at least reduce the chance of having to seek
130bee9cbfdSSatoshi Asamitwo disk-heads to read one directory or a file.
131bee9cbfdSSatoshi Asami.Ss Disk Mirroring
132bee9cbfdSSatoshi AsamiYou can configure the
1334b66483fSRuslan Ermilov.Nm
134bee9cbfdSSatoshi Asamito
135bee9cbfdSSatoshi Asami.Dq mirror
136328b06b9SRuslan Ermilovany even number of disks.
137328b06b9SRuslan ErmilovSee
138bee9cbfdSSatoshi Asami.Xr ccdconfig 8
139328b06b9SRuslan Ermilovfor how to specify the necessary flags.
140328b06b9SRuslan ErmilovFor example, if you have a
141328b06b9SRuslan Ermilov.Nm
1422d2409d6SMatthew Dillonconfiguration specifying four disks, the first two disks will be mirrored with
143328b06b9SRuslan Ermilovthe second two disks.
144328b06b9SRuslan ErmilovA write will be run to both sides of
145328b06b9SRuslan Ermilovthe mirror.
146328b06b9SRuslan ErmilovA read will be run to either side of the mirror depending
147328b06b9SRuslan Ermilovon what the driver believes to be most optimal.
148328b06b9SRuslan ErmilovIf the read fails,
1492d2409d6SMatthew Dillonthe driver will automatically attempt to read the same sector from the
150328b06b9SRuslan Ermilovother side of the mirror.
151328b06b9SRuslan ErmilovCurrently
1524b66483fSRuslan Ermilov.Nm
153ea36a492SGiorgos Keramidasuses a dual seek zone model to optimize reads for a multi-tasking load
154074ad115SRuslan Ermilovrather than a sequential load.
1552d2409d6SMatthew Dillon.Pp
1562d2409d6SMatthew DillonIn an event of a disk
157bee9cbfdSSatoshi Asamifailure, you can use
158bee9cbfdSSatoshi Asami.Xr dd 1
159bee9cbfdSSatoshi Asamito recover the failed disk.
160bee9cbfdSSatoshi Asami.Pp
161bee9cbfdSSatoshi AsamiNote that a one-disk
1624b66483fSRuslan Ermilov.Nm
163328b06b9SRuslan Ermilovis not the same as the original partition.
164328b06b9SRuslan ErmilovIn particular, this means
165bee9cbfdSSatoshi Asamiif you have a file system on a two-disk mirrored
1664b66483fSRuslan Ermilov.Nm
167bee9cbfdSSatoshi Asamiand one of the disks fail, you cannot mount and use the remaining
168bee9cbfdSSatoshi Asamipartition as itself; you have to configure it as a one-disk
1694b66483fSRuslan Ermilov.Nm .
1702d2409d6SMatthew DillonYou cannot replace a disk in a mirrored
1714b66483fSRuslan Ermilov.Nm
1722d2409d6SMatthew Dillonpartition without first backing up the partition, then replacing the disk,
1732d2409d6SMatthew Dillonthen restoring the partition.
174d5bd01d2SRuslan Ermilov.Ss Linux Compatibility
175d5bd01d2SRuslan ErmilovThe
176d5bd01d2SRuslan Ermilov.Tn Linux
177d5bd01d2SRuslan Ermilovcompatibility mode does not try to read the label that
178d5bd01d2SRuslan Ermilov.Tn Linux Ns '
179d5bd01d2SRuslan Ermilov.Xr md 4
180d5bd01d2SRuslan Ermilovdriver leaves on the raw devices.
181d5bd01d2SRuslan ErmilovYou will have to give the order
182d5bd01d2SRuslan Ermilovof devices and the interleave factor on your own.
183d5bd01d2SRuslan ErmilovWhen in
184d5bd01d2SRuslan Ermilov.Tn Linux
185d5bd01d2SRuslan Ermilovcompatibility mode,
186d5bd01d2SRuslan Ermilov.Nm
187d5bd01d2SRuslan Ermilovwill convert the interleave factor from
188d5bd01d2SRuslan Ermilov.Tn Linux
189d5bd01d2SRuslan Ermilovterminology.
190d5bd01d2SRuslan ErmilovThat means you give the same interleave factor that you
191d5bd01d2SRuslan Ermilovgave as chunk size in
192d5bd01d2SRuslan Ermilov.Tn Linux .
1933f4f4a14SMartin Cracauer.Pp
194d5bd01d2SRuslan ErmilovIf you have a
195d5bd01d2SRuslan Ermilov.Tn Linux
196d5bd01d2SRuslan Ermilov.Xr md 4
197d5bd01d2SRuslan Ermilovdevice in
198d5bd01d2SRuslan Ermilov.Dq legacy
199d5bd01d2SRuslan Ermilovmode, do not use the
200d5bd01d2SRuslan Ermilov.Dv CCDF_LINUX
201d5bd01d2SRuslan Ermilovflag in
2023f4f4a14SMartin Cracauer.Xr ccdconfig 8 .
203d5bd01d2SRuslan ErmilovUse the
204d5bd01d2SRuslan Ermilov.Dv CCDF_NO_OFFSET
205d5bd01d2SRuslan Ermilovflag instead.
206d5bd01d2SRuslan ErmilovIn that case you have to convert
207d5bd01d2SRuslan Ermilovthe interleave factor on your own, usually it is
208d5bd01d2SRuslan Ermilov.Tn Linux Ns '
209d5bd01d2SRuslan Ermilovchunk size multiplied by two.
2103f4f4a14SMartin Cracauer.Pp
211d5bd01d2SRuslan ErmilovUsing a
212d5bd01d2SRuslan Ermilov.Tn Linux
213d5bd01d2SRuslan ErmilovRAID this way is potentially dangerous and can destroy
214d5bd01d2SRuslan Ermilovthe data in there.
215d5bd01d2SRuslan ErmilovSince
216d5bd01d2SRuslan Ermilov.Fx
217d5bd01d2SRuslan Ermilovdoes not read the label used by
218d5bd01d2SRuslan Ermilov.Tn Linux ,
219d5bd01d2SRuslan Ermilovchanges in
220d5bd01d2SRuslan Ermilov.Tn Linux
221d5bd01d2SRuslan Ermilovmight invalidate the compatibility layer.
2223f4f4a14SMartin Cracauer.Pp
2233f4f4a14SMartin CracauerHowever, using this is reasonably safe if you test the compatibility
224d5bd01d2SRuslan Ermilovbefore mounting a RAID read-write for the first time.
225d5bd01d2SRuslan ErmilovJust using
226d5bd01d2SRuslan Ermilov.Xr ccdconfig 8
227d5bd01d2SRuslan Ermilovwithout mounting does not write anything to the
228d5bd01d2SRuslan Ermilov.Tn Linux
229d5bd01d2SRuslan ErmilovRAID.
230d5bd01d2SRuslan ErmilovThen you do a
231*066ef2aeSAlexander Ziaee.Nm fsck.ext2fs Pq Pa ports/filesystems/e2fsprogs
232d5bd01d2SRuslan Ermilovon the
233d5bd01d2SRuslan Ermilov.Nm
234d5bd01d2SRuslan Ermilovdevice using the
235d5bd01d2SRuslan Ermilov.Fl n
236d5bd01d2SRuslan Ermilovflag.
237d5bd01d2SRuslan ErmilovYou can mount the file system read-only to check files in there.
238d5bd01d2SRuslan ErmilovIf all this works, it is unlikely that there is a problem with
239d5bd01d2SRuslan Ermilov.Nm .
240d5bd01d2SRuslan ErmilovKeep in mind that even when the
241d5bd01d2SRuslan Ermilov.Tn Linux
242d5bd01d2SRuslan Ermilovcompatibility mode in
243d5bd01d2SRuslan Ermilov.Nm
244d5bd01d2SRuslan Ermilovis working correctly, bugs in
245d5bd01d2SRuslan Ermilov.Fx Ap s
246d5bd01d2SRuslan Ermilov.Nm ex2fs
247d5bd01d2SRuslan Ermilovimplementation would still destroy
2483f4f4a14SMartin Cracaueryour data.
249edc3aeecSSatoshi Asami.Sh WARNINGS
250edc3aeecSSatoshi AsamiIf just one (or more) of the disks in a
2514b66483fSRuslan Ermilov.Nm
252edc3aeecSSatoshi Asamifails, the entire
253bee9cbfdSSatoshi Asamifile system will be lost unless you are mirroring the disks.
2542d2409d6SMatthew Dillon.Pp
2552d2409d6SMatthew DillonIf one of the disks in a mirror is lost, you should still
256328b06b9SRuslan Ermilovbe able to back up your data.
257328b06b9SRuslan ErmilovIf a write error occurs, however, data
258328b06b9SRuslan Ermilovread from that sector may be non-deterministic.
259328b06b9SRuslan ErmilovIt may return the data
260328b06b9SRuslan Ermilovprior to the write or it may return the data that was written.
261328b06b9SRuslan ErmilovWhen a
2622d2409d6SMatthew Dillonwrite error occurs, you should recover and regenerate the data as soon
2632d2409d6SMatthew Dillonas possible.
2642d2409d6SMatthew Dillon.Pp
2652d2409d6SMatthew DillonChanging the interleave or other parameters for a
2664b66483fSRuslan Ermilov.Nm
2672d2409d6SMatthew Dillondisk usually destroys whatever data previously existed on that disk.
268edc3aeecSSatoshi Asami.Sh FILES
2693301500cSRuslan Ermilov.Bl -tag -width ".Pa /dev/ccd*"
2703301500cSRuslan Ermilov.It Pa /dev/ccd*
2713301500cSRuslan Ermilov.Nm
2723301500cSRuslan Ermilovdevice special files
2733301500cSRuslan Ermilov.El
274edc3aeecSSatoshi Asami.Sh SEE ALSO
275bee9cbfdSSatoshi Asami.Xr dd 1 ,
276edc3aeecSSatoshi Asami.Xr ccdconfig 8 ,
277edc3aeecSSatoshi Asami.Xr config 8 ,
278286fe46cSSatoshi Asami.Xr disklabel 8 ,
279edc3aeecSSatoshi Asami.Xr fsck 8 ,
280edc3aeecSSatoshi Asami.Xr mount 8 ,
281d1cd5e7cSJoel Dahl.Xr newfs 8
2829cbda590SRuslan Ermilov.Sh HISTORY
2839cbda590SRuslan ErmilovThe concatenated disk driver was originally written at the University of
2849cbda590SRuslan ErmilovUtah.
285