diff options
Diffstat (limited to 'sbin/mount_unionfs/mount_unionfs.8')
| -rw-r--r-- | sbin/mount_unionfs/mount_unionfs.8 | 204 |
1 files changed, 204 insertions, 0 deletions
diff --git a/sbin/mount_unionfs/mount_unionfs.8 b/sbin/mount_unionfs/mount_unionfs.8 new file mode 100644 index 0000000..65a6497 --- /dev/null +++ b/sbin/mount_unionfs/mount_unionfs.8 @@ -0,0 +1,204 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 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 +.\" +.Dd March 27, 1994 +.Dt MOUNT_UNION 8 +.Os BSD 4.4 +.Sh NAME +.Nm mount_union +.Nd mount union filesystems +.Sh SYNOPSIS +.Nm mount_union +.Op Fl br +.Op Fl o Ar options +.Ar directory +.Ar uniondir +.Sh DESCRIPTION +The +.Nm mount_union +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 +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_lofs 8 +or +.Xr mount_null 8 . +.El +.Pp +To enforce filesystem security, the user mounting the filesystem +must be superuser or else have write permission on the mounted-on +directory. +.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 filesystem 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 filesystem manipulates the namespace, rather than +individual filesystems. +The union operation applies recursively down the directory tree +now rooted at +.Ar uniondir . +Thus any filesystems 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 -o /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 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 mount 8 , +.Xr mount_lofs 8 , +.Xr mount_null 8 +.Sh BUGS +Without whiteout support from the filesystem backing the upper layer, +there is no way that delete and rename operations on lower layer +objects can be done. +.Dv 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 mount_union +command first appeared in +.Bx 4.4 . |
