xref: /freebsd/lib/geom/mirror/gmirror.8 (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
1.\" Copyright (c) 2004-2009 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 October 5, 2022
28.Dt GMIRROR 8
29.Os
30.Sh NAME
31.Nm gmirror
32.Nd "control utility for mirrored devices"
33.Sh SYNOPSIS
34To compile GEOM_MIRROR into your kernel, add the following lines to your
35kernel configuration file:
36.Bd -ragged -offset indent
37.Cd "options GEOM_MIRROR"
38.Ed
39.Pp
40Alternatively, to load the GEOM_MIRROR module at boot time, add the following
41line to your
42.Xr loader.conf 5 :
43.Bd -literal -offset indent
44geom_mirror_load="YES"
45.Ed
46.Pp
47.No Usage of the Nm
48utility:
49.Pp
50.Nm
51.Cm label
52.Op Fl Fhnv
53.Op Fl b Ar balance
54.Op Fl s Ar slice
55.Ar name
56.Ar prov ...
57.Nm
58.Cm clear
59.Op Fl v
60.Ar prov ...
61.Nm
62.Cm create
63.Op Fl Fnv
64.Op Fl b Ar balance
65.Op Fl s Ar slice
66.Ar name
67.Ar prov ...
68.Nm
69.Cm configure
70.Op Fl adfFhnv
71.Op Fl b Ar balance
72.Op Fl s Ar slice
73.Ar name
74.Nm
75.Cm configure
76.Op Fl v
77.Fl p Ar priority
78.Ar name
79.Ar prov
80.Nm
81.Cm rebuild
82.Op Fl v
83.Ar name
84.Ar prov ...
85.Nm
86.Cm resize
87.Op Fl v
88.Op Fl s Ar size
89.Ar name
90.Nm
91.Cm insert
92.Op Fl hiv
93.Op Fl p Ar priority
94.Ar name
95.Ar prov ...
96.Nm
97.Cm remove
98.Op Fl v
99.Ar name
100.Ar prov ...
101.Nm
102.Cm activate
103.Op Fl v
104.Ar name
105.Ar prov ...
106.Nm
107.Cm deactivate
108.Op Fl v
109.Ar name
110.Ar prov ...
111.Nm
112.Cm destroy
113.Op Fl fv
114.Ar name ...
115.Nm
116.Cm forget
117.Op Fl v
118.Ar name ...
119.Nm
120.Cm stop
121.Op Fl fv
122.Ar name ...
123.Nm
124.Cm dump
125.Ar prov ...
126.Nm
127.Cm list
128.Nm
129.Cm status
130.Nm
131.Cm load
132.Nm
133.Cm unload
134.Sh DESCRIPTION
135The
136.Nm
137utility is used for mirror (RAID1) configurations.
138After a mirror's creation, all components are detected and configured
139automatically.
140All operations like failure detection, stale component detection, rebuild
141of stale components, etc.\& are also done automatically.
142The
143.Nm
144utility uses on-disk metadata (stored in the provider's last sector) to store all needed
145information.
146Since the last sector is used for this purpose, it is possible to place a root
147file system on a mirror.
148.Pp
149The first argument to
150.Nm
151indicates an action to be performed:
152.Bl -tag -width ".Cm deactivate"
153.It Cm label
154Create a mirror.
155The order of components is important, because a component's priority is based on its position
156(starting from 0 to 255).
157The component with the biggest priority is used by the
158.Cm prefer
159balance algorithm
160and is also used as a master component when resynchronization is needed,
161e.g.\& after a power failure when the device was open for writing.
162.Pp
163Additional options include:
164.Bl -tag -width ".Fl b Ar balance"
165.It Fl b Ar balance
166Specifies balance algorithm to use, one of:
167.Bl -tag -width ".Cm round-robin"
168.It Cm load
169Read from the component with the lowest load.
170This is the default balance algorithm.
171.It Cm prefer
172Read from the component with the biggest priority.
173.It Cm round-robin
174Use round-robin algorithm when choosing component to read.
175.It Cm split
176Split read requests, which are bigger than or equal to slice size on N pieces,
177where N is the number of active components.
178.El
179.It Fl F
180Do not synchronize after a power failure or system crash.
181Assumes device is in consistent state.
182.It Fl h
183Hardcode providers' names in metadata.
184.It Fl n
185Turn off autosynchronization of stale components.
186.It Fl s Ar slice
187When using the
188.Cm split
189balance algorithm and an I/O READ request is bigger than or equal to this value,
190the I/O request will be split into N pieces, where N is the number of active
191components.
192Defaults to 4096 bytes.
193.El
194.It Cm clear
195Clear metadata on the given providers.
196.It Cm create
197Similar to
198.Cm label ,
199but creates mirror without storing on-disk metadata in last sector.
200This special "manual" operation mode assumes some external control to manage
201mirror detection after reboot, device hot-plug and other external events.
202.It Cm configure
203Configure the given device.
204.Pp
205Additional options include:
206.Bl -tag -width ".Fl p Ar priority"
207.It Fl a
208Turn on autosynchronization of stale components.
209.It Fl b Ar balance
210Specifies balance algorithm to use.
211.It Fl d
212Do not hardcode providers' names in metadata.
213.It Fl f
214Synchronize device after a power failure or system crash.
215.It Fl F
216Do not synchronize after a power failure or system crash.
217Assumes device is in consistent state.
218.It Fl h
219Hardcode providers' names in metadata.
220.It Fl n
221Turn off autosynchronization of stale components.
222.It Fl p Ar priority
223Specifies priority for the given component
224.Ar prov .
225.It Fl s Ar slice
226Specifies slice size for
227.Cm split
228balance algorithm.
229.El
230.It Cm rebuild
231Rebuild the given mirror components forcibly.
232If autosynchronization was not turned off for the given device, this command
233should be unnecessary.
234.It Cm resize
235Change the size of the given mirror.
236.Pp
237Additional options include:
238.Bl -tag -width ".Fl s Ar size"
239.It Fl s Ar size
240New size of the mirror is expressed in logical block numbers.
241This option can be omitted, then it will be automatically calculated to
242maximum available size.
243.El
244.It Cm insert
245Add the given component(s) to the existing mirror.
246.Pp
247Additional options include:
248.Bl -tag -width ".Fl p Ar priority"
249.It Fl h
250Hardcode providers' names in metadata.
251.It Fl i
252Mark component(s) as inactive immediately after insertion.
253.It Fl p Ar priority
254Specifies priority of the given component(s).
255.El
256.It Cm remove
257Remove the given component(s) from the mirror and clear metadata on it.
258.It Cm activate
259Activate the given component(s), which were marked as inactive before.
260.It Cm deactivate
261Mark the given component(s) as inactive, so it will not be automatically
262connected to the mirror.
263.It Cm destroy
264Stop the given mirror and clear metadata on all its components.
265.Pp
266Additional options include:
267.Bl -tag -width ".Fl f"
268.It Fl f
269Stop the given mirror even if it is opened.
270.El
271.It Cm forget
272Forget about components which are not connected.
273This command is useful when a disk has failed and cannot be reconnected, preventing the
274.Cm remove
275command from being used to remove it.
276.It Cm stop
277Stop the given mirror.
278.Pp
279Additional options include:
280.Bl -tag -width ".Fl f"
281.It Fl f
282Stop the given mirror even if it is opened.
283.El
284.It Cm dump
285Dump metadata stored on the given providers.
286.It Cm list
287See
288.Xr geom 8 .
289.It Cm status
290See
291.Xr geom 8 .
292.It Cm load
293See
294.Xr geom 8 .
295.It Cm unload
296See
297.Xr geom 8 .
298.El
299.Pp
300Additional options include:
301.Bl -tag -width ".Fl v"
302.It Fl v
303Be more verbose.
304.El
305.Sh EXIT STATUS
306Exit status is 0 on success, and 1 if the command fails.
307.Sh EXAMPLES
308Use 3 disks to setup a mirror.
309Choose split balance algorithm, split only
310requests which are bigger than or equal to 2kB.
311Create file system,
312mount it, then unmount it and stop device:
313.Bd -literal -offset indent
314gmirror label -v -b split -s 2048 data da0 da1 da2
315newfs /dev/mirror/data
316mount /dev/mirror/data /mnt
317\&...
318umount /mnt
319gmirror stop data
320gmirror unload
321.Ed
322.Pp
323Create a mirror on disk with valid data (note that the last sector of the disk
324will be overwritten).
325Add another disk to this mirror,
326so it will be synchronized with existing disk:
327.Bd -literal -offset indent
328gmirror label -v -b round-robin data da0
329gmirror insert data da1
330.Ed
331.Pp
332Create a mirror, but do not use automatic synchronization feature.
333Add another disk and rebuild it:
334.Bd -literal -offset indent
335gmirror label -v -n -b load data da0 da1
336gmirror insert data da2
337gmirror rebuild data da2
338.Ed
339.Pp
340One disk failed.
341Replace it with a brand new one:
342.Bd -literal -offset indent
343gmirror forget data
344gmirror insert data da1
345.Ed
346.Pp
347Create a mirror, deactivate one component, do the backup and connect it again.
348It will not be resynchronized, if there is no need to do so (there were no writes in
349the meantime):
350.Bd -literal -offset indent
351gmirror label data da0 da1
352gmirror deactivate data da1
353dd if=/dev/da1 of=/backup/data.img bs=1m
354gmirror activate data da1
355.Ed
356.Sh SYSCTL VARIABLES
357The following
358.Xr sysctl 8
359variables can be used to configure behavior for all mirrors.
360.Bl -tag -width indent
361.It Va kern.geom.mirror.debug
362Control the verbosity of kernel logging related to mirrors.
363A value larger than 0 will enable debug logging.
364.It Va kern.geom.mirror.timeout
365The amount of time, in seconds, to wait for all copies of a mirror to
366appear before starting the mirror.
367Disks that appear after the mirror has been started are not automatically
368added to the mirror.
369.It Va kern.geom.mirror.idletime
370The amount of time, in seconds, which must elapse after the last write to
371a mirror before that mirror is marked clean.
372Clean mirrors do not need to be synchronized after a power failure or
373system crash.
374A small value may result in frequent overwrites of the disks' metadata
375sectors, and thus may reduce the longevity of the disks.
376.It Va kern.geom.mirror.disconnect_on_failure
377Determine whether a disk is automatically removed from its mirror when an
378I/O request to that disk fails.
379.It Va kern.geom.mirror.sync_requests
380The number of parallel I/O requests used while synchronizing a mirror.
381This parameter may only be configured as a
382.Xr loader.conf 5
383tunable.
384.It Va kern.geom.mirror.sync_update_period
385The period, in seconds, at which a synchronizing mirror's metadata is
386updated.
387Periodic updates are used to record a synchronization's progress so that
388an interrupted synchronization may be resumed starting at the recorded
389offset, rather than at the beginning.
390A smaller value results in more accurate progress tracking, but also
391increases the number of non-sequential writes to the disk being synchronized.
392If the sysctl value is 0, no updates are performed until the synchronization
393is complete.
394.El
395.Sh NOTES
396Doing kernel dumps to
397.Nm
398providers is possible, but some conditions have to be met.
399First of all, a kernel dump will go only to one component and
400.Nm
401always chooses the component with the highest priority.
402Reading a dump from the mirror on boot will only work if the
403.Cm prefer
404balance algorithm is used (that way
405.Nm
406will read only from the component with the highest priority).
407If you use a different balance algorithm, you should create an
408.Xr rc 8
409script that sets the balance algorithm to
410.Cm prefer ,
411for example with the following command:
412.Bd -literal -offset indent
413gmirror configure -b prefer data
414.Ed
415.Pp
416Make sure that
417.Xr rcorder 8
418schedules the new script before
419.Xr savecore 8 .
420The desired balance algorithm can be restored later on
421by placing the following command in
422.Xr rc.local 8 :
423.Bd -literal -offset indent
424gmirror configure -b round-robin data
425.Ed
426.Pp
427The decision which component to choose for dumping is made when
428.Xr dumpon 8
429is called.
430If on the next boot a component with a higher priority will be available,
431the prefer algorithm will choose to read from it and
432.Xr savecore 8
433will find nothing.
434If on the next boot a component with the highest priority will be synchronized,
435the prefer balance algorithm will read from the next one, thus will find nothing
436there.
437.Sh SEE ALSO
438.Xr geom 4 ,
439.Xr dumpon 8 ,
440.Xr geom 8 ,
441.Xr gvinum 8 ,
442.Xr mount 8 ,
443.Xr newfs 8 ,
444.Xr savecore 8 ,
445.Xr sysctl 8 ,
446.Xr umount 8
447.Sh HISTORY
448The
449.Nm
450utility appeared in
451.Fx 5.3 .
452.Sh AUTHORS
453.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org
454.Sh BUGS
455There should be a way to change a component's priority inside a running mirror.
456.Pp
457There should be a section with an implementation description.
458