README

General Information
===================

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/avf

or alternatively you can use CVS to get the very latest development
version by setting the cvsroot to

  :pserver:anonymous@cvs.avf.sourceforge.net:/cvsroot/avf

and checking out the 'fuse' module.

Installation
============

See the file 'INSTALL'

IMPORTANT NOTE: If you run a system with untrusted users, installing
this program is not recommended, as it could be used to breach
security (see the 'Security' section for explanation).

How To Use
==========

FUSE is made up of three main parts:

 - A kernel filesystem module (kernel/fuse.o)

 - A userspace library (lib/libfuse.a)

 - A mount/unmount program (util/fusermount)


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/whatever -d'

  4) ls -al /mnt/whatever

  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.

The fusermount program accepts a couple of additional options (see
'fusermount -h').  You can add these options after a '--' like this:

   example/fusexmp /mnt/whatever -d -- -l

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.

Currently the first two conditions are checked by the fusermount
program before doing the mount.  This is in fact not perfectly secure,
since there is a window of time, after fusermount has checked the
mountpoint and before the mount actually takes place, when the user is
able to change the mountpoint (e.g. by changing symbolic links). 

The preferred method would be if the kernel would check the
permissions.  There is a patch for this for the 2.6.X kernel (where X
>= 3) in the patch directory.  If you apply this patch then the suid
bit can be removed from the fusermount program.

Comments about this are appreciated.