2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software donated to Berkeley by
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 4. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" @(#)mount_union.8 8.6 (Berkeley) 3/27/94
39 .Nd mount union file systems
53 in such a way that the contents of both directory trees remain visible.
64 The options are as follows:
65 .Bl -tag -width indent
72 Options are specified with the
74 flag followed by an option.
75 The following options are available:
76 .Bl -tag -width indent
78 Inverts the default position, so that
80 becomes the lower layer and
82 becomes the upper layer.
85 remains the mount point.
86 .It Sm Cm copymode No = Cm traditional | transparent | masquerade Sm
87 Specifies the way to create a file or a directory in the upper layer
88 automatically when needed.
92 uses the same way as the old unionfs for backward compatibility, and
94 duplicates the file and directory mode bits and the ownership in the
95 lower layer to the created file in the upper layer.
101 .It Sm Cm whiteout No = Cm always | whenneeded Sm
102 Specifies whether whiteouts should always be made in the upper layer
103 when removing a file or directory or only when it already exists in the
105 .It Cm udir Ns = Ns Ar mode
106 Specifies directory mode bits in octal for
109 .It Cm ufile Ns = Ns Ar mode
110 Specifies file mode bits in octal for
113 .It Cm gid Ns = Ns Ar gid
117 .It Cm uid Ns = Ns Ar uid
124 To enforce file system security, the user mounting a file system
125 must be superuser or else have write permission on the mounted-on
130 variable must be set to 1 to permit file system mounting by ordinary users.
137 to be set to 0 because this functionality can only be used by superusers.
139 Filenames are looked up in the upper layer and then in the
141 If a directory is found in the lower layer, and there is no entry
142 in the upper layer, then a
144 directory will be created in the upper layer.
145 The ownership and the mode bits are set depending on the
150 mode, it will be owned by the user who originally did the
151 union mount, with mode 0777
153 modified by the umask in effect at that time.
155 If a file exists in the upper layer then there is no way to access
156 a file with the same name in the lower layer.
157 If necessary, a combination of loopback and union mounts can be made
158 which will still allow the lower files to be accessed by a different
161 Except in the case of a directory,
162 access to an object is granted via the normal file system access checks.
163 For directories, the current user must have access to both the upper
164 and lower directories (should they both exist).
166 Requests to create or modify objects in
168 are passed to the upper layer with the exception of a few special cases.
169 An attempt to open for writing a file which exists in the lower layer
172 file to be made to the upper layer, and then for the upper layer copy
174 Similarly, an attempt to truncate a lower layer file to zero length
175 causes an empty file to be created in the upper layer.
176 Any other operation which would ultimately require modification to
177 the lower layer fails with
180 The union file system manipulates the namespace, rather than
181 individual file systems.
182 The union operation applies recursively down the directory tree
185 Thus any file systems which are mounted under
187 will take part in the union operation.
188 This differs from the
192 which only applies the union operation to the mount point itself,
193 and then only for lookups.
197 is created in the upper layer, the
199 mode sets it the fixed access mode bits given in
205 option and the owner given in
209 options, instead of ones in the lower layer.
212 mode and when owner of the file or directory matches
215 option, only mode bits for the owner will be modified.
216 More specifically, the file mode bits in the upper layer will
218 (mode in the lower layer)
222 AND 0700), and the ownership will be the same as one in the lower layer.
224 The default values for
225 .Cm ufile , udir , uid ,
236 were specified, access mode bits in the mount point will be used.
242 were specified, ownership in the mount point will be used.
248 is not specified, the value of the other option will be used.
254 is not specified, the value of the other option will be used.
258 .Bd -literal -offset indent
259 mount -t cd9660 -o ro /dev/cd0 /usr/src
260 mount -t unionfs -o noatime /var/obj /usr/src
263 mount the CD-ROM drive
270 For most purposes the effect of this is to make the
271 source tree appear writable
272 even though it is stored on a CD-ROM.
275 option is useful to avoid unnecessary copying from the lower to the
279 .Bd -literal -offset indent
280 mount -t cd9660 -o ro /dev/cd0 /usr/src
282 mount -t unionfs -o noatime -o copymode=masquerade -o uid=builder \\
283 -o udir=755 -o ufile=644 /var/obj /usr/src
286 also mount the CD-ROM drive
293 Furthermore, the owner of all files and directories in
295 is a regular user with UID 2020
296 when seen from the upper layer.
297 Note that for the access mode bits,
298 ones in the lower layer
299 (on the CD-ROM, in this example)
300 are still used without change.
301 Thus, write privilege to the upper layer can be controlled
302 independently from access mode bits and ownership in the lower layer.
303 If a user does not have read privilege from the lower layer,
304 one cannot still read even when the upper layer is mounted by using
309 .Bd -literal -offset indent
310 mount -t unionfs -o noatime -o below /sys $HOME/sys
313 attaches the system source tree below the
315 directory in the user's home directory.
316 This allows individual users to make private changes
317 to the source, and build new kernels, without those
318 changes becoming visible to other users.
319 Note that the files in the lower layer remain
332 utility first appeared in
337 option for hiding the lower layer completely was removed in
339 because this is identical to using
345 .An Masanori OZAWA Aq ozawa@ongs.co.jp
346 reimplemented handling of locking, whiteout, and file mode bits, and
347 .An Hiroki Sato Aq hrs@FreeBSD.org
348 wrote about the changes in this manual page.
350 THIS FILE SYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK)
351 AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM.
356 BATTERIES NOT INCLUDED.
358 This code also needs an owner in order to be less dangerous - serious
359 hackers can apply by sending mail to
360 .Aq freebsd-fs@FreeBSD.org
362 their intent to take it over.
364 Without whiteout support from the file system backing the upper layer,
365 there is no way that delete and rename operations on lower layer
368 is returned for this kind of operations as generated by VOP_WHITEOUT()
369 along with any others which would make modifications to the lower
375 over a union tree has the side-effect of creating
376 a tree of shadow directories in the upper layer.
378 The current implementation does not support copying extended attributes
382 or so on to the upper layer.
383 Note that this may be a security issue.
385 A shadow directory, which is one automatically created in the upper
386 layer when it exists in the lower layer and does not exist in the
387 upper layer, is always created with the superuser privilege.
388 However, a file copied from the lower layer in the same way
389 is created by the user who accessed it.
391 if the user is not the superuser, even in
393 mode the access mode bits in the copied file in the upper layer
394 will not always be the same as ones in the lower layer.
395 This behavior should be fixed.