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