xref: /freebsd/sbin/mount_fusefs/mount_fusefs.8 (revision 298f5fdc242b760e70cd3494e3a4f1f50b20664d)
1.\" Copyright (c) 1980, 1989, 1991, 1993
2.\"	The Regents of the University of California.
3.\" Copyright (c) 2005, 2006 Csaba Henk
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 4. Neither the name of the University nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\" $FreeBSD$
31.\"
32.Dd October 11, 2012
33.Dt MOUNT_FUSEFS 8
34.Os
35.Sh NAME
36.Nm mount_fusefs
37.Nd mount a Fuse file system daemon
38.Sh SYNOPSIS
39.Nm
40.Op Fl A
41.Op Fl S
42.Op Fl v
43.Op Fl D Ar fuse_daemon
44.Op Fl O Ar daemon_opts
45.Op Fl s Ar special
46.Op Fl m Ar node
47.Op Fl h
48.Op Fl V
49.Op Fl o Ar option ...
50.Ar special node
51.Op Ar fuse_daemon ...
52.Sh DESCRIPTION
53Basic usage is to start a fuse daemon on the given
54.Ar special
55file.  In practice, the daemon is assigned a
56.Ar special
57file automatically, which can then be indentified via
58.Xr fstat 1 .
59That special file can then be mounted by
60.Nm .
61.Pp
62However, the procedure of spawning a daemon will usually be automated
63so that it is performed by
64.Nm .
65If the command invoking a given
66.Ar fuse_daemon
67is appended to the list of arguments,
68.Nm
69will call the
70.Ar fuse_daemon
71via that command.  In that way the
72.Ar fuse_daemon
73will be instructed to attach itself to
74.Ar special .
75From that on mounting goes as in the simple case. (See
76.Sx DAEMON MOUNTS . )
77.Pp
78The
79.Ar special
80argument will normally be treated as the path of the special file to mount.
81.Pp
82However, if
83.Pa auto
84is passed as
85.Ar special ,
86then
87.Nm
88will look for a suitable free fuse device by itself.
89.Pp
90Finally, if
91.Ar special
92is an integer it will be interpreted as the number
93of the file descriptor of an already open fuse device
94(used when the Fuse library invokes
95.Nm .
96(See
97.Sx DAEMON MOUNTS ) .
98.Pp
99The options are as follows:
100.Bl -tag -width indent
101.It Fl A , Ic --reject-allow_other
102Prohibit the
103.Cm allow_other
104mount flag. Intended for use in scripts and the
105.Xr sudoers 5
106file.
107.It Fl S , Ic --safe
108Run in safe mode (i.e. reject invoking a filesystem daemon)
109.It Fl v
110Be verbose
111.It Fl D, Ic --daemon Ar daemon
112Call the specified
113.Ar daemon
114.It Fl O, Ic --daemon_opts Ar opts
115Add
116.Ar opts
117to the daemon's command line
118.It Fl s, Ic --special Ar special
119Use
120.Ar special
121as special
122.It Fl m, Ic --mountpath Ar node
123Mount on
124.Ar node
125.It Fl h, Ic --help
126Show help
127.It Fl V, Ic --version
128Show version information
129.It Fl o
130Mount options are specified via
131.Fl o .
132The following options are available (and also their negated versions,
133by prefixing them with
134.Dq no ) :
135.Bl -tag -width indent
136.It Cm default_permissions
137Enable traditional (file mode based) permission checking in kernel
138.It Cm allow_other
139Do not apply
140.Sx STRICT ACCESS POLICY .
141Only root can use this option
142.It Cm max_read Ns = Ns Ar n
143Limit size of read requests to
144.Ar n
145.It Cm private
146Refuse shared mounting of the daemon. This is the default behaviour,
147to allow sharing, expicitly use
148.Fl o Cm noprivate
149.It Cm neglect_shares
150Do not refuse unmounting if there are secondary mounts
151.It Cm push_symlinks_in
152Prefix absolute symlinks with the mountpoint
153.El
154.El
155.Pp
156Besides the above mount options, there is a set of pseudo-mount options which
157are supported by the Fuse library. One can list these by passing
158.Fl h
159to a Fuse daemon. Most of these options have effect only on the behaviour of
160the daemon (that is, their scope is limited to userspace). However,
161there are some which do require in-kernel support.
162Currently the options supported by the kernel are:
163.Bl -tag -width indent
164.It Cm direct_io
165Bypass the buffer cache system
166.It Cm kernel_cache
167By default cached buffers of a given file are flushed at each
168.Xr open 2 .
169This option disables this behaviour
170.El
171.Sh DAEMON MOUNTS
172Usually users do not need to use
173.Nm
174directly, as the Fuse library enables Fuse daemons to invoke
175.Nm .
176That is,
177.Pp
178.Dl fuse_daemon device mountpoint
179.Pp
180has the same effect as
181.Pp
182.Dl mount_fusefs auto mountpoint fuse_daemon
183.Pp
184This is the recommended usage when you want basic usage
185(eg, run the daemon at a low privilege level but mount it as root).
186.Sh STRICT ACCESS POLICY
187The strict access policy for Fuse filesystems lets one to use the filesystem
188only if the filesystem daemon has the same credentials (uid, real uid, gid,
189real gid) as the user.
190.Pp
191This is applied for Fuse mounts by default and only root can mount without
192the strict access policy (ie. the
193.Cm allow_other
194mount option).
195.Pp
196This is to shield users from the daemon
197.Dq spying
198on their I/O activities.
199.Pp
200Users might opt to willingly relax strict access policy (as far they
201are concerned) by doing their own secondary mount (See
202.Sx SHARED MOUNTS ) .
203.Sh SHARED MOUNTS
204A Fuse daemon can be shared (ie. mounted multiple times).
205When doing the first (primary) mount, the spawner and the mounter of the daemon
206must have the same uid, or the mounter should be the superuser.
207.Pp
208After the primary mount is in place, secondary mounts can be done by anyone
209unless this feature is disabled by
210.Cm private .
211The behaviour of a secondary mount is analogous to that of symbolic
212links: they redirect all filesystem operations to the primary mount.
213.Pp
214Doing a secondary mount is like signing an agreement: by this action, the mounter
215agrees that the Fuse daemon can trace her I/O activities. From then on
216she is not banned from using the filesystem (either via her own mount or
217via the primary mount), regardless whether
218.Cm allow_other
219is used or not.
220.Pp
221The device name of a secondary mount is the device name of the corresponding
222primary mount, followed by a '#' character and the index of the secondary
223mount; e.g.
224.Pa /dev/fuse0#3 .
225.Sh SECURITY
226System administrators might want to use a custom mount policy (ie., one going
227beyond the
228.Va vfs.usermount
229sysctl). The primary tool for such purposes is
230.Xr sudo 8 .
231However, given that
232.Nm
233is capable of invoking an arbitrary program, one must be careful when doing this.
234.Nm
235is designed in a way such that it makes that easy. For this purpose,
236there are options which disable certain risky features (ie.
237.Fl S
238and
239.Fl A ) ,
240and command line parsing is done in a flexible way: mixing options and
241non-options is allowed, but processing them stops at the third non-option
242argument (after the first two has been utilized as device and mountpoint).
243The rest of the command line specifies the daemon and its arguments.
244(Alternatively, the daemon, the special and the mount path can be
245specified using the respective options.) Note that
246.Nm
247ignores the environment variable
248.Ev POSIXLY_CORRECT
249and always behaves as described.
250.Pp
251In general, to be as scripting /
252.Xr sudoers 5
253friendly as possible, no information has a fixed
254position in the command line, but once a given piece of information is
255provided, subsequent arguments/options cannot override it (with the
256exception of some non-critical ones).
257.Sh ENVIRONMENT
258.Bl -tag -width ".Ev MOUNT_FUSEFS_SAFE"
259.It Ev MOUNT_FUSEFS_SAFE
260This has the same effect as the
261.Fl S
262option.
263.It Ev MOUNT_FUSEFS_VERBOSE
264This has the same effect as the
265.Fl v
266option.
267.It Ev MOUNT_FUSEFS_IGNORE_UNKNOWN
268If set,
269.Nm
270will ignore uknown mount options.
271.It Ev MOUNT_FUSEFS_CALL_BY_LIB
272Adjust behaviour to the needs of the FUSE library. Currently it effects
273help output.
274.El
275.Pp
276Although the following variables do not have any effect on
277.Nm
278itself, they affect the behaviour of fuse daemons:
279.Bl -tag -width ".Ev FUSE_DEV_NAME"
280.It Ev FUSE_DEV_NAME
281Device to attach. If not set, the multiplexer path
282.Ar /dev/fuse
283is used.
284.It Ev FUSE_DEV_FD
285File desciptor of an opened Fuse device to use. Overrides
286.Ev FUSE_DEV_NAME .
287.It Ev FUSE_NO_MOUNT
288If set, the library will not attempt to mount the filesystem, even
289if a mountpoint argument is supplied.
290.El
291.Sh FILES
292.Bl -tag -width /dev/fuse
293.It Pa /dev/fuse
294Fuse device with which the kernel and Fuse daemons can communicate.
295.It Pa /dev/fuse
296The multiplexer path. An
297.Xr open 2
298performed on it automatically is passed to a free Fuse device by the kernel
299(which might be created just for this puprose).
300.El
301.Sh EXAMPLES
302Mount the example filesystem in the Fuse distribution (from its directory):
303either
304.Pp
305.Dl ./fusexmp /mnt/fuse
306.Pp
307or
308.Pp
309.Dl mount_fusefs auto /mnt/fuse ./fusexmp
310.Pp
311Doing the same in two steps, using
312.Pa /dev/fuse0 :
313.Pp
314.Dl FUSE_DEV_NAME=/dev/fuse ./fusexmp &&
315.Dl mount_fusefs /dev/fuse /mnt/fuse
316.Pp
317A script wrapper for fusexmp which ensures that
318.Nm
319does not call any external utility and also provides a hacky
320(non race-free) automatic device selection:
321.Pp
322.Dl #!/bin/sh -e
323.Pp
324.Dl FUSE_DEV_NAME=/dev/fuse fusexmp
325.Dl mount_fusefs -S /dev/fuse /mnt/fuse \(lq$@\(rq
326.Sh SEE ALSO
327.Xr fstat 1 ,
328.Xr mount 8 ,
329.Xr umount 8 ,
330.Xr sudo 8
331.Sh HISTORY
332.Nm
333appears as the part of the FreeBSD implementation of the Fuse userspace filesystem
334framework (see http://fuse.sourceforge.net). This user interface is FreeBSD specific.
335.Sh CAVEATS
336Secondary mounts should be unmounted via their device name. If an attempt is
337made to be unmount them via their filesystem root path, the unmount request
338will be forwarded to the primary mount path.
339In general, unmounting by device name is less error-prone than by mount path
340(although the latter will also work under normal circumstances).
341.Pp
342If the daemon is specified via the
343.Fl D
344and
345.Fl O
346options, it will be invoked via
347.Xr system 3 ,
348and the daemon's command line will also have an
349.Dq &
350control operator appended, so that we do not have to wait for its termination.
351You should use a simple command line when invoking the daemon via these options.
352.Sh BUGS
353.Ar special
354is treated as a multiplexer if and only if it is literally the same as
355.Pa auto
356or
357.Pa /dev/fuse .
358Other paths which are equivalent with
359.Pa /dev/fuse
360(eg.,
361.Pa /../dev/fuse )
362are not.
363