209 lines
5.9 KiB
Groff
209 lines
5.9 KiB
Groff
.\" $NetBSD: mount_union.8,v 1.20 2017/06/07 15:24:50 abhinav Exp $
|
|
.\"
|
|
.\" Copyright (c) 1994
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software donated to Berkeley by
|
|
.\" Jan-Simon Pendry.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)mount_union.8 8.7 (Berkeley) 5/1/95
|
|
.\"
|
|
.Dd February 5, 2008
|
|
.Dt MOUNT_UNION 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mount_union
|
|
.Nd mount union file systems
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl b
|
|
.Op Fl o Ar options
|
|
.Ar directory
|
|
.Ar uniondir
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
command attaches
|
|
.Ar directory
|
|
above
|
|
.Ar uniondir
|
|
in such a way that the contents of both directory trees remain visible.
|
|
By default,
|
|
.Ar directory
|
|
becomes the
|
|
.Em upper
|
|
layer and
|
|
.Ar uniondir
|
|
becomes the
|
|
.Em lower
|
|
layer.
|
|
.Pp
|
|
Both
|
|
.Ar directory
|
|
and
|
|
.Ar uniondir
|
|
are converted to absolute paths before use.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width indent
|
|
.It Fl b
|
|
Invert the default position, so that
|
|
.Ar directory
|
|
becomes the lower layer and
|
|
.Ar uniondir
|
|
becomes the upper layer.
|
|
However,
|
|
.Ar uniondir
|
|
remains the mount point.
|
|
.It Fl o
|
|
Options are specified with a
|
|
.Fl o
|
|
flag followed by a comma separated string of options.
|
|
See the
|
|
.Xr mount 8
|
|
man page for possible options and their meanings.
|
|
.El
|
|
.Pp
|
|
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
|
|
.Em shadow
|
|
directory will be created in the upper layer.
|
|
It will be owned by the user who originally did the union mount,
|
|
with mode
|
|
.Qq rwxrwxrwx
|
|
.Pq 0777
|
|
modified by the umask in effect at that time.
|
|
.Pp
|
|
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 combination of loopback and union mounts can be made
|
|
which will still allow the lower files to be accessed by a different
|
|
pathname.
|
|
.Pp
|
|
Except in the case of a directory,
|
|
access to an object is granted via the normal file system access checks.
|
|
For directories, the current user must have access to both the upper
|
|
and lower directories (should they both exist).
|
|
.Pp
|
|
Requests to create or modify objects in
|
|
.Ar 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
|
|
.Em 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 lower layer file to zero length
|
|
causes an empty file to be created in the upper layer.
|
|
Any other operation which would ultimately require modification to
|
|
the lower layer fails with
|
|
.Dv EROFS .
|
|
.Pp
|
|
The union file system manipulates the namespace, rather than
|
|
individual file systems.
|
|
The union operation applies recursively down the directory tree
|
|
now rooted at
|
|
.Ar uniondir .
|
|
Thus any file systems which are mounted under
|
|
.Ar uniondir
|
|
will take part in the union operation.
|
|
This differs from the
|
|
.Em union
|
|
option to
|
|
.Xr mount 8
|
|
which only applies the union operation to the mount point itself,
|
|
and then only for lookups.
|
|
.Sh EXAMPLES
|
|
The commands
|
|
.Bd -literal -offset indent
|
|
mount -t cd9660 -o ro /dev/cd0a /usr/src
|
|
mount -t union /var/obj /usr/src
|
|
.Ed
|
|
.Pp
|
|
mount the
|
|
.Tn CD-ROM
|
|
drive
|
|
.Pa /dev/cd0a
|
|
on
|
|
.Pa /usr/src
|
|
and then attaches
|
|
.Pa /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
|
|
.Tn CD-ROM .
|
|
.Pp
|
|
The command
|
|
.Bd -literal -offset indent
|
|
mount -t union -o -b /sys $HOME/sys
|
|
.Ed
|
|
.Pp
|
|
attaches the system source tree below the
|
|
.Pa sys
|
|
directory in the user's home directory.
|
|
This allows individual users to make private changes
|
|
to the source, and build new kernels, without those
|
|
changes becoming visible to other users.
|
|
Note that the files in the lower layer remain
|
|
accessible via
|
|
.Pa /sys .
|
|
.Sh SEE ALSO
|
|
.Xr intro 2 ,
|
|
.Xr mount 2 ,
|
|
.Xr unmount 2 ,
|
|
.Xr fstab 5 ,
|
|
.Xr fsck_ffs 8 ,
|
|
.Xr mount 8 ,
|
|
.Xr mount_null 8 ,
|
|
.Xr sysctl 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
command first appeared in
|
|
.Bx 4.4 .
|
|
.Sh BUGS
|
|
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.
|
|
An attempt to mount a union directory under one which does not
|
|
have whiteout support will return
|
|
.Dv EOPNOTSUPP
|
|
.Pq Qq Operation not supported .
|
|
Whiteout support can be added to an existing FFS file system
|
|
by using the
|
|
.Fl c
|
|
option of
|
|
.Xr fsck_ffs 8 .
|
|
.Pp
|
|
Running
|
|
.Xr find 1
|
|
over a union tree has the side-effect of creating
|
|
a tree of shadow directories in the upper layer.
|