1.\" Copyright (c) 1994 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software donated to Berkeley by 5.\" Jan-Simon Pendry. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)mount_union.8 8.6 (Berkeley) 3/27/94 32.\" 33.Dd October 3, 2016 34.Dt MOUNT_UNIONFS 8 35.Os 36.Sh NAME 37.Nm mount_unionfs 38.Nd mount union file systems 39.Sh SYNOPSIS 40.Nm 41.Op Fl b 42.Op Fl o Ar options 43.Ar directory 44.Ar uniondir 45.Sh DESCRIPTION 46The 47.Nm 48utility attaches 49.Ar directory 50above 51.Ar uniondir 52in such a way that the contents of both directory trees remain visible. 53By default, 54.Ar directory 55becomes the 56.Em upper 57layer and 58.Ar uniondir 59becomes the 60.Em lower 61layer. 62.Pp 63The options are as follows: 64.Bl -tag -width indent 65.It Fl b 66Deprecated. 67Use 68.Fl o Cm below 69instead. 70.It Fl o 71Options are specified with the 72.Fl o 73flag followed by an option. 74The following options are available: 75.Bl -tag -width indent 76.It Cm below 77Inverts the default position, so that 78.Ar directory 79becomes the lower layer and 80.Ar uniondir 81becomes the upper layer. 82However, 83.Ar uniondir 84remains the mount point. 85.It Cm copymode No = Cm traditional | transparent | masquerade 86Specifies the way to create a file or a directory in the upper layer 87automatically when needed. 88The 89.Cm traditional 90mode 91uses the same way as the old unionfs for backward compatibility, and 92.Cm transparent 93duplicates the file and directory mode bits and the ownership in the 94lower layer to the created file in the upper layer. 95For behavior of the 96.Cm masquerade 97mode, see 98.Sx MASQUERADE MODE 99below. 100.It Cm whiteout No = Cm always | whenneeded 101Specifies whether whiteouts should always be made in the upper layer 102when removing a file or directory or only when it already exists in the 103lower layer. 104.It Cm udir Ns = Ns Ar mode 105Specifies directory mode bits in octal for 106.Cm masquerade 107mode. 108.It Cm ufile Ns = Ns Ar mode 109Specifies file mode bits in octal for 110.Cm masquerade 111mode. 112.It Cm gid Ns = Ns Ar gid 113Specifies group for 114.Cm masquerade 115mode. 116.It Cm uid Ns = Ns Ar uid 117Specifies user for 118.Cm masquerade 119mode. 120.El 121.El 122.Pp 123To enforce file system security, the user mounting a file system 124must be superuser or else have write permission on the mounted-on 125directory. 126In addition, the 127.Va vfs.usermount 128.Xr sysctl 8 129variable must be set to 1 to permit file system mounting by ordinary users. 130However, note that 131.Cm transparent 132and 133.Cm masquerade 134modes require 135.Va vfs.usermount 136to be set to 0 because this functionality can only be used by superusers. 137.Pp 138Filenames are looked up in the upper layer and then in the 139lower layer. 140If a directory is found in the lower layer, and there is no entry 141in the upper layer, then a 142.Em shadow 143directory will be created in the upper layer. 144The ownership and the mode bits are set depending on the 145.Cm copymode 146option. 147In 148.Cm traditional 149mode, it will be owned by the user who originally did the 150union mount, with mode 0777 151.Pq Dq Li rwxrwxrwx 152modified by the umask in effect at that time. 153.Pp 154If a file exists in the upper layer then there is no way to access 155a file with the same name in the lower layer. 156If necessary, a combination of loopback and union mounts can be made 157which will still allow the lower files to be accessed by a different 158pathname. 159.Pp 160Except in the case of a directory, 161access to an object is granted via the normal file system access checks. 162For directories, the current user must have access to both the upper 163and lower directories (should they both exist). 164.Pp 165Requests to create or modify objects in 166.Ar uniondir 167are passed to the upper layer with the exception of a few special cases. 168An attempt to open for writing a file which exists in the lower layer 169causes a copy of the 170.Em entire 171file to be made to the upper layer, and then for the upper layer copy 172to be opened. 173Similarly, an attempt to truncate a lower layer file to zero length 174causes an empty file to be created in the upper layer. 175Any other operation which would ultimately require modification to 176the lower layer fails with 177.Er EROFS . 178.Pp 179The union file system manipulates the namespace, rather than 180individual file systems. 181The union operation applies recursively down the directory tree 182now rooted at 183.Ar uniondir . 184Thus any file systems which are mounted under 185.Ar uniondir 186will take part in the union operation. 187This differs from the 188.Cm union 189option to 190.Xr mount 8 191which only applies the union operation to the mount point itself, 192and then only for lookups. 193.Sh MASQUERADE MODE 194When a file 195(or a directory) 196is created in the upper layer, the 197.Cm masquerade 198mode sets it the fixed access mode bits given in 199.Cm ufile 200(for files) 201or 202.Cm udir 203(for directories) 204option and the owner given in 205.Cm udir 206and 207.Cm gid 208options, instead of ones in the lower layer. 209Note that in the 210.Cm masquerade 211mode and when owner of the file or directory matches 212one specified in 213.Cm uid 214option, only mode bits for the owner will be modified. 215More specifically, the file mode bits in the upper layer will 216be 217(mode in the lower layer) 218OR 219(mode given in 220.Cm ufile 221AND 0700), and the ownership will be the same as one in the lower layer. 222.Pp 223The default values for 224.Cm ufile , udir , uid , 225and 226.Cm gid 227are as follow: 228.Pp 229.Bl -bullet -compact 230.It 231If none of 232.Cm ufile 233and 234.Cm udir 235were specified, access mode bits in the mount point will be used. 236.It 237If none of 238.Cm uid 239and 240.Cm gid 241were specified, ownership in the mount point will be used. 242.It 243If one of 244.Cm udir 245or 246.Cm ufile 247is not specified, the value of the other option will be used. 248.It 249If one of 250.Cm uid 251or 252.Cm gid 253is not specified, the value of the other option will be used. 254.El 255.Sh EXAMPLES 256The commands 257.Bd -literal -offset indent 258mount -t cd9660 -o ro /dev/cd0 /usr/src 259mount -t unionfs -o noatime /var/obj /usr/src 260.Ed 261.Pp 262mount the CD-ROM drive 263.Pa /dev/cd0 264on 265.Pa /usr/src 266and then attaches 267.Pa /var/obj 268on top. 269For most purposes the effect of this is to make the 270source tree appear writable 271even though it is stored on a CD-ROM. 272The 273.Fl o Cm noatime 274option is useful to avoid unnecessary copying from the lower to the 275upper layer. 276.Pp 277The commands 278.Bd -literal -offset indent 279mount -t cd9660 -o ro /dev/cd0 /usr/src 280chown 2020 /usr/src 281mount -t unionfs -o noatime -o copymode=masquerade -o uid=builder \\ 282 -o udir=755 -o ufile=644 /var/obj /usr/src 283.Ed 284.Pp 285also mount the CD-ROM drive 286.Pa /dev/cd0 287on 288.Pa /usr/src 289and then attaches 290.Pa /var/obj 291on top. 292Furthermore, the owner of all files and directories in 293.Pa /usr/src 294is a regular user with UID 2020 295when seen from the upper layer. 296Note that for the access mode bits, 297ones in the lower layer 298(on the CD-ROM, in this example) 299are still used without change. 300Thus, write privilege to the upper layer can be controlled 301independently from access mode bits and ownership in the lower layer. 302If a user does not have read privilege from the lower layer, 303one cannot still read even when the upper layer is mounted by using 304.Cm masquerade 305mode. 306.Pp 307The command 308.Bd -literal -offset indent 309mount -t unionfs -o noatime -o below /sys $HOME/sys 310.Ed 311.Pp 312attaches the system source tree below the 313.Pa sys 314directory in the user's home directory. 315This allows individual users to make private changes 316to the source, and build new kernels, without those 317changes becoming visible to other users. 318Note that the files in the lower layer remain 319accessible via 320.Pa /sys . 321.Sh SEE ALSO 322.Xr intro 2 , 323.Xr mount 2 , 324.Xr unmount 2 , 325.Xr fstab 5 , 326.Xr mount 8 , 327.Xr mount_nullfs 8 328.Sh HISTORY 329The 330.Nm mount_null 331utility first appeared in 332.Bx 4.4 . 333It was renamed to 334.Nm 335in 336.Fx 5.0 . 337.Pp 338The 339.Fl r 340option for hiding the lower layer completely was removed in 341.Fx 7.0 342because this is identical to using 343.Xr mount_nullfs 8 . 344.Sh AUTHORS 345.An -nosplit 346In 347.Fx 7.0 , 348.An Masanori OZAWA Aq Mt ozawa@ongs.co.jp 349reimplemented handling of locking, whiteout, and file mode bits, and 350.An Hiroki Sato Aq Mt hrs@FreeBSD.org 351wrote about the changes in this manual page. 352.Sh BUGS 353THIS FILE SYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK) 354AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. 355USE AT YOUR OWN RISK. 356.Pp 357This code also needs an owner in order to be less dangerous - serious 358hackers can apply by sending mail to 359.Aq Mt freebsd-fs@FreeBSD.org 360and announcing 361their intent to take it over. 362.Pp 363Without whiteout support from the file system backing the upper layer, 364there is no way that delete and rename operations on lower layer 365objects can be done. 366.Er EOPNOTSUPP 367is returned for this kind of operations as generated by VOP_WHITEOUT() 368along with any others which would make modifications to the lower 369layer, such as 370.Xr chmod 1 . 371.Pp 372Running 373.Xr find 1 374over a union tree has the side-effect of creating 375a tree of shadow directories in the upper layer. 376.Pp 377The current implementation does not support copying extended attributes 378for 379.Xr acl 9 , 380.Xr mac 9 , 381or so on to the upper layer. 382Note that this may be a security issue. 383.Pp 384A shadow directory, which is one automatically created in the upper 385layer when it exists in the lower layer and does not exist in the 386upper layer, is always created with the superuser privilege. 387However, a file copied from the lower layer in the same way 388is created by the user who accessed it. 389Because of this, 390if the user is not the superuser, even in 391.Cm transparent 392mode the access mode bits in the copied file in the upper layer 393will not always be the same as ones in the lower layer. 394This behavior should be fixed. 395