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