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