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