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