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 optionq 77 78 $ # ensure all meson options are applied to the final build system 79 $ meson setup --reconfigure ../ 80 81To build, test, and install libfuse, you then use Ninja: 82 83 $ ninja 84 $ sudo python3 -m pytest test/ 85 $ sudo ninja install 86 87Running the tests requires the [py.test](http://www.pytest.org/) 88Python module. Instead of running the tests as root, the majority of 89tests can also be run as a regular user if *util/fusermount3* is made 90setuid root first: 91 92 $ sudo chown root:root util/fusermount3 93 $ sudo chmod 4755 util/fusermount3 94 $ python3 -m pytest test/ 95 96Security implications 97--------------------- 98 99The *fusermount3* program is installed setuid root. This is done to 100allow normal users to mount their own filesystem implementations. 101 102To limit the harm that malicious users can do this way, *fusermount3* 103enforces the following limitations: 104 105 - The user can only mount on a mountpoint for which they have write 106 permission 107 108 - The mountpoint must not be a sticky directory which isn't owned by 109 the user (like /tmp usually is) 110 111 - No other user (including root) can access the contents of the 112 mounted filesystem (though this can be relaxed by allowing the use 113 of the *allow_other* and *allow_root* mount options in 114 */etc/fuse.conf*) 115 116 117If you intend to use the *allow_other* mount options, be aware that 118FUSE has an unresolved [security 119bug](https://github.com/libfuse/libfuse/issues/15): if the 120*default_permissions* mount option is not used, the results of the 121first permission check performed by the file system for a directory 122entry will be re-used for subsequent accesses as long as the inode of 123the accessed entry is present in the kernel cache - even if the 124permissions have since changed, and even if the subsequent access is 125made by a different user. This is of little concern if the filesystem 126is accessible only to the mounting user (which has full access to the 127filesystem anyway), but becomes a security issue when other users are 128allowed to access the filesystem (since they can exploit this to 129perform operations on the filesystem that they do not actually have 130permissions for). 131 132This bug needs to be fixed in the Linux kernel and has been known 133since 2006 but unfortunately no fix has been applied yet. If you 134depend on correct permission handling for FUSE file systems, the only 135workaround is to use `default_permissions` (which does not currently 136support ACLs), or to completely disable caching of directory entry 137attributes. 138 139Building your own filesystem 140------------------------------ 141 142FUSE comes with several example file systems in the `example` 143directory. For example, the *passthrough* examples mirror the contents 144of the root directory under the mountpoint. Start from there and adapt 145the code! 146 147The documentation of the API functions and necessary callbacks is 148mostly contained in the files `include/fuse.h` (for the high-level 149API) and `include/fuse_lowlevel.h` (for the low-level API). An 150autogenerated html version of the API is available in the `doc/html` 151directory and at http://libfuse.github.io/doxygen. 152 153 154Getting Help 155------------ 156 157If you need help, please ask on the <[email protected]> 158mailing list (subscribe at 159https://lists.sourceforge.net/lists/listinfo/fuse-devel). 160 161Please report any bugs on the GitHub issue tracker at 162https://github.com/libfuse/libfuse/issues. 163