1fuse(8)                     System Manager's Manual                    fuse(8)
2
3
4

NAME

6       fuse - configuration and mount options for FUSE file systems
7

DESCRIPTION

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

DEFINITIONS

15       FUSE   The in-kernel filesystem that forwards requests to a  user-space
16              process.
17
18       filesystem
19              The  user-space  process that responds to requests received from
20              the kernel.
21
22       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
29       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
35       client Any process that interacts with the mountpoint.
36

CONFIGURATION

38       Some   options   regarding   mount  policy  can  be  set  in  the  file
39       /etc/fuse.conf. Currently these options are:
40
41       mount_max = NNN
42              Set the maximum number of FUSE mounts allowed to non-root users.
43              The default is 1000.
44
45       user_allow_other
46              Allow  non-root  users  to specify the allow_other or allow_root
47              mount options (see below).
48
49       These limits are enforced by the fusermount3 helper,  so  they  can  be
50       avoided by filesystems that run as root.
51

OPTIONS

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
58   General mount options:
59       These are FUSE specific mount options that can  be  specified  for  all
60       filesystems:
61
62       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
71              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
76              Filesystems that do not implement any permission checking should
77              generally add this option internally.
78
79       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
84       rootmode=M
85              Specifies  the file mode of the filesystem's root (in octal rep‐
86              resentation).
87
88       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
92       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
96              In  most  cases,  this  option  should  not  be specified by the
97              filesystem owner but set internally by the filesystem.
98
99       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
105              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
109              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
115       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
119              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
123       user_id=N
124              group_id=N Specifies the numeric uid/gid of the mount owner.
125
126              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
130       fsname=NAME
131              Sets  the  filesystem source (first field in /etc/mtab). The de‐
132              fault is the name of the filesystem process.
133
134       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
140              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
143
144   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
149       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
154       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
161              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
165
166   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
171       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
178              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
182       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
188       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
193       uid=N  Override the st_uid field set by the filesystem (N is numeric).
194
195       gid=N  Override the st_gid field set by the filesystem (N is numeric).
196
197       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
203       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
211       attr_timeout=T
212              The  timeout  in seconds for which file/directory attributes are
213              cached.  The default is 1.0 second.
214
215       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
220       noforget
221
222       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
230       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
235
236   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
241       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
246       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
257

FUSE MODULES (STACKING)

259       Modules  are  filesystem stacking support to high level API. Filesystem
260       modules can be built into libfuse or loaded from shared object
261
262   iconv
263       Perform file name character set conversion.  Options are:
264
265       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
269       to_code=CHARSET
270              Character  set to convert to.  Default is determined by the cur‐
271              rent locale.
272
273   subdir
274       Prepend a given directory to each path. Options are:
275
276       subdir=DIR
277              Directory to prepend to all paths.  This option is mandatory.
278
279       rellinks
280              Transform absolute symlinks into relative
281
282       norellinks
283              Do not transform absolute symlinks into relative.  This  is  the
284              default.
285

SECURITY

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
292       1.     The user can only mount on a mountpoint, for which it has  write
293              permission
294
295       2.     The  mountpoint  is  not a sticky directory which isn't owned by
296              the user (like /tmp usually is)
297
298       3.     No other user (including root) can access the  contents  of  the
299              mounted filesystem.
300

NOTE

302       FUSE filesystems are unmounted using the fusermount3(1) command (fuser‐
303       mount3 -u mountpoint).
304

AUTHORS

306       FUSE is currently maintained by Nikolaus Rath <Nikolaus@rath.org>
307
308       The original author of FUSE is Miklos Szeredi <mszeredi@inf.bme.hu>.
309
310       This man  page  was  originally  written  by  Bastien  Roucaries  <rou‐
311       caries.bastien+debian@gmail.com> for the Debian GNU/Linux distribution.
312

SEE ALSO

314       fusermount3(1) fusermount(1) mount(8) fuse(4)
315
316
317
318                                                                       fuse(8)
Impressum