lib/geom/union/gunion.8

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