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.
6 .\" Copyright (c) 2019 The FreeBSD Foundation
8 .\" Portions of this documentation were written by BFF Storage Systems under
9 .\" sponsorship from the FreeBSD Foundation.
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\" notice, this list of conditions and the following disclaimer.
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\" notice, this list of conditions and the following disclaimer in the
18 .\" documentation and/or other materials provided with the distribution.
19 .\" 3. Neither the name of the University nor the names of its contributors
20 .\" may be used to endorse or promote products derived from this software
21 .\" without specific prior written permission.
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
40 .Nd mount a Fuse file system daemon
46 .Op Fl D Ar fuse_daemon
47 .Op Fl O Ar daemon_opts
52 .Op Fl o Ar option ...
54 .Op Ar fuse_daemon ...
56 Basic usage is to start a fuse daemon on the given
59 In practice, the daemon is assigned a
61 file automatically, which can then be identified via
63 That special file can then be mounted by
66 However, the procedure of spawning a daemon will usually be automated
67 so that it is performed by
69 If the command invoking a given
71 is appended to the list of arguments,
78 will be instructed to attach itself to
80 From that on mounting goes as in the simple case. (See
85 argument will normally be treated as the path of the special file to mount.
93 will look for a suitable free fuse device by itself.
97 is an integer it will be interpreted as the number
98 of the file descriptor of an already open fuse device
99 (used when the Fuse library invokes
102 .Sx DAEMON MOUNTS ) .
104 The options are as follows:
105 .Bl -tag -width indent
106 .It Fl A , Ic --reject-allow_other
110 Intended for use in scripts and the
111 .Xr sudoers 5 Pq Pa ports/security/sudo
114 Run in safe mode (i.e., reject invoking a filesystem daemon).
117 .It Fl D , Ic --daemon Ar daemon
120 .It Fl O , Ic --daemon_opts Ar opts
123 to the daemon's command line.
124 .It Fl s , Ic --special Ar special
128 .It Fl m , Ic --mountpath Ar node
133 .It Fl V , Ic --version
134 Show version information.
136 Mount options are specified via
138 The following options are available (and also their negated versions,
139 by prefixing them with
141 .Bl -tag -width indent
144 .Sx STRICT ACCESS POLICY .
145 Only root can use this option.
147 I/O to the file system may be done asynchronously.
148 Writes may be delayed and/or reordered.
149 .It Cm default_permissions
150 Enable traditional (file mode based) permission checking in kernel.
152 Allow signals to interrupt operations that are blocked waiting for a reply from the server.
153 When this option is in use, system calls may fail with
155 whenever a signal is received.
156 .It Cm max_read Ns = Ns Ar n
157 Limit size of read requests to
159 .It Cm neglect_shares
160 Do not refuse unmounting if there are secondary mounts.
162 Refuse shared mounting of the daemon.
163 This is the default behaviour, to allow sharing, explicitly use
165 .It Cm push_symlinks_in
166 Prefix absolute symlinks with the mountpoint.
167 .It Cm subtype Ns = Ns Ar fsname
170 to the file system name as reported by
172 This option can be used to identify the file system implemented by
177 Besides the above mount options, there is a set of pseudo-mount options which
178 are supported by the Fuse library.
179 One can list these by passing
182 Most of these options only have effect on the behavior of the daemon (that is,
183 their scope is limited to userspace).
184 However, there are some which do require in-kernel support.
185 Currently the options supported by the kernel are:
186 .Bl -tag -width indent
188 Bypass the buffer cache system.
190 By default cached buffers of a given file are flushed at each
192 This option disables this behaviour.
195 Usually users do not need to use
197 directly, as the Fuse library enables Fuse daemons to invoke
201 .Dl fuse_daemon device mountpoint
203 has the same effect as
205 .Dl mount_fusefs auto mountpoint fuse_daemon
207 This is the recommended usage when you want basic usage
208 (eg, run the daemon at a low privilege level but mount it as root).
209 .Sh STRICT ACCESS POLICY
210 The strict access policy for Fuse filesystems lets one use the filesystem
211 only if the filesystem daemon has the same credentials (uid, real uid, gid,
212 real gid) as the user.
214 This is applied for Fuse mounts by default and only root can mount without
215 the strict access policy (i.e., the
219 This is to shield users from the daemon
221 on their I/O activities.
223 Users might opt to willingly relax strict access policy (as far as they
224 are concerned) by doing their own secondary mount (See
225 .Sx SHARED MOUNTS ) .
227 A Fuse daemon can be shared (i.e., mounted multiple times).
228 When doing the first (primary) mount, the spawner and the mounter of the daemon
229 must have the same uid, or the mounter should be the superuser.
231 After the primary mount is in place, secondary mounts can be done by anyone
232 unless this feature is disabled by
234 The behaviour of a secondary mount is analogous to that of symbolic
235 links: they redirect all filesystem operations to the primary mount.
237 Doing a secondary mount is like signing an agreement: by this action, the mounter
238 agrees that the Fuse daemon can trace her I/O activities.
239 From then on she is not banned from using the filesystem
240 (either via her own mount or via the primary mount), regardless whether
244 The device name of a secondary mount is the device name of the corresponding
245 primary mount, followed by a '#' character and the index of the secondary
249 System administrators might want to use a custom mount policy (ie., one going
253 The primary tool for such purposes is
254 .Xr sudo 8 Pq Pa ports/security/sudo .
257 is capable of invoking an arbitrary program, one must be careful when doing this.
259 is designed in a way such that it makes that easy.
260 For this purpose, there are options which disable certain risky features
264 and command line parsing is done in a flexible way: mixing options and
265 non-options is allowed, but processing them stops at the third non-option
266 argument (after the first two have been utilized as device and mountpoint).
267 The rest of the command line specifies the daemon and its arguments.
268 (Alternatively, the daemon, the special and the mount path can be
269 specified using the respective options.) Note that
271 ignores the environment variable
273 and always behaves as described.
275 In general, to be as scripting /
276 .Xr sudoers 5 Pq Pa ports/security/sudo
277 friendly as possible, no information has a fixed
278 position in the command line, but once a given piece of information is
279 provided, subsequent arguments/options cannot override it (with the
280 exception of some non-critical ones).
282 .Bl -tag -width ".Ev MOUNT_FUSEFS_SAFE"
283 .It Ev MOUNT_FUSEFS_SAFE
284 This has the same effect as the
287 .It Ev MOUNT_FUSEFS_VERBOSE
288 This has the same effect as the
291 .It Ev MOUNT_FUSEFS_IGNORE_UNKNOWN
294 will ignore unknown mount options.
295 .It Ev MOUNT_FUSEFS_CALL_BY_LIB
296 Adjust behavior to the needs of the FUSE library.
297 Currently it effects help output.
300 Although the following variables do not have any effect on
302 itself, they affect the behaviour of fuse daemons:
303 .Bl -tag -width ".Ev FUSE_DEV_NAME"
306 If not set, the multiplexer path
310 File descriptor of an opened Fuse device to use.
314 If set, the library will not attempt to mount the filesystem, even
315 if a mountpoint argument is supplied.
318 .Bl -tag -width /dev/fuse
320 Fuse device with which the kernel and Fuse daemons can communicate.
322 The multiplexer path.
325 performed on it automatically is passed to a free Fuse device by the kernel
326 (which might be created just for this puprose).
329 Mount the example filesystem in the Fuse distribution (from its directory):
332 .Dl ./fusexmp /mnt/fuse
336 .Dl mount_fusefs auto /mnt/fuse ./fusexmp
338 Doing the same in two steps, using
341 .Dl FUSE_DEV_NAME=/dev/fuse ./fusexmp &&
342 .Dl mount_fusefs /dev/fuse /mnt/fuse
344 A script wrapper for fusexmp which ensures that
346 does not call any external utility and also provides a hacky
347 (non race-free) automatic device selection:
351 .Dl FUSE_DEV_NAME=/dev/fuse fusexmp
352 .Dl mount_fusefs -S /dev/fuse /mnt/fuse \(lq$@\(rq
356 .Xr sudo 8 Pq Pa ports/security/sudo ,
360 was written as the part of the
362 implementation of the Fuse userspace filesystem framework (see
363 .Lk https://github.com/libfuse/libfuse )
364 and first appeared in the
365 .Pa sysutils/fusefs-kmod
368 It was added to the base system in
371 This user interface is
374 Secondary mounts should be unmounted via their device name.
375 If an attempt is made to unmount them via their filesystem root path,
376 the unmount request will be forwarded to the primary mount path.
377 In general, unmounting by device name is less error-prone than by mount path
378 (although the latter will also work under normal circumstances).
380 If the daemon is specified via the
384 options, it will be invoked via
386 and the daemon's command line will also have an
388 control operator appended, so that we do not have to wait for its termination.
389 You should use a simple command line when invoking the daemon via these options.
392 is treated as a multiplexer if and only if it is literally the same as
396 Other paths which are equivalent with