xref: /freebsd/lib/geom/raid3/graid3.8 (revision 95ee2897e98f5d444f26ed2334cc7c439f9c16c6)
1.\" Copyright (c) 2004-2005 Pawel Jakub Dawidek <pjd@FreeBSD.org>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd January 15, 2012
28.Dt GRAID3 8
29.Os
30.Sh NAME
31.Nm graid3
32.Nd "control utility for RAID3 devices"
33.Sh SYNOPSIS
34.Nm
35.Cm label
36.Op Fl Fhnrvw
37.Op Fl s Ar blocksize
38.Ar name
39.Ar prov prov prov ...
40.Nm
41.Cm clear
42.Op Fl v
43.Ar prov ...
44.Nm
45.Cm configure
46.Op Fl adfFhnrRvwW
47.Ar name
48.Nm
49.Cm rebuild
50.Op Fl v
51.Ar name
52.Ar prov
53.Nm
54.Cm insert
55.Op Fl hv
56.Op Fl n Ar number
57.Ar name
58.Ar prov
59.Nm
60.Cm remove
61.Op Fl v
62.Fl n Ar number
63.Ar name
64.Nm
65.Cm stop
66.Op Fl fv
67.Ar name ...
68.Nm
69.Cm list
70.Nm
71.Cm status
72.Nm
73.Cm load
74.Nm
75.Cm unload
76.Sh DESCRIPTION
77The
78.Nm
79utility is used for RAID3 array configuration.
80After a device is created, all components are detected and configured
81automatically.
82All operations such as failure detection, stale component detection, rebuild
83of stale components, etc.\& are also done automatically.
84The
85.Nm
86utility uses on-disk metadata (the provider's last sector) to store all needed
87information.
88.Pp
89The first argument to
90.Nm
91indicates an action to be performed:
92.Bl -tag -width ".Cm configure"
93.It Cm label
94Create a RAID3 device.
95The last given component will contain parity data, whilst the others
96will all contain regular data.
97The number of components must be equal to 3, 5, 9, 17, etc.\& (2^n + 1).
98.Pp
99Additional options include:
100.Bl -tag -width ".Fl h"
101.It Fl F
102Do not synchronize after a power failure or system crash.
103Assumes device is in consistent state.
104.It Fl h
105Hardcode providers' names in metadata.
106.It Fl n
107Turn off autosynchronization of stale components.
108.It Fl r
109Use parity component for reading in round-robin fashion.
110Without this option the parity component is not used at all for reading operations
111when the device is in a complete state.
112With this option specified random I/O read operations are even 40% faster,
113but sequential reads are slower.
114One cannot use this option if the
115.Fl w
116option is also specified.
117.It Fl s
118Manually specify array block size. Block size will be set equal to least
119common multiple of all component's sector sizes and specified value.
120Note that array sector size calculated as multiple of block size and number
121of regular data components. Big values may decrease performance and compatibility,
122as all I/O requests have to be multiple of sector size.
123.It Fl w
124Use verify reading feature.
125When reading from a device in a complete state, also read data from the parity component
126and verify the data by comparing XORed regular data with parity data.
127If verification fails, an
128.Er EIO
129error is returned and the value of the
130.Va kern.geom.raid3.stat.parity_mismatch
131sysctl is increased.
132One cannot use this option if the
133.Fl r
134option is also specified.
135.El
136.It Cm clear
137Clear metadata on the given providers.
138.It Cm configure
139Configure the given device.
140.Pp
141Additional options include:
142.Bl -tag -width ".Fl a"
143.It Fl a
144Turn on autosynchronization of stale components.
145.It Fl d
146Do not hardcode providers' names in metadata.
147.It Fl f
148Synchronize device after a power failure or system crash.
149.It Fl F
150Do not synchronize after a power failure or system crash.
151Assumes device is in consistent state.
152.It Fl h
153Hardcode providers' names in metadata.
154.It Fl n
155Turn off autosynchronization of stale components.
156.It Fl r
157Turn on round-robin reading.
158.It Fl R
159Turn off round-robin reading.
160.It Fl w
161Turn on verify reading.
162.It Fl W
163Turn off verify reading.
164.El
165.It Cm rebuild
166Rebuild the given component forcibly.
167If autosynchronization was not turned off for the given device, this command
168should be unnecessary.
169.It Cm insert
170Add the given component to the existing array, if one of the components was
171removed previously with the
172.Cm remove
173command or if one component is missing and will not be connected again.
174If no number is given, new component will be added instead of first missed
175component.
176.Pp
177Additional options include:
178.Bl -tag -width ".Fl h"
179.It Fl h
180Hardcode providers' names in metadata.
181.El
182.It Cm remove
183Remove the given component from the given array and clear metadata on it.
184.It Cm stop
185Stop the given arrays.
186.Pp
187Additional options include:
188.Bl -tag -width ".Fl f"
189.It Fl f
190Stop the given array even if it is opened.
191.El
192.It Cm list
193See
194.Xr geom 8 .
195.It Cm status
196See
197.Xr geom 8 .
198.It Cm load
199See
200.Xr geom 8 .
201.It Cm unload
202See
203.Xr geom 8 .
204.El
205.Pp
206Additional options include:
207.Bl -tag -width ".Fl v"
208.It Fl v
209Be more verbose.
210.El
211.Sh EXIT STATUS
212Exit status is 0 on success, and 1 if the command fails.
213.Sh EXAMPLES
214Use 3 disks to setup a RAID3 array (with the round-robin reading feature).
215Create a file system, mount it, then unmount it and stop device:
216.Bd -literal -offset indent
217graid3 label -v -r data da0 da1 da2
218newfs /dev/raid3/data
219mount /dev/raid3/data /mnt
220\&...
221umount /mnt
222graid3 stop data
223graid3 unload
224.Ed
225.Pp
226Create a RAID3 array, but do not use the automatic synchronization feature.
227Rebuild parity component:
228.Bd -literal -offset indent
229graid3 label -n data da0 da1 da2
230graid3 rebuild data da2
231.Ed
232.Pp
233Replace one data disk with a brand new one:
234.Bd -literal -offset indent
235graid3 remove -n 0 data
236graid3 insert -n 0 data da5
237.Ed
238.Sh SEE ALSO
239.Xr geom 4 ,
240.Xr geom 8 ,
241.Xr gvinum 8 ,
242.Xr mount 8 ,
243.Xr newfs 8 ,
244.Xr umount 8
245.Sh HISTORY
246The
247.Nm
248utility appeared in
249.Fx 5.3 .
250.Sh AUTHORS
251.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org
252.Sh BUGS
253There should be a section with an implementation description.
254.Pp
255Documentation for sysctls
256.Va kern.geom.raid3.*
257is missing.
258