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