Repository files navigation

This is a fork of the libfuse reference implementation which may be found here:https://github.com/libfuse/libfuse

This fork is designed to build withCMake, otherwise it should be identical tothe reference platform. The best reference for using libfuse is the referenceimplementation. BUT - This is the place to come for information about buildinglibfuse with CMake instead of meson.

FUSE (Filesystem in Userspace) is an interface for userspace programsto export a filesystem to the Linux kernel. The FUSE project consistsof two components: thefuse kernel module (maintained in the regularkernel repositories) and thelibfuse userspace library (maintainedin this repository). libfuse provides the reference implementationfor communicating with the FUSE kernel module.

A FUSE file system is typically implemented as a standaloneapplication that links with libfuse. libfuse provides functions tomount the file system, unmount it, read requests from the kernel, andsend responses back. libfuse offers two APIs: a "high-level",synchronous API, and a "low-level" asynchronous API. In both cases,incoming requests from the kernel are passed to the main program usingcallbacks. When using the high-level API, the callbacks may work withfile names and paths instead of inodes, and processing of a requestfinishes when the callback function returns. When using the low-levelAPI, the callbacks must work with inodes and responses must be sentexplicitly using a separate set of API functions.

libfuse is shipped by all major Linux distributions and has been inproduction use across a wide range of systems for many years. However,at present libfuse does not have any active, regular contributors. Thecurrent maintainer continues to apply pull requests and makes regularreleases, but unfortunately has no capacity to do any developmentbeyond addressing high-impact issues. When reporting bugs, pleaseunderstand that unless you are including a pull request or arereporting a critical issue, you will probably not get a response. Ifyou are using libfuse, please consider contributing to the project.

• Linux (fully)
• BSD (mostly/best-effort)
• For OS-X, please useOSXFUSE

You can download libfuse fromhttps://github.com/libfuse/libfuse/releases. To build andinstall, you must useMeson andNinja; or,CMake. After downloading the tarball and.sig file, verifyit usingsignify:

signify -V -m fuse-X.Y.Z.tar.gz -p fuse-X.Y.pub

Thefuse-X.Y.pub file contains the signing key and needs to be obtained from atrustworthy source. Each libfuse release contains the signing key for the release after itin thesignify directory, so you only need to manually acquire this file once when youinstall libfuse for the first time.

To build and install, you are free to use meson or CMake

We recommend to useCMake the hugely superior meta-makesystem. CMake allows a developer to use a wide variety of build systems andincludes native support for various command-line or GUI environments such asVisual Studio, Eclipse, CodeBlocks, Ninja, or plain old Unix make.

You are free to use the Unix make, Ninja, or any other CMake supported makesystem - see, CMake is better than meson !

Out of source builds arehighly recommended. Simply create a (temporary)build directory and run CMake:

$ mkdir build; cd build$ cmake ..

Normally, the default build options will work fine. However, to build examples,tests, and other recommended utilities, you will probably want to do this:(this also explicitly uses Unix Makefiles - the cmake default)

   $ cmake -G "Unix Makefiles" \                -DOPTION_BUILD_UTILS=ON \                -DOPTION_BUILD_EXAMPLES=ON \                -DCMAKE_INSTALL_PREFIX=/home/<USER>/FUSE/install \                -DCMAKE_BUILD_TYPE=Debug ..

To build, test and install, you then use make (or other supported build systems):

The equivalent for Meson build is as follows:

$ meson configure # list options$ meson configure -D disable-mtab=true # set an optionq$ # ensure all meson options are applied to the final build system$ meson setup --reconfigure ../

IMPORTANT !!! - Almost all tests will fail unless you either

• run as root
• change permissions on util/fusermount3 (see blow)

    $ make    $ python3 -m pytest test/    $ sudo make install

NOTE: One of the primary outstanding issues (with this libfuse-Cmake fork) isto remove any dependency upon python. Expect to see native ctest replace pythonpytest soon. IMPORTANT - Tests current perform best when run under python3.6.Issues have been reported attempting to use python3.7 with pytest.

Running the tests requires thepy.test Python module.

Instead of running the tests as root, the majority oftests can also be run as a regular user ifutil/fusermount3 is madesetuid root first:

$ sudo chown root:root util/fusermount3$ sudo chmod 4755 util/fusermount3$ python3 -m pytest test/

NOTE: Some tests are designed to "drop privileges" and so will be skipped if theuser is not root.

Thefusermount3 program is installed setuid root. This is done toallow normal users to mount their own filesystem implementations.

To limit the harm that malicious users can do this way,fusermount3enforces the following limitations:

• The user can only mount on a mountpoint for which they have writepermission

• The mountpoint must not be a sticky directory which isn't owned bythe user (like /tmp usually is)

• No other user (including root) can access the contents of themounted filesystem (though this can be relaxed by allowing the useof theallow_other andallow_root mount options in/etc/fuse.conf)

If you intend to use theallow_other mount options, be aware thatFUSE has an unresolvedsecuritybug: if thedefault_permissions mount option is not used, the results of thefirst permission check performed by the file system for a directoryentry will be re-used for subsequent accesses as long as the inode ofthe accessed entry is present in the kernel cache - even if thepermissions have since changed, and even if the subsequent access ismade by a different user. This is of little concern if the filesystemis accessible only to the mounting user (which has full access to thefilesystem anyway), but becomes a security issue when other users areallowed to access the filesystem (since they can exploit this toperform operations on the filesystem that they do not actually havepermissions for).

This bug needs to be fixed in the Linux kernel and has been knownsince 2006 but unfortunately no fix has been applied yet. If youdepend on correct permission handling for FUSE file systems, the onlyworkaround is to usedefault_permissions (which does not currentlysupport ACLs), or to completely disable caching of directory entryattributes.

FUSE comes with several example file systems in theexampledirectory. For example, thepassthrough examples mirror the contentsof the root directory under the mountpoint. Start from there and adaptthe code!

The documentation of the API functions and necessary callbacks ismostly contained in the filesinclude/fuse.h (for the high-levelAPI) andinclude/fuse_lowlevel.h (for the low-level API). Anautogenerated html version of the API is available in thedoc/htmldirectory and athttp://libfuse.github.io/doxygen.

If you need help, please ask on thefuse-devel@lists.sourceforge.netmailing list (subscribe athttps://lists.sourceforge.net/lists/listinfo/fuse-devel).

Please report any bugs on the GitHub issue tracker athttps://github.com/libfuse/libfuse/issues.

Please report CMake related libfuse bugs here:https://github.com/Smit-tay/libfuse-cmake/issues

Professional support is offered viaRath Consulting.