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