README

   1 General Information
   2 ===================
   3
   4 FUSE (Filesystem in Userspace) is a simple interface for userspace
   5 programs to export a virtual filesystem to the linux kernel.  FUSE
   6 also aims to provide a secure method for non privileged users to
   7 create and mount their own filesystem implementations.
   8
   9 You can download the source code releases from
  10
  11   http://sourceforge.net/projects/fuse
  12
  13 or alternatively you can use CVS to get the very latest development
  14 version by setting the cvsroot to
  15
  16   :pserver:anonymous@cvs.sourceforge.net:/cvsroot/fuse
  17
  18 and checking out the 'fuse' module.
  19
  20 Installation
  21 ============
  22
  23 ./configure
  24 make
  25 make install
  26 modprobe fuse
  27
  28 You may also need to add '/usr/local/lib' to '/etc/ld.so.conf' and/or
  29 run ldconfig.
  30
  31 For more details see the file 'INSTALL'
  32
  33 How To Use
  34 ==========
  35
  36 FUSE is made up of three main parts:
  37
  38  - A kernel filesystem module
  39
  40  - A userspace library
  41
  42  - A mount/unmount program
  43
  44
  45 Here's how to create your very own virtual filesystem in five easy
  46 steps (after installing FUSE):
  47
  48   1) Edit the file example/fusexmp.c to do whatever you want...
  49
  50   2) Build the fusexmp program
  51
  52   3) run 'example/fusexmp /mnt/fuse -d'
  53
  54   4) ls -al /mnt/fuse
  55
  56   5) Be glad
  57
  58 If it doesn't work out, please ask!  Also see the file 'include/fuse.h' for
  59 detailed documentation of the library interface.
  60
  61 Security
  62 ========
  63
  64 If you run 'make install', the fusermount program is installed
  65 set-user-id to root.  This is done to allow normal users to mount
  66 their own filesystem implementations.
  67
  68 There must however be some limitations, in order to prevent Bad User from
  69 doing nasty things.  Currently those limitations are:
  70
  71   - The user can only mount on a mountpoint, for which it has write
  72     permission
  73
  74   - The mountpoint is not a sticky directory which isn't owned by the
  75     user (like /tmp usually is)
  76
  77   - No other user (including root) can access the contents of the mounted
  78     filesystem.
  79
  80 Configuration
  81 =============
  82
  83 Some options regarding mount policy can be set in the file
  84 '/etc/fuse.conf'
  85
  86 Currently these options are:
  87
  88 mount_max = NNN
  89
  90   Set the maximum number of FUSE mounts allowed to non-root users.
  91   The default is 1000.
  92
  93 user_allow_other
  94
  95   Allow non-root users to specify the 'allow_other' or 'allow_root'
  96   mount options.
  97
  98
  99 Mount options
 100 =============
 101
 102 These are FUSE specific mount options that can be specified for all
 103 filesystems:
 104
 105 default_permissions
 106
 107   By default FUSE doesn't check file access permissions, the
 108   filesystem is free to implement it's access policy or leave it to
 109   the underlying file access mechanism (e.g. in case of network
 110   filesystems).  This option enables permission checking, restricting
 111   access based on file mode.  This is option is usually useful
 112   together with the 'allow_other' mount option.
 113
 114 allow_other
 115
 116   This option overrides the security measure restricting file access
 117   to the user mounting the filesystem.  So all users (including root)
 118   can access the files.  This option is by default only allowed to
 119   root, but this restriction can be removed with a configuration
 120   option described in the previous section.
 121
 122 allow_root
 123
 124   This option is similar to 'allow_other' but file access is limited
 125   to the user mounting the filesystem and root.  This option and
 126   'allow_other' are mutually exclusive.
 127
 128 kernel_cache
 129
 130   This option disables flushing the cache of the file contents on
 131   every open().  This should only be enabled on filesystems, where the
 132   file data is never changed externally (not through the mounted FUSE
 133   filesystem).  Thus it is not suitable for network filesystems and
 134   other "intermediate" filesystems.
 135
 136   NOTE: if this option is not specified (and neither 'direct_io') data
 137   is still cached after the open(), so a read() system call will not
 138   always initiate a read operation.
 139
 140 large_read
 141
 142   Issue large read requests.  This can improve performance for some
 143   filesystems, but can also degrade performance.  This option is only
 144   useful on 2.4.X kernels, as on 2.6 kernels requests size is
 145   automatically determined for optimum performance.
 146
 147 direct_io
 148
 149   This option disables the use of page cache (file content cache) in
 150   the kernel for this filesystem.  This has several affects:
 151
 152      - Each read() or write() system call will initiate one or more
 153        read or write operations, data will not be cached in the
 154        kernel.
 155
 156      - The return value of the read() and write() system calls will
 157        correspond to the return values of the read and write
 158        operations.  This is useful for example if the file size is not
 159        known in advance (before reading it).
 160
 161 max_read=N
 162
 163   With this option the maximum size of read operations can be set.
 164   The default is infinite.  Note that the size of read requests is
 165   limited anyway to 32 pages (which is 128kbyte on i386).
 166
 167 hard_remove
 168
 169   The default behavior is that if an open file is deleted, the file is
 170   renamed to a hidden file (.fuse_hiddenXXX), and only removed when
 171   the file is finally released.  This relieves the filesystem
 172   implementation of having to deal with this problem.  This option
 173   disables the hiding behavior, and files are removed immediately in
 174   an unlink operation (or in a rename operation which overwrites an
 175   existing file).
 176
 177   It is recommended that you not use the hard_remove option. When
 178   hard_remove is set, the following libc functions fail on unlinked
 179   files (returning errno of ENOENT):
 180      - read()
 181      - write()
 182      - fsync()
 183      - close()
 184      - f*xattr()
 185      - ftruncate()
 186      - fstat()
 187      - fchmod()
 188      - fchown()
 189
 190 debug
 191
 192   Turns on debug information printing by the library.
 193
 194 fsname=NAME
 195
 196   Sets the filesystem name.  The default is the program name.
 197
 198 use_ino
 199
 200   Honor the 'st_ino' field in getattr() and fill_dir().  This value is
 201   used to fill in the 'st_ino' field in the stat()/lstat()/fstat()
 202   functions and the 'd_ino' field in the readdir() function.  The
 203   filesystem does not have to guarantee uniqueness, however some
 204   applications rely on this value being unique for the whole
 205   filesystem.
 206
 207 readdir_ino
 208
 209   If 'use_ino' option is not given, still try to fill in the 'd_ino'
 210   field in readdir().  If the name was previously looked up, and is
 211   still in the cache, the inode number found there will be used.
 212   Otherwise it will be set to '-1'.  If 'use_ino' option is given,
 213   this option is ignored.
 214
 215 nonempty
 216
 217   Allows mounts over a non-empty file or directory.  By default these
 218   mounts are rejected (from version 2.3.1) to prevent accidental
 219   covering up of data, which could for example prevent automatic
 220   backup.
 221
 222 umask=M
 223
 224   Override the permission bits in 'st_mode' set by the filesystem.
 225   The resulting permission bits are the ones missing from the given
 226   umask value.  The value is given in octal representation.
 227
 228 uid=N
 229
 230   Override the 'st_uid' field set by the filesystem.
 231
 232 gid=N
 233
 234   Override the 'st_gid' field set by the filesystem.