1fuse(8) System Manager's Manual fuse(8)
2
6 fuse - configuration and mount options for FUSE file systems
7
9 FUSE (Filesystem in Userspace) is a simple interface for userspace pro‐
10 grams to export a virtual filesystem to the Linux kernel. FUSE also
11 aims to provide a secure method for non privileged users to create and
12 mount their own filesystem implementations.
13
15 FUSE The in-kernel filesystem that forwards requests to a user-space
16 process.
17 filesystem
19 The user-space process that responds to requests received from
20 the kernel.
21 libfuse
23 The shared library that most (user-space) filesystems use to
24 communicate with FUSE (the kernel filesystem). libfuse also pro‐
25 vides the fusermount3 (or fusermount if you have older version
26 of libfuse) helper to allow non-privileged users to mount
27 filesystems.
28 filesystem owner
30 The user that starts the filesystem and instructs the kernel to
31 associate it with a particular mountpoint. The latter is typi‐
32 cally done by the filesystem itself on start-up. When using lib‐
33 fuse, this is done by calling the fusermount3 utility.
34 client Any process that interacts with the mountpoint.
36
38 Some options regarding mount policy can be set in the file
39 /etc/fuse.conf. Currently these options are:
40 mount_max = NNN
42 Set the maximum number of FUSE mounts allowed to non-root users.
43 The default is 1000.
44 user_allow_other
46 Allow non-root users to specify the allow_other or allow_root
47 mount options (see below).
48 These limits are enforced by the fusermount3 helper, so they can be
50 avoided by filesystems that run as root.
51
53 Most of the generic mount options described in mount are supported (ro,
54 rw, suid, nosuid, dev, nodev, exec, noexec, atime, noatime, sync,
55 async, dirsync). Filesystems are mounted with nodev,nosuid by default,
56 which can only be overridden by a privileged user.
57 General mount options:
59 These are FUSE specific mount options that can be specified for all
60 filesystems:
61 default_permissions
63 This option instructs the kernel to perform its own permission
64 check instead of deferring all permission checking to the
65 filesystem. The check by the kernel is done in addition to any
66 permission checks by the filesystem, and both have to succeed
67 for an operation to be allowed. The kernel performs a standard
68 UNIX permission check (based on mode bits and ownership of the
69 directory entry, and uid/gid of the client).
70 This mount option is activated implicitly if the filesystem en‐
72 ables ACL support during the initial feature negotiation when
73 opening the device fd. In this case, the kernel performs both
74 ACL and standard unix permission checking.
75 Filesystems that do not implement any permission checking should
77 generally add this option internally.
78 allow_other
80 This option overrides the security measure restricting file ac‐
81 cess to the filesystem owner, so that all users (including root)
82 can access the files.
83 rootmode=M
85 Specifies the file mode of the filesystem's root (in octal rep‐
86 resentation).
87 blkdev Mount a filesystem backed by a block device. This is a privi‐
89 leged option. The device must be specified with the fsname=NAME
90 option.
91 blksize=N
93 Set the block size for the filesystem. This option is only valid
94 for 'fuseblk' type mounts. The default is 512.
95 In most cases, this option should not be specified by the
97 filesystem owner but set internally by the filesystem.
98 max_read=N
100 With this option the maximum size of read operations can be set.
101 The default is infinite, but typically the kernel enforces its
102 own limit in addition to this one. A value of zero corresponds
103 to no limit.
104 This option should not be specified by the filesystem owner. The
106 correct (or optimum) value depends on the filesystem implementa‐
107 tion and should thus be set by the filesystem internally.
108 This mount option is deprecated in favor of direct negotiation
110 over the device fd (as done for e.g. the maximum size of write
111 operations). For the time being, libfuse-using filesystems that
112 want to limit the read size must therefore use this mount option
113 and set the same value again in the init() handler.
114 fd=N The file descriptor to use for communication between the
116 userspace filesystem and the kernel. The file descriptor must
117 have been obtained by opening the FUSE device (/dev/fuse).
118 This option should not be specified by the filesystem owner. It
120 is set by libfuse (or, if libfuse is not used, must be set by
121 the filesystem itself).
122 user_id=N
124 group_id=N Specifies the numeric uid/gid of the mount owner.
125 This option should not be specified by the filesystem owner. It
127 is set by libfuse (or, if libfuse is not used, must be set by
128 the filesystem itself).
129 fsname=NAME
131 Sets the filesystem source (first field in /etc/mtab). The de‐
132 fault is the name of the filesystem process.
133 subtype=TYPE
135 Sets the filesystem type (third field in /etc/mtab). The default
136 is the name of the filesystem process. If the kernel supports
137 it, /etc/mtab and /proc/mounts will show the filesystem type as
138 fuse.TYPE
139 If the kernel doesn't support subtypes, the source field will be
141 TYPE#NAME, or if fsname option is not specified, just TYPE.
142 libfuse-specific mount options:
145 These following options are not actually passed to the kernel but in‐
146 terpreted by libfuse. They can be specified for all filesystems that
147 use libfuse:
148 allow_root
150 This option is similar to allow_other but file access is limited
151 to the filesystem owner and root. This option and allow_other
152 are mutually exclusive.
153 auto_unmount
155 This option enables automatic release of the mountpoint if
156 filesystem terminates for any reason. Normally the filesystem is
157 responsible for releasing the mountpoint, which means that the
158 mountpoint becomes inaccessible if the filesystem terminates
159 without first unmounting.
160 This option is dangerous and should only be used after careful
162 consideration of the risks.
163 Automatically unmounting the filesystem means that if the
165 filesystem crashes the mountpoint may suddenly appear empty,
166 which may have unintended consequences. For example, a running
167 backup and mirroring program may conclude that all the data in
168 the filesystem has been deleted and proceed to propagate this
169 deletion to the backup / remote system. If the mountpoint in‐
170 stead becomes inaccessible (the default), most programs will be‐
171 have correctly (report an error).
172 This feature may also accidentally unmount the wrong filesystem
174 due to race conditions. For example, if another filesystem was
175 mounted underneath the same mountpoint, or if a new filesystem
176 is mounted after the FUSE process has crashed, it may acciden‐
177 tally get unmounted.
178 At the moment, this option implies that the filesystem will also
180 be mounted with nodev and nosuid (even when mounted by root).
181 This restriction may be lifted in the future.
182 High-level mount options:
185 These following options are not actually passed to the kernel but in‐
186 terpreted by libfuse. They can only be specified for filesystems that
187 use the high-level libfuse API:
188 kernel_cache
190 This option disables flushing the cache of the file contents on
191 every open(2). This should only be enabled on filesystems,
192 where the file data is never changed externally (not through the
193 mounted FUSE filesystem). Thus it is not suitable for network
194 filesystems and other "intermediate" filesystems.
195 NOTE: if this option is not specified (and neither direct_io)
197 data is still cached after the open(2), so a read(2) system call
198 will not always initiate a read operation.
199 auto_cache
201 This option is an alternative to kernel_cache. Instead of uncon‐
202 ditionally keeping cached data, the cached data is invalidated
203 on open(2) if the modification time or the size of the file has
204 changed since it was last opened.
205 umask=M
207 Override the permission bits in st_mode set by the filesystem.
208 The resulting permission bits are the ones missing from the
209 given umask value. The value is given in octal representation.
210 uid=N Override the st_uid field set by the filesystem (N is numeric).
212 gid=N Override the st_gid field set by the filesystem (N is numeric).
214 entry_timeout=T
216 The timeout in seconds for which name lookups will be cached.
217 The default is 1.0 second. For all the timeout options, it is
218 possible to give fractions of a second as well (e.g. entry_time‐
219 out=2.8)
220 negative_timeout=T
222 The timeout in seconds for which a negative lookup will be
223 cached. This means, that if file did not exist (lookup returned
224 ENOENT), the lookup will only be redone after the timeout, and
225 the file/directory will be assumed to not exist until then. The
226 default is 0.0 second, meaning that caching negative lookups are
227 disabled.
228 attr_timeout=T
230 The timeout in seconds for which file/directory attributes are
231 cached. The default is 1.0 second.
232 ac_attr_timeout=T
234 The timeout in seconds for which file attributes are cached for
235 the purpose of checking if auto_cache should flush the file data
236 on open. The default is the value of attr_timeout
237 noforget
239 remember=T
241 Normally, libfuse assigns inodes to paths only for as long as
242 the kernel is aware of them. With this option inodes are instead
243 assigned for at least T seconds (or, in the case of noforget,
244 the life-time of the filesystem). This will require more memory,
245 but may be necessary when using applications that make use of
246 inode numbers.
247 modules=M1[:M2...]
249 Add modules to the filesystem stack. Modules are pushed in the
250 order they are specified, with the original filesystem being on
251 the bottom of the stack.
252 mount.fuse3 options:
255 These options are interpreted by mount.fuse3 and are thus only avail‐
256 able when mounting a file system via mount.fuse3 (such as when mounting
257 via the generic mount(1) command or /etc/fstab). Supported options are:
258 setuid=USER
260 Switch to USER and its primary group before launching the FUSE
261 file system process. mount.fuse3 must be run as root or with
262 CAP_SETUID and CAP_SETGID for this to work.
263 drop_privileges
265 Perform setup of the FUSE file descriptor and mounting the file
266 system before launching the FUSE file system process.
267 mount.fuse3 requires privilege to do so, i.e. must be run as
268 root or at least with CAP_SYS_ADMIN and CAP_SETPCAP. It will
269 launch the file system process fully unprivileged, i.e. without
270 capabilities(7) and prctl(2) flags set up such that privileges
271 can't be reacquired (e.g. via setuid or fscaps binaries). This
272 reduces risk in the event of the FUSE file system process get‐
273 ting compromised by malicious file system data.
274
277 Modules are filesystem stacking support to high level API. Filesystem
278 modules can be built into libfuse or loaded from shared object
279 iconv
281 Perform file name character set conversion. Options are:
282 from_code=CHARSET
284 Character set to convert from (see iconv -l for a list of possi‐
285 ble values). Default is UTF-8.
286 to_code=CHARSET
288 Character set to convert to. Default is determined by the cur‐
289 rent locale.
290 subdir
292 Prepend a given directory to each path. Options are:
293 subdir=DIR
295 Directory to prepend to all paths. This option is mandatory.
296 rellinks
298 Transform absolute symlinks into relative
299 norellinks
301 Do not transform absolute symlinks into relative. This is the
302 default.
303
305 The fusermount3 program is installed set-user-gid to fuse. This is done
306 to allow users from fuse group to mount their own filesystem implemen‐
307 tations. There must however be some limitations, in order to prevent
308 Bad User from doing nasty things. Currently those limitations are:
309 1. The user can only mount on a mountpoint, for which it has write
311 permission
312 2. The mountpoint is not a sticky directory which isn't owned by
314 the user (like /tmp usually is)
315 3. No other user (including root) can access the contents of the
317 mounted filesystem.
318
320 FUSE filesystems are unmounted using the fusermount3(1) command (fuser‐
321 mount3 -u mountpoint).
322
324 FUSE is currently maintained by Nikolaus Rath <Nikolaus@rath.org>
325 The original author of FUSE is Miklos Szeredi <mszeredi@inf.bme.hu>.
327 This man page was originally written by Bastien Roucaries <rou‐
329 caries.bastien+debian@gmail.com> for the Debian GNU/Linux distribution.
330
332 fusermount3(1) fusermount(1) mount(8) fuse(4)
333 fuse(8)