diff options
author | Daniel W. S. Almeida <dwlsalmeida@gmail.com> | 2020-01-29 08:06:21 +0300 |
---|---|---|
committer | Miklos Szeredi <mszeredi@redhat.com> | 2020-02-06 18:39:28 +0300 |
commit | 8ab13bca428bb98e98d1933eaeacc90e80cf6192 (patch) | |
tree | 9f1f643d39c782587adcd3c341de11e3cad42f8d /Documentation/filesystems/fuse.txt | |
parent | 519525fa47b5a8155f0b203e49a3a6a2319f75ae (diff) | |
download | linux-8ab13bca428bb98e98d1933eaeacc90e80cf6192.tar.xz |
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>
Diffstat (limited to 'Documentation/filesystems/fuse.txt')
-rw-r--r-- | Documentation/filesystems/fuse.txt | 423 |
1 files changed, 0 insertions, 423 deletions
diff --git a/Documentation/filesystems/fuse.txt b/Documentation/filesystems/fuse.txt deleted file mode 100644 index 13af4a49e7db..000000000000 --- a/Documentation/filesystems/fuse.txt +++ /dev/null @@ -1,423 +0,0 @@ -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 - 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 -(fusermount). - -One of the most important features of FUSE is allowing secure, -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/ - -Filesystem type -~~~~~~~~~~~~~~~ - -The filesystem type given to mount(2) can be one of the following: - -'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. - -'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' - - 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' - - The file mode of the filesystem's root in octal representation. - -'user_id=N' - - The numeric user id of the mount owner. - -'group_id=N' - - The numeric group id of the mount owner. - -'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 - filesystems). This option enables permission checking, restricting - access based on file mode. It is usually useful together with the - 'allow_other' mount option. - -'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' - - 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' - - 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: - - mount -t fusectl none /sys/fs/fuse/connections - -Mounting it under the '/sys/fs/fuse/connections' directory makes it -backwards compatible with earlier versions. - -Under the fuse control filesystem each connection has a directory -named by a unique number. - -For each connection the following files exist within this directory: - - '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. - - '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 - 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 - 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 - 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 -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 - processed - - 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 -some timeout and/or a number of new requests to arrive, after which it -should reply to the INTERRUPT request with an EAGAIN error. In case -1) the INTERRUPT request will be requeued. In case 2) the INTERRUPT -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: - - a) Broken userspace filesystem implementation - - b) Network connection down - - c) Accidental deadlock - - d) Malicious deadlock - -(For more on c) and d) see later sections) - -In either of these cases it may be useful to abort the connection to -the filesystem. There are several ways to do this: - - - Kill the filesystem daemon. Works in case of a) and b) - - - Kill the filesystem daemon and all users of the filesystem. Works - in all cases except some malicious deadlocks - - - Use forced umount (umount -f). Works in all cases but only if - filesystem is still attached (it hasn't been lazy unmounted) - - - Abort filesystem through the FUSE control filesystem. Most - 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. - -The implication of providing non-privileged mounts is that the mount -owner must not be able to use this capability to compromise the -system. Obvious requirements arising from this are: - - A) mount owner should not be able to get elevated privileges with the - help of the mounted filesystem - - B) mount owner should not get illegitimate access to information from - other users' and the super user's processes - - C) mount owner should not be able to induce undesired behavior in - 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 - - 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 - fusermount always adds "nosuid" and "nodev" to the mount options - for non-privileged mounts. - - B) If another user is accessing files or directories in the - filesystem, the filesystem daemon serving requests can record the - exact sequence and timing of operations performed. This - information is otherwise inaccessible to the mount owner, so this - counts as an information leak. - - The solution to this problem will be presented in point 2) of C). - - C) There are several ways in which the mount owner can induce - undesired behavior in other users' processes, such as: - - 1) mounting a filesystem over a file or directory which the mount - owner could otherwise not be able to modify (or could only - make limited modifications). - - This is solved in fusermount, by checking the access - permissions on the mountpoint and only allowing the mount if - the mount owner can do unlimited modification (has write - access to the mountpoint, and mountpoint is not a "sticky" - directory) - - 2) Even if 1) is solved the mount owner can change the behavior - 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. - - 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. - - The solution to this as well as B) is not to allow processes - to access the filesystem, which could otherwise not be - monitored or manipulated by the mount owner. Since if the - mount owner can ptrace a process, it can do all of the above - without using a FUSE mount, the same criteria as used in - 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 - 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. - -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" -config option. If this config option is set, the mounting user can -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. - -NOTE: everything in this description is greatly simplified - - | "rm /mnt/fuse/file" | FUSE filesystem daemon - | | - | | >sys_read() - | | >fuse_dev_read() - | | >request_wait() - | | [sleep on fc->waitq] - | | - | >sys_unlink() | - | >fuse_unlink() | - | [get request from | - | fc->unused_list] | - | >request_send() | - | [queue req on fc->pending] | - | [wake up fc->waitq] | [woken up] - | >request_wait_answer() | - | [sleep on req->waitq] | - | | <request_wait() - | | [remove req from fc->pending] - | | [copy req to read buffer] - | | [add req to fc->processing] - | | <fuse_dev_read() - | | <sys_read() - | | - | | [perform unlink] - | | - | | >sys_write() - | | >fuse_dev_write() - | | [look up req in fc->processing] - | | [remove from fc->processing] - | | [copy write buffer to req] - | [woken up] | [wake up req->waitq] - | | <fuse_dev_write() - | | <sys_write() - | <request_wait_answer() | - | <request_send() | - | [add request to | - | fc->unused_list] | - | <fuse_unlink() | - | <sys_unlink() | - -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 ------------------------------ - - | "rm /mnt/fuse/file" | FUSE filesystem daemon - | | - | >sys_unlink("/mnt/fuse/file") | - | [acquire inode semaphore | - | for "file"] | - | >fuse_unlink() | - | [sleep on req->waitq] | - | | <sys_read() - | | >sys_unlink("/mnt/fuse/file") - | | [acquire inode semaphore - | | for "file"] - | | *DEADLOCK* - -The solution for this is to allow the filesystem to be aborted. - -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. - - | Kamikaze filesystem thread 1 | Kamikaze filesystem thread 2 - | | - | [fd = open("/mnt/fuse/file")] | [request served normally] - | [mmap fd to 'addr'] | - | [close fd] | [FLUSH triggers 'magic' flag] - | [read a byte from addr] | - | >do_page_fault() | - | [find or create page] | - | [lock page] | - | >fuse_readpage() | - | [queue READ request] | - | [sleep on req->waitq] | - | | [read request to buffer] - | | [create reply header before addr] - | | >sys_write(addr - headerlength) - | | >fuse_dev_write() - | | [look up req in fc->processing] - | | [remove from fc->processing] - | | [copy write buffer to req] - | | >do_page_fault() - | | [find or create page] - | | [lock page] - | | * DEADLOCK * - -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 -because the destination address of the copy may not be valid after the -request has returned. - -This is solved with doing the copy atomically, and allowing abort -while the page(s) belonging to the write buffer are faulted with -get_user_pages(). The 'req->locked' flag indicates when the copy is -taking place, and abort is delayed until this flag is unset. |