From: Nikolaus Rath Date: Sun, 20 Dec 2015 21:52:30 +0000 (-0800) Subject: Migrated README to README.md for Markdown rendering on GitHub. X-Git-Tag: fuse-3.0.0pre0~69 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=dfbfd139ac7c4dbda1a4e2995e2ff5fe20d185c3;p=qemu-gpiodev%2Flibfuse.git Migrated README to README.md for Markdown rendering on GitHub. --- diff --git a/README b/README index 398dd65..5efad5c 100644 --- a/README +++ b/README @@ -1,380 +1,3 @@ -General Information -=================== +Please look at README.md -FUSE (Filesystem in Userspace) is a simple interface for userspace -programs to export a virtual filesystem to the Linux kernel. FUSE -also aims to provide a secure method for non privileged users to -create and mount their own filesystem implementations. - -You can download the source code releases from - - http://sourceforge.net/projects/fuse - -or alternatively you can use CVS to get the very latest development -version: - - cvs -d :pserver:anonymous@fuse.cvs.sourceforge.net:/cvsroot/fuse co fuse - - -Dependencies -============ - -Linux kernel version 2.6.X where X >= 9. - -Alternatively a kernel module from FUSE release 2.5.* can be used with -this release, which supports kernels >= 2.4.21. - -Installation -============ - -./configure -make -make install -modprobe fuse - -You may also need to add '/usr/local/lib' to '/etc/ld.so.conf' and/or -run ldconfig. - -You'll also need a fuse kernel module, Linux kernels 2.6.14 or later -contain FUSE support. - -For more details see the file 'INSTALL' - -How To Use -========== - -FUSE is made up of three main parts: - - - A kernel filesystem module - - - A userspace library - - - A mount/unmount program - - -Here's how to create your very own virtual filesystem in five easy -steps (after installing FUSE): - - 1) Edit the file example/fusexmp.c to do whatever you want... - - 2) Build the fusexmp program - - 3) run 'example/fusexmp /mnt/fuse -d' - - 4) ls -al /mnt/fuse - - 5) Be glad - -If it doesn't work out, please ask! Also see the file 'include/fuse.h' for -detailed documentation of the library interface. - -Security -======== - -If you run 'make install', the fusermount program is installed -set-user-id to root. This is done to allow normal users to mount -their own filesystem implementations. - -There must however be some limitations, in order to prevent Bad User from -doing nasty things. Currently those limitations are: - - - The user can only mount on a mountpoint, for which it has write - permission - - - The mountpoint is not a sticky directory which isn't owned by the - user (like /tmp usually is) - - - No other user (including root) can access the contents of the mounted - filesystem. - -Configuration -============= - -Some options regarding mount policy can be set in the file -'/etc/fuse.conf' - -Currently these options are: - -mount_max = NNN - - Set the maximum number of FUSE mounts allowed to non-root users. - The default is 1000. - -user_allow_other - - Allow non-root users to specify the 'allow_other' or 'allow_root' - mount options. - - -Mount options -============= - -Most of the generic mount options described in 'man mount' are -supported (ro, rw, suid, nosuid, dev, nodev, exec, noexec, atime, -noatime, sync async, dirsync). Filesystems are mounted with -'-onodev,nosuid' by default, which can only be overridden by a -privileged user. - -These are FUSE specific mount options that can be specified for all -filesystems: - -default_permissions - - By default FUSE doesn't check file access permissions, the - filesystem is free to implement it's 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. This is option 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. So all users (including root) - can access the files. This option is by default only allowed to - root, but this restriction can be removed with a configuration - option described in the previous section. - -allow_root - - This option is similar to 'allow_other' but file access is limited - to the user mounting the filesystem and root. This option and - 'allow_other' are mutually exclusive. - -kernel_cache - - This option disables flushing the cache of the file contents on - every open(). This should only be enabled on filesystems, where the - file data is never changed externally (not through the mounted FUSE - filesystem). Thus it is not suitable for network filesystems and - other "intermediate" filesystems. - - NOTE: if this option is not specified (and neither 'direct_io') data - is still cached after the open(), so a read() system call will not - always initiate a read operation. - -auto_cache - - This option enables automatic flushing of the data cache on open(). - The cache will only be flushed if the modification time or the size - of the file has changed. - -large_read - - Issue large read requests. This can improve performance for some - filesystems, but can also degrade performance. This option is only - useful on 2.4.X kernels, as on 2.6 kernels requests size is - automatically determined for optimum performance. - -direct_io - - This option disables the use of page cache (file content cache) in - the kernel for this filesystem. This has several affects: - - - Each read() or write() system call will initiate one or more - read or write operations, data will not be cached in the - kernel. - - - The return value of the read() and write() system calls will - correspond to the return values of the read and write - operations. This is useful for example if the file size is not - known in advance (before reading it). - -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). - -max_readahead=N - - Set the maximum number of bytes to read-ahead. The default is - determined by the kernel. On linux-2.6.22 or earlier it's 131072 - (128kbytes) - -max_write=N - - Set the maximum number of bytes in a single write operation. The - default is 128kbytes. Note, that due to various limitations, the - size of write requests can be much smaller (4kbytes). This - limitation will be removed in the future. - -async_read - - Perform reads asynchronously. This is the default - -sync_read - - Perform all reads (even read-ahead) synchronously. - -hard_remove - - The default behavior is that if an open file is deleted, the file is - renamed to a hidden file (.fuse_hiddenXXX), and only removed when - the file is finally released. This relieves the filesystem - implementation of having to deal with this problem. This option - disables the hiding behavior, and files are removed immediately in - an unlink operation (or in a rename operation which overwrites an - existing file). - - It is recommended that you not use the hard_remove option. When - hard_remove is set, the following libc functions fail on unlinked - files (returning errno of ENOENT): - - read() - - write() - - fsync() - - close() - - f*xattr() - - ftruncate() - - fstat() - - fchmod() - - fchown() - -debug - - Turns on debug information printing by the library. - -fsname=NAME - - Sets the filesystem source (first field in /etc/mtab). The default - is the program name. - -subtype=TYPE - - Sets the filesystem type (third field in /etc/mtab). The default is - the program name. - - If the kernel suppports it, /etc/mtab and /proc/mounts will show the - filesystem type as "fuse.TYPE" - - If the kernel doesn't support subtypes, the source filed will be - "TYPE#NAME", or if fsname option is not specified, just "TYPE". - -use_ino - - Honor the 'st_ino' field in getattr() and fill_dir(). This value is - used to fill in the 'st_ino' field in the stat()/lstat()/fstat() - functions and the 'd_ino' field in the readdir() function. The - filesystem does not have to guarantee uniqueness, however some - applications rely on this value being unique for the whole - filesystem. - -readdir_ino - - If 'use_ino' option is not given, still try to fill in the 'd_ino' - field in readdir(). If the name was previously looked up, and is - still in the cache, the inode number found there will be used. - Otherwise it will be set to '-1'. If 'use_ino' option is given, - this option is ignored. - -nonempty - - Allows mounts over a non-empty file or directory. By default these - mounts are rejected (from version 2.3.1) to prevent accidental - covering up of data, which could for example prevent automatic - backup. - -umask=M - - Override the permission bits in 'st_mode' set by the filesystem. - The resulting permission bits are the ones missing from the given - umask value. The value is given in octal representation. - -uid=N - - Override the 'st_uid' field set by the filesystem. - -gid=N - - Override the 'st_gid' field set by the filesystem. - -blkdev - - Mount a filesystem backed by a block device. This is a privileged - option. The device must be specified with the 'fsname=NAME' option. - -entry_timeout=T - - The timeout in seconds for which name lookups will be cached. The - default is 1.0 second. For all the timeout options, it is possible - to give fractions of a second as well (e.g. "-oentry_timeout=2.8") - -negative_timeout=T - - The timeout in seconds for which a negative lookup will be cached. - This means, that if file did not exist (lookup retuned ENOENT), the - lookup will only be redone after the timeout, and the file/directory - will be assumed to not exist until then. The default is 0.0 second, - meaning that caching negative lookups are disabled. - -attr_timeout=T - - The timeout in seconds for which file/directory attributes are - cached. The default is 1.0 second. - -ac_attr_timeout=T - - The timeout in seconds for which file attributes are cached for the - purpose of checking if "auto_cache" should flush the file data on - open. The default is the value of 'attr_timeout' - -intr - - Allow requests to be interrupted. Turning on this option may result - in unexpected behavior, if the filesystem does not support request - interruption. - -intr_signal=NUM - - Specify which signal number to send to the filesystem when a request - is interrupted. The default is 10 (USR1). - -modules=M1[:M2...] - - Add modules to the filesystem stack. Modules are pushed in the - order they are specified, with the original filesystem being on the - bottom of the stack. - - -Modules distributed with fuse ------------------------------ - -iconv -````` -Perform file name character set conversion. Options are: - -from_code=CHARSET - - Character set to convert from (see iconv -l for a list of possible - values). Default is UTF-8. - -to_code=CHARSET - - Character set to convert to. Default is determined by the current - locale. - - -subdir -`````` -Prepend a given directory to each path. Options are: - -subdir=DIR - - Directory to prepend to all paths. This option is mandatory. - -rellinks - - Transform absolute symlinks into relative - -norellinks - - Do not transform absolute symlinks into relative. This is the default. - - -Reporting bugs -============== - -Please send bug reports to the -mailing list. - -The list is open, you need not be subscribed to post. +This file just exists to make automake happy. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ef3b5a9 --- /dev/null +++ b/README.md @@ -0,0 +1,98 @@ +libfuse +======= + +About +----- + +FUSE (Filesystem in Userspace) is an interface for userspace programs +to export a filesystem to the Linux kernel. The FUSE project consists +of two components: the *fuse* kernel module (maintained in the regular +kernel repositories) and the *libfuse* userspace library (maintained +in this repository). libfuse provides the reference implementation +for communicating with the FUSE kernel module. + +A FUSE file system is typically implemented as a standalone +application that links with libfuse. libfuse provides functions to +mount the file system, unmount it, read requests from the kernel, and +send 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 using +callbacks. When using the high-level API, the callbacks may work with +file names and paths instead of inodes, and processing of a request +finishes when the callback function returns. When using the low-level +API, the callbacks must work with inodes and responses must be sent +explicitly using a separate set of API functions. + + +Installation +------------ + + ./configure + make -j8 + make install + +You may also need to add `/usr/local/lib` to `/etc/ld.so.conf` and/or +run *ldconfig*. If you're building from the git repository (instead of +using a release tarball), you also need to run `./makeconf.sh` to +create the `configure` script. + +You'll also need a fuse kernel module (Linux kernels 2.6.14 or later +contain FUSE support). + +For more details see the file `INSTALL` + +Security implications +--------------------- + +If you run `make install`, the *fusermount* program is installed +set-user-id to root. This is done to allow normal users to mount +their own filesystem implementations. + +There must however be some limitations, in order to prevent Bad User from +doing nasty things. Currently those limitations are: + + - The user can only mount on a mountpoint, for which it has write + permission + + - The mountpoint is not a sticky directory which isn't owned by the + user (like /tmp usually is) + + - No other user (including root) can access the contents of the mounted + filesystem (though this can be relaxed) + + +Building your own filesystem +------------------------------ + +FUSE comes with several example file systems in the `examples` +directory. For example, the *fusexmp* example mirrors the contents of +the root directory under the mountpoint. Start from there and adapt +the code! + +The documentation of the API functions and necessary callbacks is +mostly contained in the files `include/fuse.h` (for the high-level +API) and `include/fuse_lowlevel.h` (for the low-level API). + + +Getting Help +------------ + +If you need help, please ask on the +mailing list (subscribe at +https://lists.sourceforge.net/lists/listinfo/fuse-devel). + +Please report any bugs on the GitHub issue tracker at +https://github.com/libfuse/main/issues. + + +Credits +------- + +libfuse is currently maintained by Nikolaus Rath. + +The CUSE feature was added by Tejun Heo. + +FUSE (both libfuse and the kernel module) was written by Miklos +Szeredi. + +