217 lines
6.4 KiB
Groff
217 lines
6.4 KiB
Groff
.\" 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.
|
|
.\" 4. 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.6 (Berkeley) 3/27/94
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd March 27, 1994
|
|
.Dt MOUNT_UNIONFS 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mount_unionfs
|
|
.Nd mount union file systems
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl br
|
|
.Op Fl o Ar options
|
|
.Ar directory
|
|
.Ar uniondir
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility 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
|
|
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.
|
|
.It Fl r
|
|
Hide the lower layer completely in the same way as mounting with
|
|
.Xr mount_nullfs 8 .
|
|
.El
|
|
.Pp
|
|
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
|
|
.Em vfs.usermount
|
|
.Xr sysctl 3
|
|
variable must be set to 1 to permit file system mounting by ordinary users.
|
|
.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
|
|
.Dq rwxrwxrwx
|
|
(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
|
|
.Er 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 unionfs /var/obj /usr/src
|
|
.Ed
|
|
.Pp
|
|
mount the 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 CD-ROM.
|
|
.Pp
|
|
The command
|
|
.Bd -literal -offset indent
|
|
mount -t unionfs -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 mount 8 ,
|
|
.Xr mount_nullfs 8
|
|
.Sh 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.
|
|
.Pp
|
|
This code also needs an owner in order to be less dangerous - serious
|
|
hackers can apply by sending mail to
|
|
.Aq hackers@FreeBSD.org
|
|
and announcing
|
|
their intent to take it over.
|
|
.Pp
|
|
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.
|
|
.Er EROFS
|
|
is returned for this kind of operations along with any others
|
|
which would make modifications to the lower layer, such as
|
|
.Xr chmod 1 .
|
|
.Pp
|
|
Running
|
|
.Xr find 1
|
|
over a union tree has the side-effect of creating
|
|
a tree of shadow directories in the upper layer.
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility first appeared in
|
|
.Bx 4.4 .
|
|
It first worked in
|
|
.Fx Ns -(fill this in) .
|