1.\" Copyright (c) 1994
2.\" The Regents of the University of California.  All rights reserved.
3.\"
4.\" This code is derived from software donated to Berkeley by
5.\" Jan-Simon Pendry.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
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.\" 3. 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.
18.\"
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
29.\" SUCH DAMAGE.
30.\"
31.\"	@(#)mount_union.8	8.6 (Berkeley) 3/27/94
32.\"
33.Dd October 3, 2016
34.Dt MOUNT_UNIONFS 8
35.Os
36.Sh NAME
37.Nm mount_unionfs
38.Nd mount union file systems
39.Sh SYNOPSIS
40.Nm
41.Op Fl b
42.Op Fl o Ar options
43.Ar directory
44.Ar uniondir
45.Sh DESCRIPTION
46The
47.Nm
48utility attaches
49.Ar directory
50above
51.Ar uniondir
52in such a way that the contents of both directory trees remain visible.
53By default,
54.Ar directory
55becomes the
56.Em upper
57layer and
58.Ar uniondir
59becomes the
60.Em lower
61layer.
62.Pp
63The options are as follows:
64.Bl -tag -width indent
65.It Fl b
66Deprecated.
67Use
68.Fl o Cm below
69instead.
70.It Fl o
71Options are specified with the
72.Fl o
73flag followed by an option.
74The following options are available:
75.Bl -tag -width indent
76.It Cm below
77Inverts the default position, so that
78.Ar directory
79becomes the lower layer and
80.Ar uniondir
81becomes the upper layer.
82However,
83.Ar uniondir
84remains the mount point.
85.It Cm copymode No = Cm traditional | transparent | masquerade
86Specifies the way to create a file or a directory in the upper layer
87automatically when needed.
88The
89.Cm traditional
90mode
91uses the same way as the old unionfs for backward compatibility, and
92.Cm transparent
93duplicates the file and directory mode bits and the ownership in the
94lower layer to the created file in the upper layer.
95For behavior of the
96.Cm masquerade
97mode, see
98.Sx MASQUERADE MODE
99below.
100.It Cm whiteout No = Cm always | whenneeded
101Specifies whether whiteouts should always be made in the upper layer
102when removing a file or directory or only when it already exists in the
103lower layer.
104.It Cm udir Ns = Ns Ar mode
105Specifies directory mode bits in octal for
106.Cm masquerade
107mode.
108.It Cm ufile Ns = Ns Ar mode
109Specifies file mode bits in octal for
110.Cm masquerade
111mode.
112.It Cm gid Ns = Ns Ar gid
113Specifies group for
114.Cm masquerade
115mode.
116.It Cm uid Ns = Ns Ar uid
117Specifies user for
118.Cm masquerade
119mode.
120.El
121.El
122.Pp
123To enforce file system security, the user mounting a file system
124must be superuser or else have write permission on the mounted-on
125directory.
126In addition, the
127.Va vfs.usermount
128.Xr sysctl 8
129variable must be set to 1 to permit file system mounting by ordinary users.
130However, note that
131.Cm transparent
132and
133.Cm masquerade
134modes require
135.Va vfs.usermount
136to be set to 0 because this functionality can only be used by superusers.
137.Pp
138Filenames are looked up in the upper layer and then in the
139lower layer.
140If a directory is found in the lower layer, and there is no entry
141in the upper layer, then a
142.Em shadow
143directory will be created in the upper layer.
144The ownership and the mode bits are set depending on the
145.Cm copymode
146option.
147In
148.Cm traditional
149mode, it will be owned by the user who originally did the
150union mount, with mode 0777
151.Pq Dq Li rwxrwxrwx
152modified by the umask in effect at that time.
153.Pp
154If a file exists in the upper layer then there is no way to access
155a file with the same name in the lower layer.
156If necessary, a combination of loopback and union mounts can be made
157which will still allow the lower files to be accessed by a different
158pathname.
159.Pp
160Except in the case of a directory,
161access to an object is granted via the normal file system access checks.
162For directories, the current user must have access to both the upper
163and lower directories (should they both exist).
164.Pp
165Requests to create or modify objects in
166.Ar uniondir
167are passed to the upper layer with the exception of a few special cases.
168An attempt to open for writing a file which exists in the lower layer
169causes a copy of the
170.Em entire
171file to be made to the upper layer, and then for the upper layer copy
172to be opened.
173Similarly, an attempt to truncate a lower layer file to zero length
174causes an empty file to be created in the upper layer.
175Any other operation which would ultimately require modification to
176the lower layer fails with
177.Er EROFS .
178.Pp
179The union file system manipulates the namespace, rather than
180individual file systems.
181The union operation applies recursively down the directory tree
182now rooted at
183.Ar uniondir .
184Thus any file systems which are mounted under
185.Ar uniondir
186will take part in the union operation.
187This differs from the
188.Cm union
189option to
190.Xr mount 8
191which only applies the union operation to the mount point itself,
192and then only for lookups.
193.Sh MASQUERADE MODE
194When a file
195(or a directory)
196is created in the upper layer, the
197.Cm masquerade
198mode sets it the fixed access mode bits given in
199.Cm ufile
200(for files)
201or
202.Cm udir
203(for directories)
204option and the owner given in
205.Cm udir
206and
207.Cm gid
208options, instead of ones in the lower layer.
209Note that in the
210.Cm masquerade
211mode and when owner of the file or directory matches
212one specified in
213.Cm uid
214option, only mode bits for the owner will be modified.
215More specifically, the file mode bits in the upper layer will
216be
217(mode in the lower layer)
218OR
219(mode given in
220.Cm ufile
221AND 0700), and the ownership will be the same as one in the lower layer.
222.Pp
223The default values for
224.Cm ufile , udir , uid ,
225and
226.Cm gid
227are as follow:
228.Pp
229.Bl -bullet -compact
230.It
231If none of
232.Cm ufile
233and
234.Cm udir
235were specified, access mode bits in the mount point will be used.
236.It
237If none of
238.Cm uid
239and
240.Cm gid
241were specified, ownership in the mount point will be used.
242.It
243If one of
244.Cm udir
245or
246.Cm ufile
247is not specified, the value of the other option will be used.
248.It
249If one of
250.Cm uid
251or
252.Cm gid
253is not specified, the value of the other option will be used.
254.El
255.Sh EXAMPLES
256The commands
257.Bd -literal -offset indent
258mount -t cd9660 -o ro /dev/cd0 /usr/src
259mount -t unionfs -o noatime /var/obj /usr/src
260.Ed
261.Pp
262mount the CD-ROM drive
263.Pa /dev/cd0
264on
265.Pa /usr/src
266and then attaches
267.Pa /var/obj
268on top.
269For most purposes the effect of this is to make the
270source tree appear writable
271even though it is stored on a CD-ROM.
272The
273.Fl o Cm noatime
274option is useful to avoid unnecessary copying from the lower to the
275upper layer.
276.Pp
277The commands
278.Bd -literal -offset indent
279mount -t cd9660 -o ro /dev/cd0 /usr/src
280chown 2020 /usr/src
281mount -t unionfs -o noatime -o copymode=masquerade -o uid=builder \\
282    -o udir=755 -o ufile=644 /var/obj /usr/src
283.Ed
284.Pp
285also mount the CD-ROM drive
286.Pa /dev/cd0
287on
288.Pa /usr/src
289and then attaches
290.Pa /var/obj
291on top.
292Furthermore, the owner of all files and directories in
293.Pa /usr/src
294is a regular user with UID 2020
295when seen from the upper layer.
296Note that for the access mode bits,
297ones in the lower layer
298(on the CD-ROM, in this example)
299are still used without change.
300Thus, write privilege to the upper layer can be controlled
301independently from access mode bits and ownership in the lower layer.
302If a user does not have read privilege from the lower layer,
303one cannot still read even when the upper layer is mounted by using
304.Cm masquerade
305mode.
306.Pp
307The command
308.Bd -literal -offset indent
309mount -t unionfs -o noatime -o below /sys $HOME/sys
310.Ed
311.Pp
312attaches the system source tree below the
313.Pa sys
314directory in the user's home directory.
315This allows individual users to make private changes
316to the source, and build new kernels, without those
317changes becoming visible to other users.
318Note that the files in the lower layer remain
319accessible via
320.Pa /sys .
321.Sh SEE ALSO
322.Xr intro 2 ,
323.Xr mount 2 ,
324.Xr unmount 2 ,
325.Xr fstab 5 ,
326.Xr mount 8 ,
327.Xr mount_nullfs 8
328.Sh HISTORY
329The
330.Nm mount_null
331utility first appeared in
332.Bx 4.4 .
333It was renamed to
334.Nm
335in
336.Fx 5.0 .
337.Pp
338The
339.Fl r
340option for hiding the lower layer completely was removed in
341.Fx 7.0
342because this is identical to using
343.Xr mount_nullfs 8 .
344.Sh AUTHORS
345.An -nosplit
346In
347.Fx 7.0 ,
348.An Masanori OZAWA Aq Mt ozawa@ongs.co.jp
349reimplemented handling of locking, whiteout, and file mode bits, and
350.An Hiroki Sato Aq Mt hrs@FreeBSD.org
351wrote about the changes in this manual page.
352.Sh BUGS
353THIS FILE SYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK)
354AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM.
355USE AT YOUR OWN RISK.
356.Pp
357This code also needs an owner in order to be less dangerous - serious
358hackers can apply by sending mail to
359.Aq Mt freebsd-fs@FreeBSD.org
360and announcing
361their intent to take it over.
362.Pp
363Without whiteout support from the file system backing the upper layer,
364there is no way that delete and rename operations on lower layer
365objects can be done.
366.Er EOPNOTSUPP
367is returned for this kind of operations as generated by VOP_WHITEOUT()
368along with any others which would make modifications to the lower
369layer, such as
370.Xr chmod 1 .
371.Pp
372Running
373.Xr find 1
374over a union tree has the side-effect of creating
375a tree of shadow directories in the upper layer.
376.Pp
377The current implementation does not support copying extended attributes
378for
379.Xr acl 9 ,
380.Xr mac 9 ,
381or so on to the upper layer.
382Note that this may be a security issue.
383.Pp
384A shadow directory, which is one automatically created in the upper
385layer when it exists in the lower layer and does not exist in the
386upper layer, is always created with the superuser privilege.
387However, a file copied from the lower layer in the same way
388is created by the user who accessed it.
389Because of this,
390if the user is not the superuser, even in
391.Cm transparent
392mode the access mode bits in the copied file in the upper layer
393will not always be the same as ones in the lower layer.
394This behavior should be fixed.
395