xref: /freebsd/lib/geom/union/gunion.8 (revision 1dfcff294e44d4b45813288ef4095c36abb22f0e)
1.\"
2.\" Copyright (c) 2022 Marshall Kirk McKusick <mckusick@mckusick.com>
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 19, 2022
28.Dt GUNION 8
29.Os
30.Sh NAME
31.Nm gunion
32.Nd "control utility for UNION GEOM class"
33.Sh SYNOPSIS
34.Nm
35.Cm create
36.Op Fl v
37.Op Fl o Ar offset
38.Op Fl s Ar size
39.Op Fl S Ar secsize
40.Op Fl Z Ar gunionname
41.Ar upperdev lowerdev
42.Nm
43.Cm destroy
44.Op Fl fv
45.Ar prov ...
46.Nm
47.Cm reset
48.Op Fl v
49.Ar prov ...
50.Nm
51.Cm revert
52.Op Fl v
53.Ar prov ...
54.Nm
55.Cm commit
56.Op Fl frv
57.Ar prov ...
58.Nm
59.Cm list
60.Nm
61.Cm status
62.Nm
63.Cm load
64.Nm
65.Cm unload
66.Sh DESCRIPTION
67The
68.Nm
69utility is used to track changes to a read-only disk on a writable disk.
70Logically, a writable disk is placed over a read-only disk.
71Write requests are intercepted and stored on the writable disk.
72Read requests are first checked to see if they have been written
73on the top (writable disk) and if found are returned.
74If they have not been written on the top disk,
75then they are read from the lower disk.
76.Pp
77The
78.Nm
79utility can be especially useful if you have a large disk with a
80corrupted filesystem that you are unsure of how to repair.
81You can use
82.Nm
83to place another disk over the corrupted disk and then attempt
84to repair the filesystem.
85If the repair fails, you can revert all the changes in the upper disk
86and be back to the unchanged state of the lower disk thus allowing you
87to try another approach to repairing it.
88If the repair is successful you can request that all the writes recorded
89on the top disk be written to the lower disk.
90.Pp
91Another use of the
92.Nm
93utility is to try out upgrades to your system.
94Place the upper disk over the disk holding your filesystem that
95is to be upgraded and then run the upgrade on it.
96If it works, commit it;
97if it fails, revert the upgrade.
98An example is given below.
99.Pp
100The upper disk must be at least the size of the disk that it covers.
101The union metadata exists only for the
102period of time that the union is instantiated,
103so it is important to commit the updates before destroying the union.
104If the top disk is about 2.5 percent larger for 512 byte sector disks
105(or 0.5 percent larger for 4K sector disks) than the disk that it covers,
106it is posible (thought not currently implemented) to save the union
107metadata between instantiations of the union device.
108.Pp
109If you do not have physical media available to use for the upper layer, the
110.Xr md 4
111disk can be used instead.
112When used in
113.Cm swap
114mode the changes are all held in buffer memory.
115Pages get pushed out to the swap when the system is under memory pressure,
116otherwise they stay in the operating memory.
117If long-term persistance is desired,
118.Cm vnode
119mode can be used in which a regular file is used as backing store.
120The disk space used by the file is based on the amount of data that
121is written to the top device.
122.Pp
123The first argument to
124.Nm
125indicates an action to be performed:
126.Bl -tag -width "destroy"
127.It Cm create
128Set up a union provider on the two given devices.
129The first device given is used as the top device and must be writable.
130The second device given is used as the bottom device and need only be readable.
131The second device may be mounted read-only but it is recommended
132that it be unmounted and accessed only through a mount of the union device.
133If the operation succeeds, the new provider should appear with name
134.Pa /dev/ Ns Ao Ar upperdev Ac Ns - Ns Ao Ar lowerdev Ac Ns Pa .union .
135An alternate name can be specified with the
136.Fl Z
137flag.
138The kernel module
139.Pa geom_union.ko
140will be loaded if it is not loaded already.
141.Pp
142Additional options include:
143.Bl -tag -width "-Z gunionname"
144.It Fl o Ar offset
145Where to begin on the original provider.
146The default is to start at the beginning of the disk (i.e., at offset 0).
147This option may be used to skip over partitioning information stored
148at the beginning of a disk.
149The offset must be a multiple of the sector size.
150.It Fl s Ar size
151Size of the transparent provider.
152The default is to be the same size as the lower disk.
153Any extra space at the end of the upper disk may be used to store
154union metadata.
155.It Fl S Ar secsize
156Sector size of the transparent provider.
157The default is to be the same sector size as the lower disk.
158.It Fl v
159Be more verbose.
160.It Fl Z Ar gunionname
161The name of the new provider.
162The suffix
163.Dq .union
164will be appended to the provider name.
165.El
166.It Cm destroy
167Turn off the given union providers.
168.Pp
169Additional options include:
170.Bl -tag -width "-f"
171.It Fl f
172Force the removal of the specified provider.
173.It Fl v
174Be more verbose.
175.El
176.It Cm revert
177Discard all the changes made in the top layer thus reverting to the
178original state of the lower device.
179The union device may not be mounted or otherwise in use when a
180.Cm revert
181operation is being done.
182.It Cm commit
183Write all the changes made in the top device to the lower device
184thus committing the lower device to have the same data as the union.
185.Pp
186Additional options include:
187.Bl -tag -width "-f"
188.It Fl f
189The
190.Cm commit
191command will not allow the lower device to be mounted
192or otherwise in use while the
193.Cm commit
194operation is being done.
195However, the
196.Fl f
197flag may be specified to allow the lower device to be mounted read-only.
198To prevent a filesystem panic on the mounted lower-device filesystem,
199immediately after the
200.Cm commit
201operation finishes the lower-device filesystem should be unmounted
202and then remounted to update its metadata state.
203If the lower-device filesystem is currently being used as the root
204filesystem then the
205.Fl r
206flag should be specified to reboot the system at the completion of the
207.Cm commit
208operation.
209.It Fl r
210Reboot the system at the completion of the
211.Cm commit
212operation.
213.It Fl v
214Be more verbose.
215.El
216.It Cm reset
217Reset statistics for the given union providers.
218.It Cm list
219See
220.Xr geom 8 .
221.It Cm status
222See
223.Xr geom 8 .
224.It Cm load
225See
226.Xr geom 8 .
227.It Cm unload
228See
229.Xr geom 8 .
230.El
231.Sh EXIT STATUS
232Exit status is 0 on success, and 1 if the command fails.
233.Sh EXAMPLES
234The following example shows how to create and destroy a
235union provider with disks
236.Pa /dev/da0p1
237as the read-only disk on the bottom and
238.Pa /dev/md0
239as the wriable disk on the top.
240.Bd -literal -offset indent
241gunion create -v md0 da0p1
242mount /dev/md0-da0p1.union /mnt
243.Ed
244.Pp
245Proceed to make changes in /mnt filesystem.
246If they are successful and you want to keep them.
247.Bd -literal -offset indent
248umount /mnt
249gunion commit -v md0-da0p1.union
250.Ed
251.Pp
252If they are unsuccessful and you want to roll back.
253.Bd -literal -offset indent
254umount /mnt
255gunion revert -v md0-da0p1.union
256.Ed
257.Pp
258When done eliminate the union.
259.Bd -literal -offset indent
260umount /mnt
261gunion destroy -v md0-da0p1.union
262.Ed
263.Pp
264All uncommitted changes will be discarded when the union is destroyed.
265.Pp
266If you use the name of the full disk, for example
267.Pa da0
268and it is labelled,
269then a union name will appear for the disk as
270.Pa md0-da0.union
271as well as for each partition on the disk as
272.Pa md0-da0p1.union ,
273.Pa md0-da0p2.union ,
274etc.
275A commit operation can be done only on
276.Pa md0-da0.union
277and will commit changes to all the partitions.
278If partition level commits are desired,
279then a union must be created for each partition.
280.Pp
281The traffic statistics for the given
282union providers can be obtained with the
283.Cm list
284command.
285The example below shows the number of bytes written with
286.Xr newfs 8 :
287.Bd -literal -offset indent
288gunion create md0 da0p1
289newfs /dev/md0-da0p1.union
290gunion list
291.Ed
292.Sh SYSCTL VARIABLES
293The following
294.Xr sysctl 8
295variables can be used to control the behavior of the
296.Nm UNION
297GEOM class.
298The default value is shown next to each variable.
299.Bl -tag -width indent
300.It Va kern.geom.union.debug : No 0
301Debug level of the
302.Nm UNION
303GEOM class.
304This can be set to a number between 0 and 4 inclusive.
305If set to 0, no debug information is printed.
306If set to 1, all the verbose messages are logged.
307If set to 2, addition error-related information is logged.
308If set to 3, mapping operations are logged.
309If set to 4, the maximum amount of debug information is printed.
310.El
311.Sh SEE ALSO
312.Xr geom 4 ,
313.Xr geom 8
314.Sh HISTORY
315The
316.Nm
317utility appeared in
318.Fx 14.0 .
319.Sh AUTHORS
320.An Marshall Kirk McKusick Aq Mt mckusick@mckusick.com
321