Skip to content

Commit ea211ba

Browse files
KrxkGitKrxkGit
committed
Add documents
1 parent 00db107 commit ea211ba

5 files changed

+1782
-157
lines changed

‎README-Libfuse.md

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

0 commit comments

Comments
 (0)