sbin/mount_union/mount_union.8

   1 .\"     $NetBSD: mount_union.8,v 1.18 2008/02/05 16:54:07 ad Exp $
   2 .\"
   3 .\" Copyright (c) 1994
   4 .\" The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software donated to Berkeley by
   7 .\" Jan-Simon Pendry.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)mount_union.8       8.7 (Berkeley) 5/1/95
  34 .\"
  35 .Dd February 5, 2008
  36 .Dt MOUNT_UNION 8
  37 .Os
  38 .Sh NAME
  39 .Nm mount_union
  40 .Nd mount union filesystems
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl b
  44 .Op Fl o Ar options
  45 .Ar directory
  46 .Ar uniondir
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 command attaches
  51 .Ar directory
  52 above
  53 .Ar uniondir
  54 in such a way that the contents of both directory trees remain visible.
  55 By default,
  56 .Ar directory
  57 becomes the
  58 .Em upper
  59 layer and
  60 .Ar uniondir
  61 becomes the
  62 .Em lower
  63 layer.
  64 .Pp
  65 Both
  66 .Ar directory
  67 and
  68 .Ar uniondir
  69 are converted to absolute paths before use.
  70 .Pp
  71 The options are as follows:
  72 .Bl -tag -width indent
  73 .It Fl b
  74 Invert the default position, so that
  75 .Ar directory
  76 becomes the lower layer and
  77 .Ar uniondir
  78 becomes the upper layer.
  79 However,
  80 .Ar uniondir
  81 remains the mount point.
  82 .It Fl o
  83 Options are specified with a
  84 .Fl o
  85 flag followed by a comma separated string of options.
  86 See the
  87 .Xr mount 8
  88 man page for possible options and their meanings.
  89 .El
  90 .Pp
  91 Filenames are looked up in the upper layer and then in the
  92 lower layer.
  93 If a directory is found in the lower layer, and there is no entry
  94 in the upper layer, then a
  95 .Em shadow
  96 directory will be created in the upper layer.
  97 It will be owned by the user who originally did the union mount,
  98 with mode
  99 .Qq rwxrwxrwx
 100 .Pq 0777
 101 modified by the umask in effect at that time.
 102 .Pp
 103 If a file exists in the upper layer then there is no way to access
 104 a file with the same name in the lower layer.
 105 If necessary, a combination of loopback and union mounts can be made
 106 which will still allow the lower files to be accessed by a different
 107 pathname.
 108 .Pp
 109 Except in the case of a directory,
 110 access to an object is granted via the normal filesystem access checks.
 111 For directories, the current user must have access to both the upper
 112 and lower directories (should they both exist).
 113 .Pp
 114 Requests to create or modify objects in
 115 .Ar uniondir
 116 are passed to the upper layer with the exception of a few special cases.
 117 An attempt to open for writing a file which exists in the lower layer
 118 causes a copy of the
 119 .Em entire
 120 file to be made to the upper layer, and then for the upper layer copy
 121 to be opened.
 122 Similarly, an attempt to truncate a lower layer file to zero length
 123 causes an empty file to be created in the upper layer.
 124 Any other operation which would ultimately require modification to
 125 the lower layer fails with
 126 .Dv EROFS .
 127 .Pp
 128 The union filesystem manipulates the namespace, rather than
 129 individual filesystems.
 130 The union operation applies recursively down the directory tree
 131 now rooted at
 132 .Ar uniondir .
 133 Thus any filesystems which are mounted under
 134 .Ar uniondir
 135 will take part in the union operation.
 136 This differs from the
 137 .Em union
 138 option to
 139 .Xr mount 8
 140 which only applies the union operation to the mount point itself,
 141 and then only for lookups.
 142 .Sh EXAMPLES
 143 The commands
 144 .Bd -literal -offset indent
 145 mount -t cd9660 -o ro /dev/cd0a /usr/src
 146 mount -t union /var/obj /usr/src
 147 .Ed
 148 .Pp
 149 mount the
 150 .Tn CD-ROM
 151 drive
 152 .Pa /dev/cd0a
 153 on
 154 .Pa /usr/src
 155 and then attaches
 156 .Pa /var/obj
 157 on top.
 158 For most purposes the effect of this is to make the
 159 source tree appear writable
 160 even though it is stored on a
 161 .Tn CD-ROM .
 162 .Pp
 163 The command
 164 .Bd -literal -offset indent
 165 mount -t union -o -b /sys $HOME/sys
 166 .Ed
 167 .Pp
 168 attaches the system source tree below the
 169 .Pa sys
 170 directory in the user's home directory.
 171 This allows individual users to make private changes
 172 to the source, and build new kernels, without those
 173 changes becoming visible to other users.
 174 Note that the files in the lower layer remain
 175 accessible via
 176 .Pa /sys .
 177 .Sh SEE ALSO
 178 .Xr intro 2 ,
 179 .Xr mount 2 ,
 180 .Xr unmount 2 ,
 181 .Xr fstab 5 ,
 182 .Xr fsck_ffs 8 ,
 183 .Xr mount 8 ,
 184 .Xr mount_null 8 ,
 185 .Xr sysctl 8
 186 .Sh HISTORY
 187 The
 188 .Nm
 189 command first appeared in
 190 .Bx 4.4 .
 191 .Sh BUGS
 192 Without whiteout support from the filesystem backing the upper layer,
 193 there is no way that delete and rename operations on lower layer
 194 objects can be done.
 195 An attempt to mount a union directory under one which does not
 196 have whiteout support will return
 197 .Dv EOPNOTSUPP
 198 .Pq Qq Operation not supported .
 199 Whiteout support can be added to an existing FFS filesystem
 200 by using the
 201 .Fl c
 202 option of
 203 .Xr fsck_ffs 8 .
 204 .Pp
 205 Running
 206 .Xr find 1
 207 over a union tree has the side-effect of creating
 208 a tree of shadow directories in the upper layer.