Documentation/filesystems/fuse.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 FUSE  title
18 Non-privileged mount (or user mount):
19   A userspace filesystem mounted by a non-privileged (non-root) user.
37 What is FUSE?
40 FUSE is a userspace filesystem framework.  It consists of a kernel
41 module (fuse.ko), a userspace library (libfuse.*) and a mount utility
44 One of the most important features of FUSE is allowing secure,
45 non-privileged mounts.  This opens up new possibilities for the use of
50 `FUSE homepage: <https://github.com/libfuse/>`_
57     fuse
58       This is the usual way to mount a FUSE filesystem.  The first
72   obtained by opening the FUSE device ('/dev/fuse').
84   By default FUSE doesn't check file access permissions, the
86   the underlying file access mechanism (e.g. in case of network
109 There's a control filesystem for FUSE, which can be mounted by::
111   mount -t fusectl none /sys/fs/fuse/connections
113 Mounting it under the '/sys/fs/fuse/connections' directory makes it
116 Under the fuse control filesystem each connection has a directory
124 	  no filesystem activity and 'waiting' is non-zero, then the
137 If a process issuing a FUSE filesystem request is interrupted, the
140   -  If the request is not yet sent to userspace AND the signal is
144   -  If the request is not yet sent to userspace AND the signal is not
149   -  If the request is already sent to userspace, then an INTERRUPT
193   - Kill the filesystem daemon.  Works in case of a) and b)
195   - Kill the filesystem daemon and all users of the filesystem.  Works
198   - Use forced umount (umount -f).  Works in all cases but only if
201   - Abort filesystem through the FUSE control filesystem.  Most
204 How do non-privileged mounts work?
210 The implication of providing non-privileged mounts is that the mount
235     for non-privileged mounts.
277 	without using a FUSE mount, the same criteria as used in
290 measures, that system processes will never enter non-privileged
293   - With the 'user_allow_other' config option. If this config option is
298     an unprivileged user - normally restricted from mounting with
299     'allow_other' - could do so in a user namespace where they're
306   - With the 'allow_sys_admin_access' module option. If this option is
312 information leak or *DoS* as described in points B and C/2/i-ii in the
315 Kernel - userspace interface
319 example unlink) is performed in FUSE. ::
322  |  "rm /mnt/fuse/file"               |  FUSE filesystem daemon
327  |                                    |        [sleep on fc->waitq]
332  |       fc->unused_list]             |
334  |        [queue req on fc->pending]  |
335  |        [wake up fc->waitq]         |        [woken up]
337  |          [sleep on req->waitq]     |
339  |                                    |      [remove req from fc->pending]
341  |                                    |      [add req to fc->processing]
349  |                                    |      [look up req in fc->processing]
350  |                                    |      [remove from fc->processing]
352  |          [woken up]                |      [wake up req->waitq]
358  |       fc->unused_list]             |
364 There are a couple of ways in which to deadlock a FUSE filesystem.
368 **Scenario 1 -  Simple deadlock**::
370  |  "rm /mnt/fuse/file"               |  FUSE filesystem daemon
372  |  >sys_unlink("/mnt/fuse/file")     |
376  |      [sleep on req->waitq]         |
378  |                                    |  >sys_unlink("/mnt/fuse/file")
385 **Scenario 2 - Tricky deadlock**
394  |  [fd = open("/mnt/fuse/file")]     |  [request served normally]
403  |         [sleep on req->waitq]      |
406  |                                    |  >sys_write(addr - headerlength)
408  |                                    |      [look up req in fc->processing]
409  |                                    |      [remove from fc->processing]
425 get_user_pages().  The 'req->locked' flag indicates when the copy is