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