fuse(8)

📦
version 3.18.3 · 5 versions
, in alpine 3.23, alpine 3.24, arch rolling, fedora 44, ubuntu stonking

💖 fuse(8) — System Manager's Manual 💖

okay bestie, welcome to fuse(8), the page that lives in the System Manager's Manual section. she's long, she's iconic, and she's about to make your whole filesystem situation make sense. grab a snack. 🍓

✨ NAME ✨

fuse — literally all the configuration and mount options for FUSE file systems. that's the whole vibe. 🫶

🌸 DESCRIPTION 🌸

okay so. FUSE stands for Filesystem in Userspace, and it is a simple interface for userspace programs to export a virtual filesystem to the Linux kernel. yes you read that right, you get to write a whole filesystem in userspace and the kernel will just… go along with it. main character energy fr. 👑

and that's not even the best part. FUSE also provides a secure method for non privileged users to create and mount their own filesystem implementations. so no, you do not need to be root, you do not need to beg anyone, you just get to do it. slay. 🌈

🎀 DEFINITIONS 🎀

bestie we have to get our vocabulary straight before we go any further, so here's the group chat glossary:

  • FUSE — the in-kernel filesystem that forwards requests to a user-space process. she's the messenger. she does not do the work, she just passes notes. 💌
  • filesystem — the user-space process that responds to requests received from the kernel. this one is actually doing the homework. 😭
  • libfuse — the shared library that most (user-space) filesystems use to communicate with FUSE (the kernel filesystem). and not only that, libfuse also provides the fusermount3 helper — or fusermount, if you have an older version of libfuse — which is what lets non-privileged users mount filesystems. so yeah, she's the one holding the door open for you. 🚪✨
  • filesystem owner — the user that starts the filesystem and instructs the kernel to associate it with a particular mountpoint. and when does that happen? typically the filesystem does it itself on start-up. and if you're using libfuse, it does that by calling the fusermount3 utility. so it's a whole chain of "not me doing it directly but yes me doing it". 💅
  • client — any process that interacts with the mountpoint. that could be literally anyone. could be you. could be a background daemon. could be a script you wrote at 3am. 👀

🦋 CONFIGURATION 🦋

okay so some options regarding mount policy can be set in the file /etc/fuse.conf. currently (yes, currently, as in right now, these are the ones we've got) these options are:

  • mount_max = NNN — sets the maximum number of FUSE mounts allowed to non-root users. the default is 1000. so like, a thousand mounts for the girlies who aren't root. no cap. 🔥
  • user_allow_other — allows non-root users to specify the allow_other or allow_root mount options (peep below for those, they're coming 👇).
⚠️ heads up bestie: these limits are enforced by the fusermount3 helper, so they can be avoided by filesystems that run as root. so if you're root, the rules just… don't apply to you. must be nice. 🙈

✨ OPTIONS ✨

okay so bestie, most of the generic mount options from mount are supported here: ro, rw, suid, nosuid, dev, nodev, exec, noexec, atime, noatime, sync, async, dirsync. 💅 Filesystems get mounted with nodev,nosuid by default, and only a privileged user can override that. periodt.

🌸 General mount options: 🌸

these are the FUSE-specific mount options and they work for all filesystems:

  • default_permissions — tells the kernel to do its own permission check instead of dumping all permission checking on the filesystem. and like, the kernel's check happens in addition to whatever checks the filesystem does — both have to pass or the operation gets denied. the kernel runs a standard UNIX permission check (based on mode bits and ownership of the directory entry, plus the uid/gid of the client).
this mount option gets activated implicitly if the filesystem turns on ACL support during the initial feature negotiation when opening the device fd. in that case, the kernel does both ACL and standard unix permission checking. 🎀

filesystems that don't implement any permission checking should generally add this option internally. iykyk.

  • allow_other — this one overrides the security measure that restricts file access to the filesystem owner, so that literally all users (root included 👑) can access the files.
  • rootmode=M — specifies the file mode of the filesystem's root (in octal representation).
  • blkdev — mount a filesystem backed by a block device. this is a privileged option. the device has to be specified with the fsname=NAME option.
  • blksize=N — set the block size for the filesystem. this option is only valid for 'fuseblk' type mounts. the default is 512.

in most cases, this option should not be specified by the filesystem owner but set internally by the filesystem. 💖

  • max_read=N — with this option the maximum size of read operations can be set. the default is infinite, but typically the kernel enforces its own limit on top of this one. a value of zero corresponds to no limit.

this option should not be specified by the filesystem owner. the correct (or optimum) value depends on the filesystem implementation and should thus be set by the filesystem internally.

this mount option is deprecated in favor of direct negotiation over the device fd (like what's done for e.g. the maximum size of write operations). for the time being, libfuse-using filesystems that want to limit the read size must therefore use this mount option and set the same value again in the init() handler. 💀
  • fd=N — the file descriptor to use for communication between the userspace filesystem and the kernel. this file descriptor must have been obtained by opening the FUSE device (/dev/fuse).

this option should not be specified by the filesystem owner. it's set by libfuse (or, if libfuse isn't used, it must be set by the filesystem itself).

  • user_id=N, group_id=N — specifies the numeric uid/gid of the mount owner.

this option should not be specified by the filesystem owner. it's set by libfuse (or, if libfuse isn't used, it must be set by the filesystem itself).

  • fsname=NAME — sets the filesystem source (that's the first field in /etc/mtab). the default is the name of the filesystem process.
  • subtype=TYPE — sets the filesystem type (third field in /etc/mtab). the default is the name of the filesystem process. if the kernel supports it, /etc/mtab and /proc/mounts will show the filesystem type as fuse.TYPE ✨

if the kernel doesn't support subtypes, the source field will be TYPE#NAME, or if the fsname option isn't specified, just TYPE.

🦋 libfuse-specific mount options: 🦋

these next ones are not actually passed to the kernel — they're interpreted by libfuse itself. they can be specified for all filesystems that use libfuse:

  • allow_root — similar to allow_other but file access is limited to the filesystem owner and root. this option and allow_other are mutually exclusive. 🙈
  • auto_unmount — enables automatic release of the mountpoint if the filesystem terminates for any reason. normally the filesystem is responsible for releasing the mountpoint, which means the mountpoint becomes inaccessible if the filesystem terminates without first unmounting.
⚠️ this option is dangerous and should only be used after careful consideration of the risks. like, for real for real.

automatically unmounting the filesystem means that if the filesystem crashes the mountpoint may suddenly appear empty, which may have unintended consequences. for example, a running backup and mirroring program may conclude that all the data in the filesystem has been deleted and proceed to propagate this deletion to the backup / remote system. if the mountpoint instead becomes inaccessible (the default), most programs will behave correctly (report an error).

this feature may also accidentally unmount the wrong filesystem due to race conditions. for example, if another filesystem was mounted underneath the same mountpoint, or if a new filesystem is mounted after the FUSE process has crashed, it may accidentally get unmounted. 😭

at the moment, this option implies that the filesystem will also be mounted with nodev and nosuid (even when mounted by root). this restriction may be lifted in the future.

💜 High-level mount options: 💜

these following options are also not actually passed to the kernel — libfuse interprets them — and they can only be specified for filesystems that use the high-level libfuse API:

  • kernel_cache — disables flushing the cache of the file contents on every open(2). this should only be enabled on filesystems where the file data is never changed externally (not through the mounted FUSE filesystem). so it's not suitable for network filesystems and other "intermediate" filesystems.
NOTE: if this option isn't specified (and neither is direct_io) data is still cached after the open(2), so a read(2) system call will not always initiate a read operation. 🧚
  • auto_cache — this option is an alternative to kernel_cache. instead of unconditionally keeping cached data, the cached data is invalidated on open(2) if the modification time or the size of the file has changed since it was last opened.
  • umask=M, fmask=M, dmask=M — override the permission bits set by the filesystem in st_mode. the resulting permission bits are the ones missing from the mask value, which is given in octal representation. fmask and dmask (respectively) may be used to control the permission bits of files and directories separately. umask is overridden by the individual fmask and dmask options.
  • uid=N — override the st_uid field set by the filesystem (N is numeric).
  • gid=N — override the st_gid field set by the filesystem (N is numeric).
  • entry_timeout=T — the timeout in seconds for which name lookups will be cached. the default is 1.0 second. for all the timeout options, it's possible to give fractions of a second as well (e.g. entry_timeout=2.8) 🍓
  • negative_timeout=T — the timeout in seconds for which a negative lookup will be cached. this means that if the file did not exist (lookup returned ENOENT), the lookup will only be redone after the timeout, and the file/directory will be assumed to not exist until then. the default is 0.0 second, meaning that caching negative lookups is disabled.
  • attr_timeout=T — the timeout in seconds for which file/directory attributes are cached. the default is 1.0 second.
  • ac_attr_timeout=T — the timeout in seconds for which file attributes are cached for the purpose of checking if auto_cache should flush the file data on open. the default is the value of attr_timeout.
  • noforget
  • remember=T — normally, libfuse assigns inodes to paths only for as long as the kernel is aware of them. with this option inodes are instead assigned for at least T seconds (or, in the case of noforget, the life-time of the filesystem). this will require more memory, but may be necessary when using applications that make use of inode numbers.
  • modules=M1[:M2...] — add modules to the filesystem stack. modules are pushed in the order they're specified, with the original filesystem being on the bottom of the stack. 📚

🎀 mount.fuse3 options: 🎀

these options are interpreted by mount.fuse3 and are thus only available when mounting a file system via mount.fuse3 (like when mounting via the generic mount(1) command or /etc/fstab). the supported options are:

  • setuid=USER — switch to USER and its primary group before launching the FUSE file system process. mount.fuse3 must be run as root or with CAP_SETUID and CAP_SETGID for this to work. 🔥
  • drop_privileges — perform setup of the FUSE file descriptor and mounting the file system before launching the FUSE file system process. mount.fuse3 requires privilege to do so, i.e. must be run as root or at least with CAP_SYS_ADMIN and CAP_SETPCAP. it will launch the file system process fully unprivileged, i.e. without capabilities(7) and prctl(2) flags set up such that privileges can't be reacquired (e.g. via setuid or fscaps binaries). this reduces risk in the event of the FUSE file system process getting compromised by malicious file system data. 💪

🧩 FUSE MODULES (STACKING)

okay so modules?? bestie they're literally the glow-up layer for the high level API 💅 They're filesystem stacking support for the high level API, and here's the tea: filesystem modules can be either built into libfuse or loaded from a shared object. Pick your fighter.

🎀 iconv

She does file name character set conversion ✨ Options are:

  • from_code=CHARSET — the character set you're converting from (peep iconv -l for the whole list of possible values, it's giving menu). Default is UTF-8.
  • to_code=CHARSET — the character set you're converting to. The default is determined by the current locale, so it's lowkey just vibing with wherever you are.

🦋 subdir

This one prepends a given directory to each path. Options are:

  • subdir=DIR — the directory to prepend to all paths. > 🚨 This option is mandatory. No subdir, no service, fr fr.
  • rellinks — transform absolute symlinks into relative ✨
  • norellinks — do not transform absolute symlinks into relative. This is the default, so if you don't say anything, she stays absolute.

🔒 SECURITY

So the fusermount3 program is installed set-user-gid to fuse. Why tho? To allow users from the fuse group to mount their own filesystem implementations 👑 iconic, generous, love that for us.

But bestie… there must however be some limitations, because otherwise Bad User™ could do nasty things 😭 and we are NOT letting that happen. Currently those limitations are:

  1. The user can only mount on a mountpoint for which it has write permission.
  2. The mountpoint is not a sticky directory which isn't owned by the user (like /tmp usually is 👀).
  3. No other user (including root) can access the contents of the mounted filesystem.
Three rules. That's the whole vibe check. Respect them or the whole thing falls apart 💀

📌 NOTE

FUSE filesystems are unmounted using the fusermount3(1) command, like this:

fusermount3 -u mountpoint

That's the move. Don't come for me, just use it 🙈

👑 AUTHORS

FUSE is currently maintained by Nikolaus Rath <Nikolaus@rath.org> 💜

The original author of FUSE is Miklos Szeredi <mszeredi@inf.bme.hu>. legends, both of them, no cap.

This man page was originally written by Bastien Roucaries <roucaries.bastien+debian@gmail.com> for the Debian GNU/Linux distribution 🎀 (ty for your service, bestie)

🌈 SEE ALSO

and that's a wrap on the fuse(8) girlies ✨ this whole page is dated and versioned down at the bottom in the footer like a little signature — so consider this my sign-off: it's the fuse(8) manual, and you've officially read the whole thing 💅🫶 go mount something iconic, bestie 🦋

📦 where this page comes from