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 At the moment, this option implies that the filesystem will also
162 be mounted with nodev and nosuid (even when mounted by root).
163 This restriction may be lifted in the future.
164 High-level mount options:
167 These following options are not actually passed to the kernel but in‐
168 terpreted by libfuse. They can only be specified for filesystems that
169 use the high-level libfuse API:
170 kernel_cache
172 This option disables flushing the cache of the file contents on
173 every open(2). This should only be enabled on filesystems,
174 where the file data is never changed externally (not through the
175 mounted FUSE filesystem). Thus it is not suitable for network
176 filesystems and other "intermediate" filesystems.
177 NOTE: if this option is not specified (and neither direct_io)
179 data is still cached after the open(2), so a read(2) system call
180 will not always initiate a read operation.
181 auto_cache
183 This option is an alternative to kernel_cache. Instead of uncon‐
184 ditionally keeping cached data, the cached data is invalidated
185 on open(2) if the modification time or the size of the file has
186 changed since it was last opened.
187 umask=M
189 Override the permission bits in st_mode set by the filesystem.
190 The resulting permission bits are the ones missing from the
191 given umask value. The value is given in octal representation.
192 uid=N Override the st_uid field set by the filesystem (N is numeric).
194 gid=N Override the st_gid field set by the filesystem (N is numeric).
196 entry_timeout=T
198 The timeout in seconds for which name lookups will be cached.
199 The default is 1.0 second. For all the timeout options, it is
200 possible to give fractions of a second as well (e.g. entry_time‐
201 out=2.8)
202 negative_timeout=T
204 The timeout in seconds for which a negative lookup will be
205 cached. This means, that if file did not exist (lookup returned
206 ENOENT), the lookup will only be redone after the timeout, and
207 the file/directory will be assumed to not exist until then. The
208 default is 0.0 second, meaning that caching negative lookups are
209 disabled.
210 attr_timeout=T
212 The timeout in seconds for which file/directory attributes are
213 cached. The default is 1.0 second.
214 ac_attr_timeout=T
216 The timeout in seconds for which file attributes are cached for
217 the purpose of checking if auto_cache should flush the file data
218 on open. The default is the value of attr_timeout
219 noforget
221 remember=T
223 Normally, libfuse assigns inodes to paths only for as long as
224 the kernel is aware of them. With this option inodes are instead
225 assigned for at least T seconds (or, in the case of noforget,
226 the life-time of the filesystem). This will require more memory,
227 but may be necessary when using applications that make use of
228 inode numbers.
229 modules=M1[:M2...]
231 Add modules to the filesystem stack. Modules are pushed in the
232 order they are specified, with the original filesystem being on
233 the bottom of the stack.
234 mount.fuse3 options:
237 These options are interpreted by mount.fuse3 and are thus only avail‐
238 able when mounting a file system via mount.fuse3 (such as when mounting
239 via the generic mount(1) command or /etc/fstab). Supported options are:
240 setuid=USER
242 Switch to USER and its primary group before launching the FUSE
243 file system process. mount.fuse3 must be run as root or with
244 CAP_SETUID and CAP_SETGID for this to work.
245 drop_privileges
247 Perform setup of the FUSE file descriptor and mounting the file
248 system before launching the FUSE file system process.
249 mount.fuse3 requires privilege to do so, i.e. must be run as
250 root or at least with CAP_SYS_ADMIN and CAP_SETPCAP. It will
251 launch the file system process fully unprivileged, i.e. without
252 capabilities(7) and prctl(2) flags set up such that privileges
253 can't be reacquired (e.g. via setuid or fscaps binaries). This
254 reduces risk in the event of the FUSE file system process get‐
255 ting compromised by malicious file system data.
256
259 Modules are filesystem stacking support to high level API. Filesystem
260 modules can be built into libfuse or loaded from shared object
261 iconv
263 Perform file name character set conversion. Options are:
264 from_code=CHARSET
266 Character set to convert from (see iconv -l for a list of possi‐
267 ble values). Default is UTF-8.
268 to_code=CHARSET
270 Character set to convert to. Default is determined by the cur‐
271 rent locale.
272 subdir
274 Prepend a given directory to each path. Options are:
275 subdir=DIR
277 Directory to prepend to all paths. This option is mandatory.
278 rellinks
280 Transform absolute symlinks into relative
281 norellinks
283 Do not transform absolute symlinks into relative. This is the
284 default.
285
287 The fusermount3 program is installed set-user-gid to fuse. This is done
288 to allow users from fuse group to mount their own filesystem implemen‐
289 tations. There must however be some limitations, in order to prevent
290 Bad User from doing nasty things. Currently those limitations are:
291 1. The user can only mount on a mountpoint, for which it has write
293 permission
294 2. The mountpoint is not a sticky directory which isn't owned by
296 the user (like /tmp usually is)
297 3. No other user (including root) can access the contents of the
299 mounted filesystem.
300
302 FUSE filesystems are unmounted using the fusermount3(1) command (fuser‐
303 mount3 -u mountpoint).
304
306 FUSE is currently maintained by Nikolaus Rath <Nikolaus@rath.org>
307 The original author of FUSE is Miklos Szeredi <mszeredi@inf.bme.hu>.
309 This man page was originally written by Bastien Roucaries <rou‐
311 caries.bastien+debian@gmail.com> for the Debian GNU/Linux distribution.
312
314 fusermount3(1) fusermount(1) mount(8) fuse(4)
315 fuse(8)