Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 1 | General Information |
| 2 | =================== |
| 3 | |
Miklos Szeredi | 539488e | 2005-02-02 10:17:38 +0000 | [diff] [blame] | 4 | FUSE (Filesystem in Userspace) is a simple interface for userspace |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 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 | |
Miklos Szeredi | a2c5e56 | 2004-10-19 22:01:21 +0000 | [diff] [blame] | 11 | http://sourceforge.net/projects/fuse |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 12 | |
| 13 | or alternatively you can use CVS to get the very latest development |
Miklos Szeredi | 0a7077f | 2001-11-11 18:20:17 +0000 | [diff] [blame] | 14 | version by setting the cvsroot to |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 15 | |
Miklos Szeredi | a2c5e56 | 2004-10-19 22:01:21 +0000 | [diff] [blame] | 16 | :pserver:anonymous@cvs.sourceforge.net:/cvsroot/fuse |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 17 | |
Miklos Szeredi | 0a7077f | 2001-11-11 18:20:17 +0000 | [diff] [blame] | 18 | and checking out the 'fuse' module. |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 19 | |
| 20 | Installation |
| 21 | ============ |
| 22 | |
Miklos Szeredi | 94ed76a | 2004-07-26 19:38:45 +0000 | [diff] [blame] | 23 | ./configure |
| 24 | make |
| 25 | make install |
Miklos Szeredi | 539488e | 2005-02-02 10:17:38 +0000 | [diff] [blame] | 26 | modprobe fuse |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 27 | |
Miklos Szeredi | b92d978 | 2005-02-07 16:10:49 +0000 | [diff] [blame] | 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' |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 32 | |
| 33 | How To Use |
| 34 | ========== |
| 35 | |
| 36 | FUSE is made up of three main parts: |
| 37 | |
Miklos Szeredi | 94ed76a | 2004-07-26 19:38:45 +0000 | [diff] [blame] | 38 | - A kernel filesystem module |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 39 | |
Miklos Szeredi | 94ed76a | 2004-07-26 19:38:45 +0000 | [diff] [blame] | 40 | - A userspace library |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 41 | |
Miklos Szeredi | 94ed76a | 2004-07-26 19:38:45 +0000 | [diff] [blame] | 42 | - A mount/unmount program |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 43 | |
| 44 | |
| 45 | Here's how to create your very own virtual filesystem in five easy |
Miklos Szeredi | ddc862a | 2002-01-09 13:46:10 +0000 | [diff] [blame] | 46 | steps (after installing FUSE): |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 47 | |
| 48 | 1) Edit the file example/fusexmp.c to do whatever you want... |
| 49 | |
| 50 | 2) Build the fusexmp program |
| 51 | |
Miklos Szeredi | 94ed76a | 2004-07-26 19:38:45 +0000 | [diff] [blame] | 52 | 3) run 'example/fusexmp /mnt/fuse -d' |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 53 | |
Miklos Szeredi | 94ed76a | 2004-07-26 19:38:45 +0000 | [diff] [blame] | 54 | 4) ls -al /mnt/fuse |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 55 | |
Miklos Szeredi | 0a7077f | 2001-11-11 18:20:17 +0000 | [diff] [blame] | 56 | 5) Be glad |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 57 | |
Miklos Szeredi | 0a7077f | 2001-11-11 18:20:17 +0000 | [diff] [blame] | 58 | If it doesn't work out, please ask! Also see the file 'include/fuse.h' for |
| 59 | detailed documentation of the library interface. |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 60 | |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 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 |
Miklos Szeredi | e518374 | 2005-02-02 11:14:04 +0000 | [diff] [blame] | 66 | their own filesystem implementations. |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 67 | |
Miklos Szeredi | 0a7077f | 2001-11-11 18:20:17 +0000 | [diff] [blame] | 68 | There must however be some limitations, in order to prevent Bad User from |
| 69 | doing nasty things. Currently those limitations are: |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 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 | |
Miklos Szeredi | 0a7077f | 2001-11-11 18:20:17 +0000 | [diff] [blame] | 77 | - No other user (including root) can access the contents of the mounted |
Miklos Szeredi | 8cffdb9 | 2001-11-09 14:49:18 +0000 | [diff] [blame] | 78 | filesystem. |
Miklos Szeredi | 539488e | 2005-02-02 10:17:38 +0000 | [diff] [blame] | 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. This option is by default only |
| 118 | allowed to root, but this restriction can be removed with a |
| 119 | configuration option described in the previous section. |
| 120 | |
| 121 | allow_root |
| 122 | |
| 123 | This option is similar to 'allow_other' but file access is limited |
| 124 | to the user mounting the filesystem and root. |
| 125 | |
| 126 | kernel_cache |
| 127 | |
| 128 | This option disables flushing the cache of the file contents on |
| 129 | every open(). This should only be enabled on filesystems, where the |
| 130 | file data is never changed externally (not through the mounted FUSE |
| 131 | filesystem). Thus it is not suitable for network filesystems and |
| 132 | other "intermediate" filesystems. |
| 133 | |
| 134 | NOTE: if this option is not specified (and neither 'direct_io') data |
| 135 | is still cached after the open(), so a read() system call will not |
| 136 | always initiate a read operation. |
| 137 | |
| 138 | large_read |
| 139 | |
| 140 | Issue large read requests. This can improve performance for some |
| 141 | filesystems, but can also degrade performance. This option is only |
| 142 | useful on 2.4.X kernels, as on 2.6 kernels requests size is |
| 143 | automatically determined for optimum performance. |
| 144 | |
| 145 | direct_io |
| 146 | |
| 147 | This option disables the use of page cache (file content cache) in |
| 148 | the kernel for this filesystem. This has several affects: |
| 149 | |
| 150 | - Each read() or write() system call will initiate one or more |
| 151 | read or write operations, data will not be cached in the |
| 152 | kernel. |
| 153 | |
| 154 | - The return value of the read() and write() system calls will |
| 155 | correspond to the return values of the read and write |
| 156 | operations. This is useful for example if the file size is not |
| 157 | known in advance (before reading it). |
| 158 | |
| 159 | max_read=N |
| 160 | |
| 161 | With this option the maximum size of read operations can be set. |
| 162 | The default is infinite. Note that the size of read requests is |
| 163 | limited anyway to 32 pages (which is 128kbyte on i386). |
| 164 | |
| 165 | hard_remove |
| 166 | |
| 167 | The default behavior is that if an open file is deleted, the file is |
| 168 | renamed to a hidden file (.fuse_hiddenXXX), and only removed when |
| 169 | the file is finally released. This relieves the filesystem |
| 170 | implementation of having to deal with this problem. This option |
| 171 | disables the hiding behavior, and files are removed immediately in |
| 172 | an unlink operation (or in a rename operation which overwrites an |
| 173 | existing file). |
| 174 | |
Miklos Szeredi | a4f72cf | 2005-06-07 05:12:45 +0000 | [diff] [blame] | 175 | It is recommended that you not use the hard_remove option. When |
| 176 | hard_remove is set, the following libc functions fail on unlinked |
| 177 | files (returning errno of ENOENT): |
| 178 | - read() |
| 179 | - write() |
| 180 | - fsync() |
| 181 | - close() |
| 182 | - f*xattr() |
| 183 | - ftruncate() |
| 184 | - fstat() |
| 185 | - fchmod() |
| 186 | - fchown() |
| 187 | |
Miklos Szeredi | 539488e | 2005-02-02 10:17:38 +0000 | [diff] [blame] | 188 | debug |
| 189 | |
| 190 | Turns on debug information printing by the library. |
| 191 | |
| 192 | fsname=NAME |
| 193 | |
| 194 | Sets the filesystem name. The default is the program name. |
Miklos Szeredi | e518374 | 2005-02-02 11:14:04 +0000 | [diff] [blame] | 195 | |
Miklos Szeredi | 437d811 | 2005-07-06 09:14:20 +0000 | [diff] [blame^] | 196 | nonempty |
| 197 | |
| 198 | Allows mounts over a non-empty file or directory. By default these |
| 199 | mounts are rejected (from version 2.3.1) to prevent accidental |
| 200 | covering up of data, which could for example prevent automatic |
| 201 | backup. |