README.md

   1 libfuse
   2 =======
   3
   4 Warning: unresolved security issue
   5 ----------------------------------
   6
   7 Be aware that FUSE has an unresolved security bug
   8 ([bug #15](https://github.com/libfuse/libfuse/issues/15)): the
   9 permission check for accessing a cached directory is only done once
  10 when the directory entry is first loaded into the cache. Subsequent
  11 accesses will re-use the results of the first check, even if the
  12 directory permissions have since changed, and even if the subsequent
  13 access is made by a different user.
  14
  15 This bug needs to be fixed in the Linux kernel and has been known
  16 since 2006 but unfortunately no fix has been applied yet. If you
  17 depend on correct permission handling for FUSE file systems, the only
  18 workaround is to completely disable caching of directory
  19 entries. Alternatively, the severity of the bug can be somewhat
  20 reduced by not using the `allow_other` mount option.
  21
  22
  23 About
  24 -----
  25
  26 FUSE (Filesystem in Userspace) is an interface for userspace programs
  27 to export a filesystem to the Linux kernel. The FUSE project consists
  28 of two components: the *fuse* kernel module (maintained in the regular
  29 kernel repositories) and the *libfuse* userspace library (maintained
  30 in this repository). libfuse provides the reference implementation
  31 for communicating with the FUSE kernel module.
  32
  33 A FUSE file system is typically implemented as a standalone
  34 application that links with libfuse. libfuse provides functions to
  35 mount the file system, unmount it, read requests from the kernel, and
  36 send responses back. libfuse offers two APIs: a "high-level",
  37 synchronous API, and a "low-level" asynchronous API. In both cases,
  38 incoming requests from the kernel are passed to the main program using
  39 callbacks. When using the high-level API, the callbacks may work with
  40 file names and paths instead of inodes, and processing of a request
  41 finishes when the callback function returns. When using the low-level
  42 API, the callbacks must work with inodes and responses must be sent
  43 explicitly using a separate set of API functions.
  44
  45
  46 Installation
  47 ------------
  48
  49     ./configure
  50     make -j8
  51     make install
  52
  53 You may also need to add `/usr/local/lib` to `/etc/ld.so.conf` and/or
  54 run *ldconfig*. If you're building from the git repository (instead of
  55 using a release tarball), you also need to run `./makeconf.sh` to
  56 create the `configure` script.
  57
  58 You'll also need a fuse kernel module (Linux kernels 2.6.14 or later
  59 contain FUSE support).
  60
  61 For more details see the file `INSTALL`
  62
  63 Security implications
  64 ---------------------
  65
  66 If you run `make install`, the *fusermount* program is installed
  67 set-user-id to root.  This is done to allow normal users to mount
  68 their own filesystem implementations.
  69
  70 There must however be some limitations, in order to prevent Bad User from
  71 doing nasty things.  Currently those limitations are:
  72
  73   - The user can only mount on a mountpoint, for which it has write
  74     permission
  75
  76   - The mountpoint is not a sticky directory which isn't owned by the
  77     user (like /tmp usually is)
  78
  79   - No other user (including root) can access the contents of the
  80     mounted filesystem (though this can be relaxed by allowing the use
  81     of the `allow_other` and `allow_root` mount options in `fuse.conf`)
  82
  83
  84 Building your own filesystem
  85 ------------------------------
  86
  87 FUSE comes with several example file systems in the `examples`
  88 directory. For example, the *fusexmp* example mirrors the contents of
  89 the root directory under the mountpoint. Start from there and adapt
  90 the code!
  91
  92 The documentation of the API functions and necessary callbacks is
  93 mostly contained in the files `include/fuse.h` (for the high-level
  94 API) and `include/fuse_lowlevel.h` (for the low-level API). An
  95 autogenerated html version of the API is available in the `doc/html`
  96 directory and at http://libfuse.github.io/doxygen.
  97
  98
  99 Getting Help
 100 ------------
 101
 102 If you need help, please ask on the <fuse-devel@lists.sourceforge.net>
 103 mailing list (subscribe at
 104 https://lists.sourceforge.net/lists/listinfo/fuse-devel).
 105
 106 Please report any bugs on the GitHub issue tracker at
 107 https://github.com/libfuse/main/issues.
 108