MOUNT_FUSEFS(8)

💅 MOUNT_FUSEFS — mount a Fuse file system daemon

okay bestie so this is MOUNT_FUSEFS(8), from the System Manager's Manual, and it's literally the tool that mounts your Fuse daemon's file system. it's giving "matchmaker between your daemon and your kernel" energy and honestly? iconic. let's go ✨

---

🎀 SYNOPSIS

mount_fusefs [-A] [-S] [-v] [-D fuse_daemon] [-O daemon_opts]
             [-s special] [-m node] [-h] [-V] [-o option ...] special
             node [fuse_daemon ...]

---

🦋 DESCRIPTION

so the basic vibe is: you start a fuse daemon on the given special file. in practice the daemon gets handed a special file automatically, and you can then find out which one it is via fstat(1). then mount_fusefs mounts that special file. easy. 🫶

but like — spawning a daemon is usually automated, so most of the time mount_fusefs does it for you. if the command that invokes a given fuse_daemon is tacked onto the end of the argument list, mount_fusefs will call the fuse_daemon through that command. that way the fuse_daemon gets told to attach itself to special. from there on out, mounting goes exactly like the simple case. (peep "DAEMON MOUNTS" below 👀)

the special argument is normally treated as the path of the special file to mount.

but — if auto is passed as special, then mount_fusefs goes looking for a suitable free fuse device all by itself. main character energy, honestly.

and finally, if special is an integer, it gets interpreted as the number of the file descriptor of an already-open fuse device (that's what happens when the Fuse library invokes mount_fusefs. see "DAEMON MOUNTS").

the options are as follows, bestie:

---

✨ OPTIONS ✨

• -A, --reject-allow_other — prohibits the allow_other mount flag. it's intended for use in scripts and the sudoers(5) (ports/security/sudo) file. no sneaky allow_other business 💀
• -S, --safe — runs in safe mode, meaning it rejects invoking a filesystem daemon. safe queen behavior 👑
• -v — be verbose. spill the tea about what's happening.
• -D, --daemon daemon — calls the specified daemon.
• -O, --daemon_opts opts — adds opts to the daemon's command line.
• -s, --special special — uses special as special.
• -m, --mountpath node — mounts on node.
• -h, --help — shows help.
• -V, --version — shows version info.
• -o — mount options go through -o. here's what's available (and also their negated versions, which you get by slapping a no prefix on them, iykyk):
  • allow_other — do not apply the "STRICT ACCESS POLICY". only root can use this one, no cap.
  • async — I/O to the file system may be done asynchronously. writes may be delayed and/or reordered. chaotic but valid ✨
  • default_permissions — enables traditional (file mode based) permission checking in the kernel.
  • intr — allows signals to interrupt operations that are blocked waiting for a reply from the server. when this option is in use, system calls may fail with EINTR whenever a signal is received.
  • max_read=n — limits the size of read requests to n.
  • neglect_shares — don't refuse unmounting if there are secondary mounts.
  • private — refuses shared mounting of the daemon. this is the default behaviour; to allow sharing, you explicitly use -o noprivate.
  • push_symlinks_in — prefixes absolute symlinks with the mountpoint.
  • subtype=fsname — suffixes fsname to the file system name as reported by statfs(2). this option can be used to identify the file system implemented by fuse_daemon. super handy 🎀

besides all the above mount options, there's a whole set of pseudo-mount options that the Fuse library supports. you can list them by passing -h to a Fuse daemon. most of these options only affect the daemon's behavior (i.e. their scope is limited to userspace). however, some of them do require in-kernel support. currently the options supported by the kernel are:

• direct_io — bypasses the buffer cache system. direct. no middleman. 💅
• kernel_cache — by default, cached buffers of a given file are flushed at each open(2). this option disables that behaviour.

---

🌸 DAEMON MOUNTS

usually you don't need to use mount_fusefs directly, because the Fuse library lets Fuse daemons invoke mount_fusefs themselves. so like, this:

fuse_daemon device mountpoint

has the same effect as this:

mount_fusefs auto mountpoint fuse_daemon

and that^ is the recommended usage when you want the basic setup (eg, run the daemon at a low privilege level but mount it as root). chef's kiss 🧑‍🍳💋

---

💜 STRICT ACCESS POLICY

the strict access policy for Fuse filesystems means you can only use the filesystem if the filesystem daemon has the same credentials (uid, real uid, gid, real gid) as the user. matching outfits only, bestie. 👯

this is applied to Fuse mounts by default, and only root can mount without the strict access policy (i.e. the allow_other mount option).

the whole point is to shield users from a daemon "spying" on their I/O activities. 🙈 no surveillance vibes allowed.

users might opt to willingly relax the strict access policy (as far as they're concerned) by doing their own secondary mount — see "SHARED MOUNTS" below.

---

🦋 SHARED MOUNTS

a Fuse daemon can be shared, meaning mounted multiple times. when you do the first (primary) mount, the spawner and the mounter of the daemon must have the same uid, or the mounter should be the superuser.

once the primary mount is in place, secondary mounts can be done by anyone, unless this feature is disabled by private. the behaviour of a secondary mount is analogous to symbolic links: they redirect all filesystem operations to the primary mount.

doing a secondary mount is basically signing an agreement: by doing it, the mounter agrees that the Fuse daemon can trace her I/O activities. from then on she's not banned from using the filesystem (either via her own mount or via the primary mount), regardless of whether allow_other is used or not.

the device name of a secondary mount is the device name of the corresponding primary mount, followed by a # character and the index of the secondary mount; e.g., /dev/fuse0#3. cute little naming convention fr fr.

---

🔥 SECURITY

system administrators might want to use a custom mount policy (i.e. one that goes beyond the vfs.usermount sysctl). the primary tool for that is sudo(8) (ports/security/sudo). however, given that mount_fusefs is capable of invoking an arbitrary program, you gotta be careful when doing this. mount_fusefs is designed in a way that makes that easy, though — for this purpose there are options that disable certain risky features (-S and -A), and command line parsing is done in a flexible way: mixing options and non-options is allowed, but processing them stops at the third non-option argument (after the first two have been utilized as device and mountpoint). the rest of the command line specifies the daemon and its arguments. (alternatively, the daemon, the special and the mount path can be specified using the respective options.) note that mount_fusefs ignores the environment variable POSIXLY_CORRECT and always behaves as described. it said what it said. 💅

in general, to be as scripting / sudoers(5) (ports/security/sudo) friendly as possible, no piece of information has a fixed position in the command line, but once a given piece of information is provided, subsequent arguments/options cannot override it (with the exception of some non-critical ones).

---

🌈 ENVIRONMENT

• MOUNT_FUSEFS_SAFE — this has the same effect as the -S option.
• MOUNT_FUSEFS_VERBOSE — this has the same effect as the -v option.
• MOUNT_FUSEFS_IGNORE_UNKNOWN — if set, mount_fusefs will ignore unknown mount options.
• MOUNT_FUSEFS_CALL_BY_LIB — adjusts behavior to the needs of the FUSE library. currently it affects help output.

although the following variables don't have any effect on mount_fusefs itself, they do affect the behaviour of fuse daemons:

• FUSE_DEV_NAME — device to attach. if not set, the multiplexer path /dev/fuse is used.
• FUSE_DEV_FD — file descriptor of an opened Fuse device to use. overrides FUSE_DEV_NAME. boss move.
• FUSE_NO_MOUNT — if set, the library will not attempt to mount the filesystem, even if a mountpoint argument is supplied.

---

🍓 FILES

• /dev/fuse — Fuse device with which the kernel and Fuse daemons can communicate. 🫶
• /dev/fuse — the multiplexer path. an open(2) performed on it is automatically passed to a free Fuse device by the kernel (which might be created just for this purpose). yes it's listed twice, that's how the original rolls, don't come for me 😭

---

⭐ EXAMPLES

mount the example filesystem in the Fuse distribution (from its directory): either

./fusexmp /mnt/fuse

or

mount_fusefs auto /mnt/fuse ./fusexmp

doing the same in two steps, using /dev/fuse0:

FUSE_DEV_NAME=/dev/fuse ./fusexmp &&
mount_fusefs /dev/fuse /mnt/fuse

a script wrapper for fusexmp which ensures that mount_fusefs does not call any external utility and also provides a hacky (non race-free) automatic device selection:

#!/bin/sh -e

FUSE_DEV_NAME=/dev/fuse fusexmp
mount_fusefs -S /dev/fuse /mnt/fuse “$@”

---

👑 SEE ALSO

fstat(1), mount(8), sudo(8) (ports/security/sudo), umount(8)

---

🧚 HISTORY

mount_fusefs was written as part of the FreeBSD implementation of the Fuse userspace filesystem framework (see https://github.com/libfuse/libfuse) and first appeared in the sysutils/fusefs-kmod port, supporting FreeBSD 6.0. it was added to the base system in FreeBSD 10.0. glow-up complete ✨

---

💀 CAVEATS

this user interface is FreeBSD specific. secondary mounts should be unmounted via their device name. if an attempt is made to unmount them via their filesystem root path, the unmount request will be forwarded to the primary mount path. in general, unmounting by device name is less error-prone than by mount path (although the latter will also work under normal circumstances). so like, device name. do it. 🙏

if the daemon is specified via the -D and -O options, it will be invoked via system(3), and the daemon's command line will also have an & control operator appended, so that we don't have to wait for its termination. you should use a simple command line when invoking the daemon via these options. keep it simple bestie, no cap.

---

😭 BUGS

special is treated as a multiplexer if and only if it is literally the same as auto or /dev/fuse. other paths which are equivalent with /dev/fuse (eg., /../dev/fuse) are not. literal means literal, she does not do vibes-based path matching 💀

---

and that's the whole page, bestie! go mount something iconic. 🦋💖

---

big cute sign-off: this page is from the Debian edition, dated October 9, 2021, and it's literally the MOUNT_FUSEFS(8) page from the System Manager's Manual. mwah 💋✨