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.\" %sccs.include.redist.roff% 8.\" 9.\" @(#)mount_union.8 8.6 (Berkeley) 03/27/94 10.\" 11.Dd 12.Dt MOUNT_UNION 8 13.Os BSD 4.4 14.Sh NAME 15.Nm mount_union 16.Nd mount union filesystems 17.Sh SYNOPSIS 18.Nm mount_union 19.Op Fl br 20.Op Fl o Ar options 21.Ar directory 22.Ar uniondir 23.Sh DESCRIPTION 24The 25.Nm mount_union 26command 27attaches 28.Ar directory 29above 30.Ar uniondir 31in such a way that the contents of both directory trees remain visible. 32By default, 33.Ar directory 34becomes the 35.Em upper 36layer and 37.Ar uniondir 38becomes the 39.Em lower 40layer. 41.Pp 42The options are as follows: 43.Bl -tag -width indent 44.It Fl b 45Invert the default position, so that 46.Ar directory 47becomes the lower layer and 48.Ar uniondir 49becomes the upper layer. 50However, 51.Ar uniondir 52remains the mount point. 53.It Fl o 54Options are specified with a 55.Fl o 56flag followed by a comma separated string of options. 57See the 58.Xr mount 8 59man page for possible options and their meanings. 60.It Fl r 61Hide the lower layer completely in the same way as mounting with 62.Xr mount_lofs 8 63or 64.Xr mount_null 8 . 65.El 66.Pp 67To enforce filesystem security, the user mounting the filesystem 68must be superuser or else have write permission on the mounted-on 69directory. 70.Pp 71Filenames are looked up in the upper layer and then in the 72lower layer. 73If a directory is found in the lower layer, and there is no entry 74in the upper layer, then a 75.Em shadow 76directory will be created in the upper layer. 77It will be owned by the user who originally did the union mount, 78with mode 79.Dq rwxrwxrwx 80(0777) modified by the umask in effect at that time. 81.Pp 82If a file exists in the upper layer then there is no way to access 83a file with the same name in the lower layer. 84If necessary, a combination of loopback and union mounts can be made 85which will still allow the lower files to be accessed by a different 86pathname. 87.Pp 88Except in the case of a directory, 89access to an object is granted via the normal filesystem access checks. 90For directories, the current user must have access to both the upper 91and lower directories (should they both exist). 92.Pp 93Requests to create or modify objects in 94.Ar uniondir 95are passed to the upper layer with the exception of a few special cases. 96An attempt to open for writing a file which exists in the lower layer 97causes a copy of the 98.Em entire 99file to be made to the upper layer, and then for the upper layer copy 100to be opened. 101Similarly, an attempt to truncate a lower layer file to zero length 102causes an empty file to be created in the upper layer. 103Any other operation which would ultimately require modification to 104the lower layer fails with 105.Dv EROFS . 106.Pp 107The union filesystem manipulates the namespace, rather than 108individual filesystems. 109The union operation applies recursively down the directory tree 110now rooted at 111.Ar uniondir . 112Thus any filesystems which are mounted under 113.Ar uniondir 114will take part in the union operation. 115This differs from the 116.Em union 117option to 118.Xr mount 8 119which only applies the union operation to the mount point itself, 120and then only for lookups. 121.Sh EXAMPLES 122The commands 123.Bd -literal -offset indent 124mount -t cd9660 -o ro /dev/cd0a /usr/src 125mount -t union -o /var/obj /usr/src 126.Ed 127.Pp 128mount the CD-ROM drive 129.Pa /dev/cd0a 130on 131.Pa /usr/src 132and then attaches 133.Pa /var/obj 134on top. 135For most purposes the effect of this is to make the 136source tree appear writable 137even though it is stored on a CD-ROM. 138.Pp 139The command 140.Bd -literal -offset indent 141mount -t union -o -b /sys $HOME/sys 142.Ed 143.Pp 144attaches the system source tree below the 145.Pa sys 146directory in the user's home directory. 147This allows individual users to make private changes 148to the source, and build new kernels, without those 149changes becoming visible to other users. 150Note that the files in the lower layer remain 151accessible via 152.Pa /sys . 153.Sh SEE ALSO 154.Xr intro 2 , 155.Xr mount 2 , 156.Xr unmount 2 , 157.Xr fstab 5 , 158.Xr mount 8 , 159.Xr mount_lofs 8 , 160.Xr mount_null 8 161.Sh BUGS 162Without whiteout support from the filesystem backing the upper layer, 163there is no way that delete and rename operations on lower layer 164objects can be done. 165.Dv EROFS 166is returned for this kind of operations along with any others 167which would make modifications to the lower layer, such as 168.Xr chmod 1 . 169.Pp 170Running 171.Xr find 1 172over a union tree has the side-effect of creating 173a tree of shadow directories in the upper layer. 174.Sh HISTORY 175The 176.Nm mount_union 177command first appeared in 178.Bx 4.4 . 179