2026-06-08 09:17 @216.73.217.65
CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
fuse(8) System Manager's Manual fuse(8) NAME fuse - configuration and mount options for FUSE file systems DESCRIPTION FUSE (Filesystem in Userspace) is a simple interface for userspace pro- grams to export a virtual filesystem to the Linux kernel. FUSE also aims to provide a secure method for non privileged users to create and mount their own filesystem implementations. DEFINITIONS FUSE The in-kernel filesystem that forwards requests to a user-space process. filesystem The user-space process that responds to requests received from the kernel. libfuse The shared library that most (user-space) filesystems use to communicate with FUSE (the kernel filesystem). libfuse also pro- vides the fusermount3 (or fusermount if you have older version of libfuse) helper to allow non-privileged users to mount filesystems. filesystem owner The user that starts the filesystem and instructs the kernel to associate it with a particular mountpoint. The latter is typi- cally done by the filesystem itself on start-up. When using lib- fuse, this is done by calling the fusermount3 utility. client Any process that interacts with the mountpoint. CONFIGURATION Some options regarding mount policy can be set in the file /etc/fuse.conf. Currently these options are: mount_max = NNN Set the maximum number of FUSE mounts allowed to non-root users. The default is 1000. user_allow_other Allow non-root users to specify the allow_other or allow_root mount options (see below). These limits are enforced by the fusermount3 helper, so they can be avoided by filesystems that run as root. OPTIONS Most of the generic mount options described in mount are supported (ro, rw, suid, nosuid, dev, nodev, exec, noexec, atime, noatime, sync, async, dirsync). Filesystems are mounted with nodev,nosuid by default, which can only be overridden by a privileged user. General mount options: These are FUSE specific mount options that can be specified for all filesystems: default_permissions This option instructs the kernel to perform its own permission check instead of deferring all permission checking to the filesystem. The check by the kernel is done in addition to any permission checks by the filesystem, and both have to succeed for an operation to be allowed. The kernel performs a standard UNIX permission check (based on mode bits and ownership of the directory entry, and uid/gid of the client). This mount option is activated implicitly if the filesystem en- ables ACL support during the initial feature negotiation when opening the device fd. In this case, the kernel performs both ACL and standard unix permission checking. Filesystems that do not implement any permission checking should generally add this option internally. allow_other This option overrides the security measure restricting file ac- cess to the filesystem owner, so that all users (including root) can access the files. rootmode=M Specifies the file mode of the filesystem's root (in octal rep- resentation). blkdev Mount a filesystem backed by a block device. This is a privi- leged option. The device must 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 in addition to 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 implementa- tion and should thus be set by the filesystem internally. This mount option is deprecated in favor of direct negotiation over the device fd (as 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. The file descriptor must have been obtained by opening the FUSE device (/dev/fuse). This option should not be specified by the filesystem owner. It is set by libfuse (or, if libfuse is not used, 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 is set by libfuse (or, if libfuse is not used, must be set by the filesystem itself). fsname=NAME Sets the filesystem source (first field in /etc/mtab). The de- fault 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 fsname option is not specified, just TYPE. libfuse-specific mount options: These following options are not actually passed to the kernel but in- terpreted by libfuse. They can be specified for all filesystems that use libfuse: allow_root This option is 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 This option enables automatic release of the mountpoint if filesystem terminates for any reason. Normally the filesystem is responsible for releasing the mountpoint, which means that the mountpoint becomes inaccessible if the filesystem terminates without first unmounting. 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 not actually passed to the kernel but in- terpreted by libfuse. They can only be specified for filesystems that use the high-level libfuse API: kernel_cache This option 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). Thus it is not suitable for network filesystems and other "intermediate" filesystems. NOTE: if this option is not specified (and neither 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 uncon- ditionally 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 Override the permission bits in st_mode set by the filesystem. The resulting permission bits are the ones missing from the given umask value. The value is given in octal representation. 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 is possible to give fractions of a second as well (e.g. entry_time- out=2.8) negative_timeout=T The timeout in seconds for which a negative lookup will be cached. This means, that if 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 are 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 are 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 avail- able when mounting a file system via mount.fuse3 (such as when mounting via the generic mount(1) command or /etc/fstab). 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 get- ting compromised by malicious file system data. FUSE MODULES (STACKING) Modules are filesystem stacking support to high level API. Filesystem modules can be built into libfuse or loaded from shared object iconv Perform file name character set conversion. Options are: from_code=CHARSET Character set to convert from (see iconv -l for a list of possi- ble values). Default is UTF-8. to_code=CHARSET Character set to convert to. Default is determined by the cur- rent locale. subdir Prepend a given directory to each path. Options are: subdir=DIR Directory to prepend to all paths. This option is mandatory. rellinks Transform absolute symlinks into relative norellinks Do not transform absolute symlinks into relative. This is the default. SECURITY The fusermount3 program is installed set-user-gid to fuse. This is done to allow users from fuse group to mount their own filesystem implemen- tations. There must however be some limitations, in order to prevent Bad User from doing nasty things. 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. NOTE FUSE filesystems are unmounted using the fusermount3(1) command (fuser- mount3 -u mountpoint). AUTHORS FUSE is currently maintained by Nikolaus Rath <Nikolaus AT rath.org> The original author of FUSE is Miklos Szeredi <mszeredi AT inf.hu>. This man page was originally written by Bastien Roucaries <rou- caries.bastien+debian AT gmail.com> for the Debian GNU/Linux distribution. SEE ALSO fusermount3(1) fusermount(1) mount(8) fuse(4) fuse(8) FUSE(4) Linux Programmer's Manual FUSE(4) NAME fuse - Filesystem in Userspace (FUSE) device SYNOPSIS #include <linux/fuse.h> DESCRIPTION This device is the primary interface between the FUSE filesystem driver and a user-space process wishing to provide the filesystem (referred to in the rest of this manual page as the filesystem daemon). This manual page is intended for those interested in understanding the kernel in- terface itself. Those implementing a FUSE filesystem may wish to make use of a user-space library such as libfuse that abstracts away the low-level interface. At its core, FUSE is a simple client-server protocol, in which the Linux kernel is the client and the daemon is the server. After obtain- ing a file descriptor for this device, the daemon may read(2) requests from that file descriptor and is expected to write(2) back its replies. It is important to note that a file descriptor is associated with a unique FUSE filesystem. In particular, opening a second copy of this device, will not allow access to resources created through the first file descriptor (and vice versa). The basic protocol Every message that is read by the daemon begins with a header described by the following structure: struct fuse_in_header { uint32_t len; /* Total length of the data, including this header */ uint32_t opcode; /* The kind of operation (see below) */ uint64_t unique; /* A unique identifier for this request */ uint64_t nodeid; /* ID of the filesystem object being operated on */ uint32_t uid; /* UID of the requesting process */ uint32_t gid; /* GID of the requesting process */ uint32_t pid; /* PID of the requesting process */ uint32_t padding; }; The header is followed by a variable-length data portion (which may be empty) specific to the requested operation (the requested operation is indicated by opcode). The daemon should then process the request and if applicable send a re- ply (almost all operations require a reply; if they do not, this is documented below), by performing a write(2) to the file descriptor. All replies must start with the following header: struct fuse_out_header { uint32_t len; /* Total length of data written to the file descriptor */ int32_t error; /* Any error that occurred (0 if none) */ uint64_t unique; /* The value from the corresponding request */ }; This header is also followed by (potentially empty) variable-sized data depending on the executed request. However, if the reply is an error reply (i.e., error is set), then no further payload data should be sent, independent of the request. Exchanged messages This section should contain documentation for each of the messages in the protocol. This manual page is currently incomplete, so not all messages are documented. For each message, first the struct sent by the kernel is given, followed by a description of the semantics of the message. FUSE_INIT struct fuse_init_in { uint32_t major; uint32_t minor; uint32_t max_readahead; /* Since protocol v7.6 */ uint32_t flags; /* Since protocol v7.6 */ }; This is the first request sent by the kernel to the daemon. It is used to negotiate the protocol version and other filesystem parameters. Note that the protocol version may affect the lay- out of any structure in the protocol (including this structure). The daemon must thus remember the negotiated version and flags for each session. As of the writing of this man page, the high- est supported kernel protocol version is 7.26. Users should be aware that the descriptions in this manual page may be incomplete or incorrect for older or more recent protocol versions. The reply for this request has the following format: struct fuse_init_out { uint32_t major; uint32_t minor; uint32_t max_readahead; /* Since v7.6 */ uint32_t flags; /* Since v7.6; some flags bits were introduced later */ uint16_t max_background; /* Since v7.13 */ uint16_t congestion_threshold; /* Since v7.13 */ uint32_t max_write; /* Since v7.5 */ uint32_t time_gran; /* Since v7.6 */ uint32_t unused[9]; }; If the major version supported by the kernel is larger than that supported by the daemon, the reply shall consist of only uint32_t major (following the usual header), indicating the largest major version supported by the daemon. The kernel will then issue a new FUSE_INIT request conforming to the older ver- sion. In the reverse case, the daemon should quietly fall back to the kernel's major version. The negotiated minor version is considered to be the minimum of the minor versions provided by the daemon and the kernel and both parties should use the protocol corresponding to said minor version. FUSE_GETATTR struct fuse_getattr_in { uint32_t getattr_flags; uint32_t dummy; uint64_t fh; /* Set only if (getattr_flags & FUSE_GETATTR_FH) }; The requested operation is to compute the attributes to be re- turned by stat(2) and similar operations for the given filesys- tem object. The object for which the attributes should be com- puted is indicated either by header->nodeid or, if the FUSE_GETATTR_FH flag is set, by the file handle fh. The latter case of operation is analogous to fstat(2). For performance reasons, these attributes may be cached in the kernel for a specified duration of time. While the cache time- out has not been exceeded, the attributes will be served from the cache and will not cause additional FUSE_GETATTR requests. The computed attributes and the requested cache timeout should then be returned in the following structure: struct fuse_attr_out { /* Attribute cache duration (seconds + nanoseconds) */ uint64_t attr_valid; uint32_t attr_valid_nsec; uint32_t dummy; struct fuse_attr { uint64_t ino; uint64_t size; uint64_t blocks; uint64_t atime; uint64_t mtime; uint64_t ctime; uint32_t atimensec; uint32_t mtimensec; uint32_t ctimensec; uint32_t mode; uint32_t nlink; uint32_t uid; uint32_t gid; uint32_t rdev; uint32_t blksize; uint32_t padding; } attr; }; FUSE_ACCESS struct fuse_access_in { uint32_t mask; uint32_t padding; }; If the default_permissions mount options is not used, this re- quest may be used for permissions checking. No reply data is expected, but errors may be indicated as usual by setting the error field in the reply header (in particular, access denied errors may be indicated by returning -EACCES). FUSE_OPEN and FUSE_OPENDIR struct fuse_open_in { uint32_t flags; /* The flags that were passed to the open(2) */ uint32_t unused; }; The requested operation is to open the node indicated by header->nodeid. The exact semantics of what this means will de- pend on the filesystem being implemented. However, at the very least the filesystem should validate that the requested flags are valid for the indicated resource and then send a reply with the following format: struct fuse_open_out { uint64_t fh; uint32_t open_flags; uint32_t padding; }; The fh field is an opaque identifier that the kernel will use to refer to this resource The open_flags field is a bit mask of any number of the flags that indicate properties of this file handle to the kernel: FOPEN_DIRECT_IO Bypass page cache for this open file. FOPEN_KEEP_CACHE Don't invalidate the data cache on open. FOPEN_NONSEEKABLE The file is not seekable. FUSE_READ and FUSE_READDIR struct fuse_read_in { uint64_t fh; uint64_t offset; uint32_t size; uint32_t read_flags; uint64_t lock_owner; uint32_t flags; uint32_t padding; }; The requested action is to read up to size bytes of the file or directory, starting at offset. The bytes should be returned di- rectly following the usual reply header. FUSE_INTERRUPT struct fuse_interrupt_in { uint64_t unique; }; The requested action is to cancel the pending operation indi- cated by unique. This request requires no response. However, receipt of this message does not by itself cancel the indicated operation. The kernel will still expect a reply to said opera- tion (e.g., an EINTR error or a short read). At most one FUSE_INTERRUPT request will be issued for a given operation. After issuing said operation, the kernel will wait uninterrupt- ibly for completion of the indicated request. FUSE_LOOKUP Directly following the header is a filename to be looked up in the directory indicated by header->nodeid. The expected reply is of the form: struct fuse_entry_out { uint64_t nodeid; /* Inode ID */ uint64_t generation; /* Inode generation */ uint64_t entry_valid; uint64_t attr_valid; uint32_t entry_valid_nsec; uint32_t attr_valid_nsec; struct fuse_attr attr; }; The combination of nodeid and generation must be unique for the filesystem's lifetime. The interpretation of timeouts and attr is as for FUSE_GETATTR. FUSE_FLUSH struct fuse_flush_in { uint64_t fh; uint32_t unused; uint32_t padding; uint64_t lock_owner; }; The requested action is to flush any pending changes to the in- dicated file handle. No reply data is expected. However, an empty reply message still needs to be issued once the flush op- eration is complete. FUSE_RELEASE and FUSE_RELEASEDIR struct fuse_release_in { uint64_t fh; uint32_t flags; uint32_t release_flags; uint64_t lock_owner; }; These are the converse of FUSE_OPEN and FUSE_OPENDIR respec- tively. The daemon may now free any resources associated with the file handle fh as the kernel will no longer refer to it. There is no reply data associated with this request, but a reply still needs to be issued once the request has been completely processed. FUSE_STATFS This operation implements statfs(2) for this filesystem. There is no input data associated with this request. The expected re- ply data has the following structure: struct fuse_kstatfs { uint64_t blocks; uint64_t bfree; uint64_t bavail; uint64_t files; uint64_t ffree; uint32_t bsize; uint32_t namelen; uint32_t frsize; uint32_t padding; uint32_t spare[6]; }; struct fuse_statfs_out { struct fuse_kstatfs st; }; For the interpretation of these fields, see statfs(2). ERRORS E2BIG Returned from read(2) operations when the kernel's request is too large for the provided buffer and the request was FUSE_SETX- ATTR. EINVAL Returned from write(2) if validation of the reply failed. Not all mistakes in replies will be caught by this validation. How- ever, basic mistakes, such as short replies or an incorrect unique value, are detected. EIO Returned from read(2) operations when the kernel's request is too large for the provided buffer. Note: There are various ways in which incorrect use of these in- terfaces can cause operations on the provided filesystem's files and directories to fail with EIO. Among the possible incorrect uses are: * changing mode & S_IFMT for an inode that has previously been reported to the kernel; or * giving replies to the kernel that are shorter than what the kernel expected. ENODEV Returned from read(2) and write(2) if the FUSE filesystem was unmounted. EPERM Returned from operations on a /dev/fuse file descriptor that has not been mounted. CONFORMING TO The FUSE filesystem is Linux-specific. NOTES The following messages are not yet documented in this manual page: FUSE_BATCH_FORGET FUSE_BMAP FUSE_CREATE FUSE_DESTROY FUSE_FALLOCATE FUSE_FORGET FUSE_FSYNC FUSE_FSYNCDIR FUSE_GETLK FUSE_GETXATTR FUSE_IOCTL FUSE_LINK FUSE_LISTXATTR FUSE_LSEEK FUSE_MKDIR FUSE_MKNOD FUSE_NOTIFY_REPLY FUSE_POLL FUSE_READDIRPLUS FUSE_READLINK FUSE_REMOVEXATTR FUSE_RENAME FUSE_RENAME2 FUSE_RMDIR FUSE_SETATTR FUSE_SETLK FUSE_SETLKW FUSE_SYMLINK FUSE_UNLINK FUSE_WRITE SEE ALSO fusermount(1), mount.fuse(8) COLOPHON This page is part of release 5.10 of the Linux man-pages project. A description of the project, information about reporting bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/. Linux 2018-02-02 FUSE(4)
Generated by phpMan v3.6.3-2-gc817beb Author: Che Dong Under GNU General Public License
2026-06-08 09:17 @216.73.217.65
CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)