Documentation/filesystems/fuse.txt

   1 Definitions
   2 ~~~~~~~~~~~
   3
   4 Userspace filesystem:
   5
   6   A filesystem in which data and metadata are provided by an ordinary
   7   userspace process.  The filesystem can be accessed normally through
   8   the kernel interface.
   9
  10 Filesystem daemon:
  11
  12   The process(es) providing the data and metadata of the filesystem.
  13
  14 Non-privileged mount (or user mount):
  15
  16   A userspace filesystem mounted by a non-privileged (non-root) user.
  17   The filesystem daemon is running with the privileges of the mounting
  18   user.  NOTE: this is not the same as mounts allowed with the "user"
  19   option in /etc/fstab, which is not discussed here.
  20
  21 Mount owner:
  22
  23   The user who does the mounting.
  24
  25 User:
  26
  27   The user who is performing filesystem operations.
  28
  29 What is FUSE?
  30 ~~~~~~~~~~~~~
  31
  32 FUSE is a userspace filesystem framework.  It consists of a kernel
  33 module (fuse.ko), a userspace library (libfuse.*) and a mount utility
  34 (fusermount).
  35
  36 One of the most important features of FUSE is allowing secure,
  37 non-privileged mounts.  This opens up new possibilities for the use of
  38 filesystems.  A good example is sshfs: a secure network filesystem
  39 using the sftp protocol.
  40
  41 The userspace library and utilities are available from the FUSE
  42 homepage:
  43
  44   http://fuse.sourceforge.net/
  45
  46 Mount options
  47 ~~~~~~~~~~~~~
  48
  49 'fd=N'
  50
  51   The file descriptor to use for communication between the userspace
  52   filesystem and the kernel.  The file descriptor must have been
  53   obtained by opening the FUSE device ('/dev/fuse').
  54
  55 'rootmode=M'
  56
  57   The file mode of the filesystem's root in octal representation.
  58
  59 'user_id=N'
  60
  61   The numeric user id of the mount owner.
  62
  63 'group_id=N'
  64
  65   The numeric group id of the mount owner.
  66
  67 'default_permissions'
  68
  69   By default FUSE doesn't check file access permissions, the
  70   filesystem is free to implement it's access policy or leave it to
  71   the underlying file access mechanism (e.g. in case of network
  72   filesystems).  This option enables permission checking, restricting
  73   access based on file mode.  This is option is usually useful
  74   together with the 'allow_other' mount option.
  75
  76 'allow_other'
  77
  78   This option overrides the security measure restricting file access
  79   to the user mounting the filesystem.  This option is by default only
  80   allowed to root, but this restriction can be removed with a
  81   (userspace) configuration option.
  82
  83 'max_read=N'
  84
  85   With this option the maximum size of read operations can be set.
  86   The default is infinite.  Note that the size of read requests is
  87   limited anyway to 32 pages (which is 128kbyte on i386).
  88
  89 How do non-privileged mounts work?
  90 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  91
  92 Since the mount() system call is a privileged operation, a helper
  93 program (fusermount) is needed, which is installed setuid root.
  94
  95 The implication of providing non-privileged mounts is that the mount
  96 owner must not be able to use this capability to compromise the
  97 system.  Obvious requirements arising from this are:
  98
  99  A) mount owner should not be able to get elevated privileges with the
 100     help of the mounted filesystem
 101
 102  B) mount owner should not get illegitimate access to information from
 103     other users' and the super user's processes
 104
 105  C) mount owner should not be able to induce undesired behavior in
 106     other users' or the super user's processes
 107
 108 How are requirements fulfilled?
 109 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 110
 111  A) The mount owner could gain elevated privileges by either:
 112
 113      1) creating a filesystem containing a device file, then opening
 114         this device
 115
 116      2) creating a filesystem containing a suid or sgid application,
 117         then executing this application
 118
 119     The solution is not to allow opening device files and ignore
 120     setuid and setgid bits when executing programs.  To ensure this
 121     fusermount always adds "nosuid" and "nodev" to the mount options
 122     for non-privileged mounts.
 123
 124  B) If another user is accessing files or directories in the
 125     filesystem, the filesystem daemon serving requests can record the
 126     exact sequence and timing of operations performed.  This
 127     information is otherwise inaccessible to the mount owner, so this
 128     counts as an information leak.
 129
 130     The solution to this problem will be presented in point 2) of C).
 131
 132  C) There are several ways in which the mount owner can induce
 133     undesired behavior in other users' processes, such as:
 134
 135      1) mounting a filesystem over a file or directory which the mount
 136         owner could otherwise not be able to modify (or could only
 137         make limited modifications).
 138
 139         This is solved in fusermount, by checking the access
 140         permissions on the mountpoint and only allowing the mount if
 141         the mount owner can do unlimited modification (has write
 142         access to the mountpoint, and mountpoint is not a "sticky"
 143         directory)
 144
 145      2) Even if 1) is solved the mount owner can change the behavior
 146         of other users' processes.
 147
 148          i) It can slow down or indefinitely delay the execution of a
 149            filesystem operation creating a DoS against the user or the
 150            whole system.  For example a suid application locking a
 151            system file, and then accessing a file on the mount owner's
 152            filesystem could be stopped, and thus causing the system
 153            file to be locked forever.
 154
 155          ii) It can present files or directories of unlimited length, or
 156            directory structures of unlimited depth, possibly causing a
 157            system process to eat up diskspace, memory or other
 158            resources, again causing DoS.
 159
 160         The solution to this as well as B) is not to allow processes
 161         to access the filesystem, which could otherwise not be
 162         monitored or manipulated by the mount owner.  Since if the
 163         mount owner can ptrace a process, it can do all of the above
 164         without using a FUSE mount, the same criteria as used in
 165         ptrace can be used to check if a process is allowed to access
 166         the filesystem or not.
 167
 168         Note that the ptrace check is not strictly necessary to
 169         prevent B/2/i, it is enough to check if mount owner has enough
 170         privilege to send signal to the process accessing the
 171         filesystem, since SIGSTOP can be used to get a similar effect.
 172
 173 I think these limitations are unacceptable?
 174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 175
 176 If a sysadmin trusts the users enough, or can ensure through other
 177 measures, that system processes will never enter non-privileged
 178 mounts, it can relax the last limitation with a "user_allow_other"
 179 config option.  If this config option is set, the mounting user can
 180 add the "allow_other" mount option which disables the check for other
 181 users' processes.
 182
 183 Kernel - userspace interface
 184 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 185
 186 The following diagram shows how a filesystem operation (in this
 187 example unlink) is performed in FUSE.
 188
 189 NOTE: everything in this description is greatly simplified
 190
 191  |  "rm /mnt/fuse/file"               |  FUSE filesystem daemon
 192  |                                    |
 193  |                                    |  >sys_read()
 194  |                                    |    >fuse_dev_read()
 195  |                                    |      >request_wait()
 196  |                                    |        [sleep on fc->waitq]
 197  |                                    |
 198  |  >sys_unlink()                     |
 199  |    >fuse_unlink()                  |
 200  |      [get request from             |
 201  |       fc->unused_list]             |
 202  |      >request_send()               |
 203  |        [queue req on fc->pending]  |
 204  |        [wake up fc->waitq]         |        [woken up]
 205  |        >request_wait_answer()      |
 206  |          [sleep on req->waitq]     |
 207  |                                    |      <request_wait()
 208  |                                    |      [remove req from fc->pending]
 209  |                                    |      [copy req to read buffer]
 210  |                                    |      [add req to fc->processing]
 211  |                                    |    <fuse_dev_read()
 212  |                                    |  <sys_read()
 213  |                                    |
 214  |                                    |  [perform unlink]
 215  |                                    |
 216  |                                    |  >sys_write()
 217  |                                    |    >fuse_dev_write()
 218  |                                    |      [look up req in fc->processing]
 219  |                                    |      [remove from fc->processing]
 220  |                                    |      [copy write buffer to req]
 221  |          [woken up]                |      [wake up req->waitq]
 222  |                                    |    <fuse_dev_write()
 223  |                                    |  <sys_write()
 224  |        <request_wait_answer()      |
 225  |      <request_send()               |
 226  |      [add request to               |
 227  |       fc->unused_list]             |
 228  |    <fuse_unlink()                  |
 229  |  <sys_unlink()                     |
 230
 231 There are a couple of ways in which to deadlock a FUSE filesystem.
 232 Since we are talking about unprivileged userspace programs,
 233 something must be done about these.
 234
 235 Scenario 1 -  Simple deadlock
 236 -----------------------------
 237
 238  |  "rm /mnt/fuse/file"               |  FUSE filesystem daemon
 239  |                                    |
 240  |  >sys_unlink("/mnt/fuse/file")     |
 241  |    [acquire inode semaphore        |
 242  |     for "file"]                    |
 243  |    >fuse_unlink()                  |
 244  |      [sleep on req->waitq]         |
 245  |                                    |  <sys_read()
 246  |                                    |  >sys_unlink("/mnt/fuse/file")
 247  |                                    |    [acquire inode semaphore
 248  |                                    |     for "file"]
 249  |                                    |    *DEADLOCK*
 250
 251 The solution for this is to allow requests to be interrupted while
 252 they are in userspace:
 253
 254  |      [interrupted by signal]       |
 255  |    <fuse_unlink()                  |
 256  |    [release semaphore]             |    [semaphore acquired]
 257  |  <sys_unlink()                     |
 258  |                                    |    >fuse_unlink()
 259  |                                    |      [queue req on fc->pending]
 260  |                                    |      [wake up fc->waitq]
 261  |                                    |      [sleep on req->waitq]
 262
 263 If the filesystem daemon was single threaded, this will stop here,
 264 since there's no other thread to dequeue and execute the request.
 265 In this case the solution is to kill the FUSE daemon as well.  If
 266 there are multiple serving threads, you just have to kill them as
 267 long as any remain.
 268
 269 Moral: a filesystem which deadlocks, can soon find itself dead.
 270
 271 Scenario 2 - Tricky deadlock
 272 ----------------------------
 273
 274 This one needs a carefully crafted filesystem.  It's a variation on
 275 the above, only the call back to the filesystem is not explicit,
 276 but is caused by a pagefault.
 277
 278  |  Kamikaze filesystem thread 1      |  Kamikaze filesystem thread 2
 279  |                                    |
 280  |  [fd = open("/mnt/fuse/file")]     |  [request served normally]
 281  |  [mmap fd to 'addr']               |
 282  |  [close fd]                        |  [FLUSH triggers 'magic' flag]
 283  |  [read a byte from addr]           |
 284  |    >do_page_fault()                |
 285  |      [find or create page]         |
 286  |      [lock page]                   |
 287  |      >fuse_readpage()              |
 288  |         [queue READ request]       |
 289  |         [sleep on req->waitq]      |
 290  |                                    |  [read request to buffer]
 291  |                                    |  [create reply header before addr]
 292  |                                    |  >sys_write(addr - headerlength)
 293  |                                    |    >fuse_dev_write()
 294  |                                    |      [look up req in fc->processing]
 295  |                                    |      [remove from fc->processing]
 296  |                                    |      [copy write buffer to req]
 297  |                                    |        >do_page_fault()
 298  |                                    |           [find or create page]
 299  |                                    |           [lock page]
 300  |                                    |           * DEADLOCK *
 301
 302 Solution is again to let the the request be interrupted (not
 303 elaborated further).
 304
 305 An additional problem is that while the write buffer is being
 306 copied to the request, the request must not be interrupted.  This
 307 is because the destination address of the copy may not be valid
 308 after the request is interrupted.
 309
 310 This is solved with doing the copy atomically, and allowing
 311 interruption while the page(s) belonging to the write buffer are
 312 faulted with get_user_pages().  The 'req->locked' flag indicates
 313 when the copy is taking place, and interruption is delayed until
 314 this flag is unset.
 315