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 You'll also need a fuse kernel module, Linux kernels 2.6.14 or later
  39 contain FUSE support.
  40
  41 For more details see the file 'INSTALL'
  42
  43 How To Use
  44 ==========
  45
  46 FUSE is made up of three main parts:
  47
  48  - A kernel filesystem module
  49
  50  - A userspace library
  51
  52  - A mount/unmount program
  53
  54
  55 Here's how to create your very own virtual filesystem in five easy
  56 steps (after installing FUSE):
  57
  58   1) Edit the file example/fusexmp.c to do whatever you want...
  59
  60   2) Build the fusexmp program
  61
  62   3) run 'example/fusexmp /mnt/fuse -d'
  63
  64   4) ls -al /mnt/fuse
  65
  66   5) Be glad
  67
  68 If it doesn't work out, please ask!  Also see the file 'include/fuse.h' for
  69 detailed documentation of the library interface.
  70
  71 Security
  72 ========
  73
  74 If you run 'make install', the fusermount program is installed
  75 set-user-id to root.  This is done to allow normal users to mount
  76 their own filesystem implementations.
  77
  78 There must however be some limitations, in order to prevent Bad User from
  79 doing nasty things.  Currently those limitations are:
  80
  81   - The user can only mount on a mountpoint, for which it has write
  82     permission
  83
  84   - The mountpoint is not a sticky directory which isn't owned by the
  85     user (like /tmp usually is)
  86
  87   - No other user (including root) can access the contents of the mounted
  88     filesystem.
  89
  90 Configuration
  91 =============
  92
  93 Some options regarding mount policy can be set in the file
  94 '/etc/fuse.conf'
  95
  96 Currently these options are:
  97
  98 mount_max = NNN
  99
 100   Set the maximum number of FUSE mounts allowed to non-root users.
 101   The default is 1000.
 102
 103 user_allow_other
 104
 105   Allow non-root users to specify the 'allow_other' or 'allow_root'
 106   mount options.
 107
 108
 109 Mount options
 110 =============
 111
 112 Most of the generic mount options described in 'man mount' are
 113 supported (ro, rw, suid, nosuid, dev, nodev, exec, noexec, atime,
 114 noatime, sync async, dirsync).  Filesystems are mounted with
 115 '-onodev,nosuid' by default, which can only be overridden by a
 116 privileged user.
 117
 118 These are FUSE specific mount options that can be specified for all
 119 filesystems:
 120
 121 default_permissions
 122
 123   By default FUSE doesn't check file access permissions, the
 124   filesystem is free to implement it's access policy or leave it to
 125   the underlying file access mechanism (e.g. in case of network
 126   filesystems).  This option enables permission checking, restricting
 127   access based on file mode.  This is option is usually useful
 128   together with the 'allow_other' mount option.
 129
 130 allow_other
 131
 132   This option overrides the security measure restricting file access
 133   to the user mounting the filesystem.  So all users (including root)
 134   can access the files.  This option is by default only allowed to
 135   root, but this restriction can be removed with a configuration
 136   option described in the previous section.
 137
 138 allow_root
 139
 140   This option is similar to 'allow_other' but file access is limited
 141   to the user mounting the filesystem and root.  This option and
 142   'allow_other' are mutually exclusive.
 143
 144 kernel_cache
 145
 146   This option disables flushing the cache of the file contents on
 147   every open().  This should only be enabled on filesystems, where the
 148   file data is never changed externally (not through the mounted FUSE
 149   filesystem).  Thus it is not suitable for network filesystems and
 150   other "intermediate" filesystems.
 151
 152   NOTE: if this option is not specified (and neither 'direct_io') data
 153   is still cached after the open(), so a read() system call will not
 154   always initiate a read operation.
 155
 156 auto_cache
 157
 158   This option enables automatic flushing of the data cache on open().
 159   The cache will only be flushed if the modification time or the size
 160   of the file has changed.
 161
 162 large_read
 163
 164   Issue large read requests.  This can improve performance for some
 165   filesystems, but can also degrade performance.  This option is only
 166   useful on 2.4.X kernels, as on 2.6 kernels requests size is
 167   automatically determined for optimum performance.
 168
 169 direct_io
 170
 171   This option disables the use of page cache (file content cache) in
 172   the kernel for this filesystem.  This has several affects:
 173
 174      - Each read() or write() system call will initiate one or more
 175        read or write operations, data will not be cached in the
 176        kernel.
 177
 178      - The return value of the read() and write() system calls will
 179        correspond to the return values of the read and write
 180        operations.  This is useful for example if the file size is not
 181        known in advance (before reading it).
 182
 183 max_read=N
 184
 185   With this option the maximum size of read operations can be set.
 186   The default is infinite.  Note that the size of read requests is
 187   limited anyway to 32 pages (which is 128kbyte on i386).
 188
 189 max_readahead=N
 190
 191   Set the maximum number of bytes to read-ahead.  The default is
 192   determined by the kernel.  On linux-2.6.22 or earlier it's 131072
 193   (128kbytes)
 194
 195 max_write=N
 196
 197   Set the maximum number of bytes in a single write operation.  The
 198   default is 128kbytes.  Note, that due to various limitations, the
 199   size of write requests can be much smaller (4kbytes).  This
 200   limitation will be removed in the future.
 201
 202 async_read
 203
 204   Perform reads asynchronously. This is the default
 205
 206 sync_read
 207
 208   Perform all reads (even read-ahead) synchronously.
 209
 210 hard_remove
 211
 212   The default behavior is that if an open file is deleted, the file is
 213   renamed to a hidden file (.fuse_hiddenXXX), and only removed when
 214   the file is finally released.  This relieves the filesystem
 215   implementation of having to deal with this problem.  This option
 216   disables the hiding behavior, and files are removed immediately in
 217   an unlink operation (or in a rename operation which overwrites an
 218   existing file).
 219
 220   It is recommended that you not use the hard_remove option. When
 221   hard_remove is set, the following libc functions fail on unlinked
 222   files (returning errno of ENOENT):
 223      - read()
 224      - write()
 225      - fsync()
 226      - close()
 227      - f*xattr()
 228      - ftruncate()
 229      - fstat()
 230      - fchmod()
 231      - fchown()
 232
 233 debug
 234
 235   Turns on debug information printing by the library.
 236
 237 fsname=NAME
 238
 239   Sets the filesystem source (first field in /etc/mtab).  The default
 240   is the program name.
 241
 242 subtype=TYPE
 243
 244   Sets the filesystem type (third field in /etc/mtab).  The default is
 245   the program name.
 246
 247   If the kernel suppports it, /etc/mtab and /proc/mounts will show the
 248   filesystem type as "fuse.TYPE"
 249
 250   If the kernel doesn't support subtypes, the source filed will be
 251   "TYPE#NAME", or if fsname option is not specified, just "TYPE".
 252
 253 use_ino
 254
 255   Honor the 'st_ino' field in getattr() and fill_dir().  This value is
 256   used to fill in the 'st_ino' field in the stat()/lstat()/fstat()
 257   functions and the 'd_ino' field in the readdir() function.  The
 258   filesystem does not have to guarantee uniqueness, however some
 259   applications rely on this value being unique for the whole
 260   filesystem.
 261
 262 readdir_ino
 263
 264   If 'use_ino' option is not given, still try to fill in the 'd_ino'
 265   field in readdir().  If the name was previously looked up, and is
 266   still in the cache, the inode number found there will be used.
 267   Otherwise it will be set to '-1'.  If 'use_ino' option is given,
 268   this option is ignored.
 269
 270 nonempty
 271
 272   Allows mounts over a non-empty file or directory.  By default these
 273   mounts are rejected (from version 2.3.1) to prevent accidental
 274   covering up of data, which could for example prevent automatic
 275   backup.
 276
 277 umask=M
 278
 279   Override the permission bits in 'st_mode' set by the filesystem.
 280   The resulting permission bits are the ones missing from the given
 281   umask value.  The value is given in octal representation.
 282
 283 uid=N
 284
 285   Override the 'st_uid' field set by the filesystem.
 286
 287 gid=N
 288
 289   Override the 'st_gid' field set by the filesystem.
 290
 291 blkdev
 292
 293   Mount a filesystem backed by a block device.  This is a privileged
 294   option.  The device must be specified with the 'fsname=NAME' option.
 295
 296 entry_timeout=T
 297
 298   The timeout in seconds for which name lookups will be cached. The
 299   default is 1.0 second.  For all the timeout options, it is possible
 300   to give fractions of a second as well (e.g. "-oentry_timeout=2.8")
 301
 302 negative_timeout=T
 303
 304   The timeout in seconds for which a negative lookup will be cached.
 305   This means, that if file did not exist (lookup retuned ENOENT), the
 306   lookup will only be redone after the timeout, and the file/directory
 307   will be assumed to not exist until then.  The default is 0.0 second,
 308   meaning that caching negative lookups are disabled.
 309
 310 attr_timeout=T
 311
 312   The timeout in seconds for which file/directory attributes are
 313   cached.  The default is 1.0 second.
 314
 315 ac_attr_timeout=T
 316
 317   The timeout in seconds for which file attributes are cached for the
 318   purpose of checking if "auto_cache" should flush the file data on
 319   open.   The default is the value of 'attr_timeout'
 320
 321 intr
 322
 323   Allow requests to be interrupted.  Turning on this option may result
 324   in unexpected behavior, if the filesystem does not support request
 325   interruption.
 326
 327 intr_signal=NUM
 328
 329   Specify which signal number to send to the filesystem when a request
 330   is interrupted.  The default is 10 (USR1).
 331
 332 modules=M1[:M2...]
 333
 334   Add modules to the filesystem stack.  Modules are pushed in the
 335   order they are specified, with the original filesystem being on the
 336   bottom of the stack.
 337
 338
 339 Modules distributed with fuse
 340 -----------------------------
 341
 342 iconv
 343 `````
 344 Perform file name character set conversion.  Options are:
 345
 346 from_code=CHARSET
 347
 348   Character set to convert from (see iconv -l for a list of possible
 349   values).  Default is UTF-8.
 350
 351 to_code=CHARSET
 352
 353   Character set to convert to.  Default is determined by the current
 354   locale.
 355
 356
 357 subdir
 358 ``````
 359 Prepend a given directory to each path. Options are:
 360
 361 subdir=DIR
 362
 363   Directory to prepend to all paths.  This option is mandatory.
 364
 365 rellinks
 366
 367   Transform absolute symlinks into relative
 368
 369 norellinks
 370
 371   Do not transform absolute symlinks into relative.  This is the default.
 372
 373
 374 Reporting bugs
 375 ==============
 376
 377 Please send bug reports to the <fuse-devel@lists.sourceforge.net>
 378 mailing list.
 379
 380 The list is open, you need not be subscribed to post.