mount_unionfs(8)
NAME
mount_unionfs - mount union file systems
SYNOPSIS
mount_unionfs [-br] [-o options] directory uniondir
DESCRIPTION
- The mount_unionfs utility attaches directory above uniondir
- in such a way
that the contents of both directory trees remain visible. - By default,
directory becomes the upper layer and uniondir becomes the - lower layer.
- The options are as follows:
- -b Invert the default position, so that directory be
- comes the lower
- layer and uniondir becomes the upper layer. Howev
- er, uniondir
remains the mount point. - -o Options are specified with a -o flag followed by a
- comma sepa
- rated string of options. See the mount(8) man page
- for possible
options and their meanings. - -r Hide the lower layer completely in the same way as
- mounting with
- mount_nullfs(8).
- To enforce file system security, the user mounting the file
- system must
be superuser or else have write permission on the mounted-on - directory.
In addition, the vfs.usermount sysctl(8) variable must be - set to 1 to
permit file system mounting by ordinary users. - Filenames are looked up in the upper layer and then in the
- lower layer.
If a directory is found in the lower layer, and there is no - entry in the
upper layer, then a shadow directory will be created in the - upper layer.
It will be owned by the user who originally did the union - mount, with
mode ``rwxrwxrwx'' (0777) modified by the umask in effect at - that time.
- If a file exists in the upper layer then there is no way to
- access a file
with the same name in the lower layer. If necessary, a com - bination of
loopback and union mounts can be made which will still allow - the lower
files to be accessed by a different pathname. - Except in the case of a directory, access to an object is
- granted via the
normal file system access checks. For directories, the cur - rent user must
have access to both the upper and lower directories (should - they both
exist). - Requests to create or modify objects in uniondir are passed
- to the upper
layer with the exception of a few special cases. An attempt - to open for
writing a file which exists in the lower layer causes a copy - of the
entire file to be made to the upper layer, and then for the - upper layer
copy to be opened. Similarly, an attempt to truncate a low - er layer file
to zero length causes an empty file to be created in the up - per layer.
Any other operation which would ultimately require modifica - tion to the
lower layer fails with EROFS. - The union file system manipulates the namespace, rather than
- individual
file systems. The union operation applies recursively down - the directory
tree now rooted at uniondir. Thus any file systems which - are mounted
under uniondir will take part in the union operation. This - differs from
the union option to mount(8) which only applies the union - operation to
the mount point itself, and then only for lookups.
EXAMPLES
- The commands
- mount -t cd9660 -o ro /dev/cd0a /usr/src
mount -t unionfs /var/obj /usr/src - mount the CD-ROM drive /dev/cd0a on /usr/src and then at
- taches /var/obj
on top. For most purposes the effect of this is to make the - source tree
appear writable even though it is stored on a CD-ROM. - The command
mount -t unionfs -o -b /sys $HOME/sys- attaches the system source tree below the sys directory in
- the user's
home directory. This allows individual users to make pri - vate changes to
the source, and build new kernels, without those changes be - coming visible
to other users. Note that the files in the lower layer re - main accessible
via /sys.
SEE ALSO
HISTORY
- The mount_unionfs utility first appeared in 4.4BSD. It
- first worked in
FreeBSD-(fill this in).
BUGS
- THIS FILE SYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT
- DOESN'T WORK)
AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. USE - AT YOUR OWN
RISK. BEWARE OF DOG. SLIPPERY WHEN WET. - This code also needs an owner in order to be less dangerous
- - serious
hackers can apply by sending mail to <hackers@FreeBSD.org> - and announcing
their intent to take it over. - Without whiteout support from the file system backing the
- upper layer,
there is no way that delete and rename operations on lower - layer objects
can be done. EROFS is returned for this kind of operations - along with
any others which would make modifications to the lower lay - er, such as
chmod(1). - Running find(1) over a union tree has the side-effect of
- creating a tree
of shadow directories in the upper layer. - BSD March 27, 1994