1libfuse 2======= 3 4About 5----- 6 7FUSE (Filesystem in Userspace) is an interface for userspace programs 8to export a filesystem to the Linux kernel. The FUSE project consists 9of two components: the *fuse* kernel module (maintained in the regular 10kernel repositories) and the *libfuse* userspace library (maintained 11in this repository). libfuse provides the reference implementation 12for communicating with the FUSE kernel module. 13 14A FUSE file system is typically implemented as a standalone 15application that links with libfuse. libfuse provides functions to 16mount the file system, unmount it, read requests from the kernel, and 17send responses back. libfuse offers two APIs: a "high-level", 18synchronous API, and a "low-level" asynchronous API. In both cases, 19incoming requests from the kernel are passed to the main program using 20callbacks. When using the high-level API, the callbacks may work with 21file names and paths instead of inodes, and processing of a request 22finishes when the callback function returns. When using the low-level 23API, the callbacks must work with inodes and responses must be sent 24explicitly using a separate set of API functions. 25 26 27Development Status 28------------------ 29 30libfuse is shipped by all major Linux distributions and has been in 31production use across a wide range of systems for many years. However, 32at present libfuse does not have any active, regular contributors. The 33current maintainer continues to apply pull requests and makes regular 34releases, but unfortunately has no capacity to do any development 35beyond addressing high-impact issues. When reporting bugs, please 36understand that unless you are including a pull request or are 37reporting a critical issue, you will probably not get a response. If 38you are using libfuse, please consider contributing to the project. 39 40 41Supported Platforms 42------------------- 43 44* Linux (fully) 45* BSD (mostly/best-effort) 46* For OS-X, please use [OSXFUSE](https://osxfuse.github.io/) 47 48 49Installation 50------------ 51 52You can download libfuse from https://github.com/libfuse/libfuse/releases. To build and 53install, you must use [Meson](http://mesonbuild.com/) and 54[Ninja](https://ninja-build.org). After downloading the tarball and `.sig` file, verify 55it using [signify](https://www.openbsd.org/papers/bsdcan-signify.html): 56 57 signify -V -m fuse-X.Y.Z.tar.gz -p fuse-X.Y.pub 58 59The `fuse-X.Y.pub` file contains the signing key and needs to be obtained from a 60trustworthy source. Each libfuse release contains the signing key for the release after it 61in the `signify` directory, so you only need to manually acquire this file once when you 62install libfuse for the first time. 63 64After you have validated the tarball, extract it, create a (temporary) build directory and 65run Meson: 66 67 $ tar xzf fuse-X.Y.Z.tar.gz; cd fuse-X.Y.Z 68 $ mkdir build; cd build 69 $ meson setup .. 70 71Normally, the default build options will work fine. If you 72nevertheless want to adjust them, you can do so with the 73*meson configure* command: 74 75 $ meson configure # list options 76 $ meson configure -D disable-mtab=true # set an option 77 78To build, test, and install libfuse, you then use Ninja: 79 80 $ ninja 81 $ sudo python3 -m pytest test/ 82 $ sudo ninja install 83 84Running the tests requires the [py.test](http://www.pytest.org/) 85Python module. Instead of running the tests as root, the majority of 86tests can also be run as a regular user if *util/fusermount3* is made 87setuid root first: 88 89 $ sudo chown root:root util/fusermount3 90 $ sudo chmod 4755 util/fusermount3 91 $ python3 -m pytest test/ 92 93Security implications 94--------------------- 95 96The *fusermount3* program is installed setuid root. This is done to 97allow normal users to mount their own filesystem implementations. 98 99To limit the harm that malicious users can do this way, *fusermount3* 100enforces the following limitations: 101 102 - The user can only mount on a mountpoint for which they have write 103 permission 104 105 - The mountpoint must not be a sticky directory which isn't owned by 106 the user (like /tmp usually is) 107 108 - No other user (including root) can access the contents of the 109 mounted filesystem (though this can be relaxed by allowing the use 110 of the *allow_other* and *allow_root* mount options in 111 */etc/fuse.conf*) 112 113 114If you intend to use the *allow_other* mount options, be aware that 115FUSE has an unresolved [security 116bug](https://github.com/libfuse/libfuse/issues/15): if the 117*default_permissions* mount option is not used, the results of the 118first permission check performed by the file system for a directory 119entry will be re-used for subsequent accesses as long as the inode of 120the accessed entry is present in the kernel cache - even if the 121permissions have since changed, and even if the subsequent access is 122made by a different user. This is of little concern if the filesystem 123is accessible only to the mounting user (which has full access to the 124filesystem anyway), but becomes a security issue when other users are 125allowed to access the filesystem (since they can exploit this to 126perform operations on the filesystem that they do not actually have 127permissions for). 128 129This bug needs to be fixed in the Linux kernel and has been known 130since 2006 but unfortunately no fix has been applied yet. If you 131depend on correct permission handling for FUSE file systems, the only 132workaround is to use `default_permissions` (which does not currently 133support ACLs), or to completely disable caching of directory entry 134attributes. 135 136Building your own filesystem 137------------------------------ 138 139FUSE comes with several example file systems in the `example` 140directory. For example, the *passthrough* examples mirror the contents 141of the root directory under the mountpoint. Start from there and adapt 142the code! 143 144The documentation of the API functions and necessary callbacks is 145mostly contained in the files `include/fuse.h` (for the high-level 146API) and `include/fuse_lowlevel.h` (for the low-level API). An 147autogenerated html version of the API is available in the `doc/html` 148directory and at http://libfuse.github.io/doxygen. 149 150 151Getting Help 152------------ 153 154If you need help, please ask on the <fuse-devel@lists.sourceforge.net> 155mailing list (subscribe at 156https://lists.sourceforge.net/lists/listinfo/fuse-devel). 157 158Please report any bugs on the GitHub issue tracker at 159https://github.com/libfuse/libfuse/issues. 160