Documentation: filesystems: convert fuse to RST
Converts fuse.txt to reStructuredText format, improving the presentation without changing much of the underlying content. Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com> Signed-off-by: Miklos Szeredi <mszeredi@redhat.com>
This commit is contained in:
Daniel W. S. Almeida
Miklos Szeredi
parent
519525fa47
commit
8ab13bca42
|
|
@ -1,41 +1,40 @@
|
|||
.. SPDX-License-Identifier: GPL-2.0
|
||||
==============
|
||||
FUSE
|
||||
==============
|
||||
|
||||
Definitions
|
||||
~~~~~~~~~~~
|
||||
===========
|
||||
|
||||
Userspace filesystem:
|
||||
|
||||
A filesystem in which data and metadata are provided by an ordinary
|
||||
userspace process. The filesystem can be accessed normally through
|
||||
the kernel interface.
|
||||
|
||||
Filesystem daemon:
|
||||
|
||||
The process(es) providing the data and metadata of the filesystem.
|
||||
|
||||
Non-privileged mount (or user mount):
|
||||
|
||||
A userspace filesystem mounted by a non-privileged (non-root) user.
|
||||
The filesystem daemon is running with the privileges of the mounting
|
||||
user. NOTE: this is not the same as mounts allowed with the "user"
|
||||
option in /etc/fstab, which is not discussed here.
|
||||
|
||||
Filesystem connection:
|
||||
|
||||
A connection between the filesystem daemon and the kernel. The
|
||||
connection exists until either the daemon dies, or the filesystem is
|
||||
umounted. Note that detaching (or lazy umounting) the filesystem
|
||||
does _not_ break the connection, in this case it will exist until
|
||||
does *not* break the connection, in this case it will exist until
|
||||
the last reference to the filesystem is released.
|
||||
|
||||
Mount owner:
|
||||
|
||||
The user who does the mounting.
|
||||
|
||||
User:
|
||||
|
||||
The user who is performing filesystem operations.
|
||||
|
||||
What is FUSE?
|
||||
~~~~~~~~~~~~~
|
||||
=============
|
||||
|
||||
FUSE is a userspace filesystem framework. It consists of a kernel
|
||||
module (fuse.ko), a userspace library (libfuse.*) and a mount utility
|
||||
|
|
@ -46,50 +45,41 @@ non-privileged mounts. This opens up new possibilities for the use of
|
|||
filesystems. A good example is sshfs: a secure network filesystem
|
||||
using the sftp protocol.
|
||||
|
||||
The userspace library and utilities are available from the FUSE
|
||||
homepage:
|
||||
|
||||
http://fuse.sourceforge.net/
|
||||
The userspace library and utilities are available from the
|
||||
`FUSE homepage: <http://fuse.sourceforge.net/>`_
|
||||
|
||||
Filesystem type
|
||||
~~~~~~~~~~~~~~~
|
||||
===============
|
||||
|
||||
The filesystem type given to mount(2) can be one of the following:
|
||||
|
||||
'fuse'
|
||||
fuse
|
||||
This is the usual way to mount a FUSE filesystem. The first
|
||||
argument of the mount system call may contain an arbitrary string,
|
||||
which is not interpreted by the kernel.
|
||||
|
||||
This is the usual way to mount a FUSE filesystem. The first
|
||||
argument of the mount system call may contain an arbitrary string,
|
||||
which is not interpreted by the kernel.
|
||||
|
||||
'fuseblk'
|
||||
|
||||
The filesystem is block device based. The first argument of the
|
||||
mount system call is interpreted as the name of the device.
|
||||
fuseblk
|
||||
The filesystem is block device based. The first argument of the
|
||||
mount system call is interpreted as the name of the device.
|
||||
|
||||
Mount options
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
'fd=N'
|
||||
=============
|
||||
|
||||
fd=N
|
||||
The file descriptor to use for communication between the userspace
|
||||
filesystem and the kernel. The file descriptor must have been
|
||||
obtained by opening the FUSE device ('/dev/fuse').
|
||||
|
||||
'rootmode=M'
|
||||
|
||||
rootmode=M
|
||||
The file mode of the filesystem's root in octal representation.
|
||||
|
||||
'user_id=N'
|
||||
|
||||
user_id=N
|
||||
The numeric user id of the mount owner.
|
||||
|
||||
'group_id=N'
|
||||
|
||||
group_id=N
|
||||
The numeric group id of the mount owner.
|
||||
|
||||
'default_permissions'
|
||||
|
||||
default_permissions
|
||||
By default FUSE doesn't check file access permissions, the
|
||||
filesystem is free to implement its access policy or leave it to
|
||||
the underlying file access mechanism (e.g. in case of network
|
||||
|
|
@ -97,28 +87,25 @@ Mount options
|
|||
access based on file mode. It is usually useful together with the
|
||||
'allow_other' mount option.
|
||||
|
||||
'allow_other'
|
||||
|
||||
allow_other
|
||||
This option overrides the security measure restricting file access
|
||||
to the user mounting the filesystem. This option is by default only
|
||||
allowed to root, but this restriction can be removed with a
|
||||
(userspace) configuration option.
|
||||
|
||||
'max_read=N'
|
||||
|
||||
max_read=N
|
||||
With this option the maximum size of read operations can be set.
|
||||
The default is infinite. Note that the size of read requests is
|
||||
limited anyway to 32 pages (which is 128kbyte on i386).
|
||||
|
||||
'blksize=N'
|
||||
|
||||
blksize=N
|
||||
Set the block size for the filesystem. The default is 512. This
|
||||
option is only valid for 'fuseblk' type mounts.
|
||||
|
||||
Control filesystem
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
==================
|
||||
|
||||
There's a control filesystem for FUSE, which can be mounted by:
|
||||
There's a control filesystem for FUSE, which can be mounted by::
|
||||
|
||||
mount -t fusectl none /sys/fs/fuse/connections
|
||||
|
||||
|
|
@ -130,53 +117,51 @@ named by a unique number.
|
|||
|
||||
For each connection the following files exist within this directory:
|
||||
|
||||
'waiting'
|
||||
waiting
|
||||
The number of requests which are waiting to be transferred to
|
||||
userspace or being processed by the filesystem daemon. If there is
|
||||
no filesystem activity and 'waiting' is non-zero, then the
|
||||
filesystem is hung or deadlocked.
|
||||
|
||||
The number of requests which are waiting to be transferred to
|
||||
userspace or being processed by the filesystem daemon. If there is
|
||||
no filesystem activity and 'waiting' is non-zero, then the
|
||||
filesystem is hung or deadlocked.
|
||||
|
||||
'abort'
|
||||
|
||||
Writing anything into this file will abort the filesystem
|
||||
connection. This means that all waiting requests will be aborted an
|
||||
error returned for all aborted and new requests.
|
||||
abort
|
||||
Writing anything into this file will abort the filesystem
|
||||
connection. This means that all waiting requests will be aborted an
|
||||
error returned for all aborted and new requests.
|
||||
|
||||
Only the owner of the mount may read or write these files.
|
||||
|
||||
Interrupting filesystem operations
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
##################################
|
||||
|
||||
If a process issuing a FUSE filesystem request is interrupted, the
|
||||
following will happen:
|
||||
|
||||
1) If the request is not yet sent to userspace AND the signal is
|
||||
- If the request is not yet sent to userspace AND the signal is
|
||||
fatal (SIGKILL or unhandled fatal signal), then the request is
|
||||
dequeued and returns immediately.
|
||||
|
||||
2) If the request is not yet sent to userspace AND the signal is not
|
||||
fatal, then an 'interrupted' flag is set for the request. When
|
||||
- If the request is not yet sent to userspace AND the signal is not
|
||||
fatal, then an interrupted flag is set for the request. When
|
||||
the request has been successfully transferred to userspace and
|
||||
this flag is set, an INTERRUPT request is queued.
|
||||
|
||||
3) If the request is already sent to userspace, then an INTERRUPT
|
||||
- If the request is already sent to userspace, then an INTERRUPT
|
||||
request is queued.
|
||||
|
||||
INTERRUPT requests take precedence over other requests, so the
|
||||
userspace filesystem will receive queued INTERRUPTs before any others.
|
||||
|
||||
The userspace filesystem may ignore the INTERRUPT requests entirely,
|
||||
or may honor them by sending a reply to the _original_ request, with
|
||||
or may honor them by sending a reply to the *original* request, with
|
||||
the error set to EINTR.
|
||||
|
||||
It is also possible that there's a race between processing the
|
||||
original request and its INTERRUPT request. There are two possibilities:
|
||||
|
||||
1) The INTERRUPT request is processed before the original request is
|
||||
1. The INTERRUPT request is processed before the original request is
|
||||
processed
|
||||
|
||||
2) The INTERRUPT request is processed after the original request has
|
||||
2. The INTERRUPT request is processed after the original request has
|
||||
been answered
|
||||
|
||||
If the filesystem cannot find the original request, it should wait for
|
||||
|
|
@ -186,7 +171,7 @@ should reply to the INTERRUPT request with an EAGAIN error. In case
|
|||
reply will be ignored.
|
||||
|
||||
Aborting a filesystem connection
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
================================
|
||||
|
||||
It is possible to get into certain situations where the filesystem is
|
||||
not responding. Reasons for this may be:
|
||||
|
|
@ -216,7 +201,7 @@ the filesystem. There are several ways to do this:
|
|||
powerful method, always works.
|
||||
|
||||
How do non-privileged mounts work?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
==================================
|
||||
|
||||
Since the mount() system call is a privileged operation, a helper
|
||||
program (fusermount) is needed, which is installed setuid root.
|
||||
|
|
@ -235,15 +220,13 @@ system. Obvious requirements arising from this are:
|
|||
other users' or the super user's processes
|
||||
|
||||
How are requirements fulfilled?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
===============================
|
||||
|
||||
A) The mount owner could gain elevated privileges by either:
|
||||
|
||||
1) creating a filesystem containing a device file, then opening
|
||||
this device
|
||||
1. creating a filesystem containing a device file, then opening this device
|
||||
|
||||
2) creating a filesystem containing a suid or sgid application,
|
||||
then executing this application
|
||||
2. creating a filesystem containing a suid or sgid application, then executing this application
|
||||
|
||||
The solution is not to allow opening device files and ignore
|
||||
setuid and setgid bits when executing programs. To ensure this
|
||||
|
|
@ -275,16 +258,16 @@ How are requirements fulfilled?
|
|||
of other users' processes.
|
||||
|
||||
i) It can slow down or indefinitely delay the execution of a
|
||||
filesystem operation creating a DoS against the user or the
|
||||
whole system. For example a suid application locking a
|
||||
system file, and then accessing a file on the mount owner's
|
||||
filesystem could be stopped, and thus causing the system
|
||||
file to be locked forever.
|
||||
filesystem operation creating a DoS against the user or the
|
||||
whole system. For example a suid application locking a
|
||||
system file, and then accessing a file on the mount owner's
|
||||
filesystem could be stopped, and thus causing the system
|
||||
file to be locked forever.
|
||||
|
||||
ii) It can present files or directories of unlimited length, or
|
||||
directory structures of unlimited depth, possibly causing a
|
||||
system process to eat up diskspace, memory or other
|
||||
resources, again causing DoS.
|
||||
directory structures of unlimited depth, possibly causing a
|
||||
system process to eat up diskspace, memory or other
|
||||
resources, again causing *DoS*.
|
||||
|
||||
The solution to this as well as B) is not to allow processes
|
||||
to access the filesystem, which could otherwise not be
|
||||
|
|
@ -294,28 +277,27 @@ How are requirements fulfilled?
|
|||
ptrace can be used to check if a process is allowed to access
|
||||
the filesystem or not.
|
||||
|
||||
Note that the ptrace check is not strictly necessary to
|
||||
Note that the *ptrace* check is not strictly necessary to
|
||||
prevent B/2/i, it is enough to check if mount owner has enough
|
||||
privilege to send signal to the process accessing the
|
||||
filesystem, since SIGSTOP can be used to get a similar effect.
|
||||
filesystem, since *SIGSTOP* can be used to get a similar effect.
|
||||
|
||||
I think these limitations are unacceptable?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
===========================================
|
||||
|
||||
If a sysadmin trusts the users enough, or can ensure through other
|
||||
measures, that system processes will never enter non-privileged
|
||||
mounts, it can relax the last limitation with a "user_allow_other"
|
||||
mounts, it can relax the last limitation with a 'user_allow_other'
|
||||
config option. If this config option is set, the mounting user can
|
||||
add the "allow_other" mount option which disables the check for other
|
||||
add the 'allow_other' mount option which disables the check for other
|
||||
users' processes.
|
||||
|
||||
Kernel - userspace interface
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
============================
|
||||
|
||||
The following diagram shows how a filesystem operation (in this
|
||||
example unlink) is performed in FUSE.
|
||||
example unlink) is performed in FUSE. ::
|
||||
|
||||
NOTE: everything in this description is greatly simplified
|
||||
|
||||
| "rm /mnt/fuse/file" | FUSE filesystem daemon
|
||||
| |
|
||||
|
|
@ -357,12 +339,13 @@ NOTE: everything in this description is greatly simplified
|
|||
| <fuse_unlink() |
|
||||
| <sys_unlink() |
|
||||
|
||||
.. note:: Everything in the description above is greatly simplified
|
||||
|
||||
There are a couple of ways in which to deadlock a FUSE filesystem.
|
||||
Since we are talking about unprivileged userspace programs,
|
||||
something must be done about these.
|
||||
|
||||
Scenario 1 - Simple deadlock
|
||||
-----------------------------
|
||||
**Scenario 1 - Simple deadlock**::
|
||||
|
||||
| "rm /mnt/fuse/file" | FUSE filesystem daemon
|
||||
| |
|
||||
|
|
@ -379,12 +362,12 @@ Scenario 1 - Simple deadlock
|
|||
|
||||
The solution for this is to allow the filesystem to be aborted.
|
||||
|
||||
Scenario 2 - Tricky deadlock
|
||||
----------------------------
|
||||
**Scenario 2 - Tricky deadlock**
|
||||
|
||||
|
||||
This one needs a carefully crafted filesystem. It's a variation on
|
||||
the above, only the call back to the filesystem is not explicit,
|
||||
but is caused by a pagefault.
|
||||
but is caused by a pagefault. ::
|
||||
|
||||
| Kamikaze filesystem thread 1 | Kamikaze filesystem thread 2
|
||||
| |
|
||||
|
|
@ -410,7 +393,7 @@ but is caused by a pagefault.
|
|||
| | [lock page]
|
||||
| | * DEADLOCK *
|
||||
|
||||
Solution is basically the same as above.
|
||||
The solution is basically the same as above.
|
||||
|
||||
An additional problem is that while the write buffer is being copied
|
||||
to the request, the request must not be interrupted/aborted. This is
|
||||
|
|
@ -47,4 +47,5 @@ Documentation for filesystem implementations.
|
|||
:maxdepth: 2
|
||||
|
||||
autofs
|
||||
fuse
|
||||
virtiofs
|
||||
|
|
|
|||
|
|
@ -6821,7 +6821,7 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/mszeredi/fuse.git
|
|||
S: Maintained
|
||||
F: fs/fuse/
|
||||
F: include/uapi/linux/fuse.h
|
||||
F: Documentation/filesystems/fuse.txt
|
||||
F: Documentation/filesystems/fuse.rst
|
||||
|
||||
FUTEX SUBSYSTEM
|
||||
M: Thomas Gleixner <tglx@linutronix.de>
|
||||
|
|
|
|||
Loading…
Reference in New Issue