1General Information 2=================== 3 4FUSE (Filesystem in Userspace) is a simple interface for userspace 5programs to export a virtual filesystem to the Linux kernel. FUSE 6also aims to provide a secure method for non privileged users to 7create and mount their own filesystem implementations. 8 9You can download the source code releases from 10 11 http://sourceforge.net/projects/fuse 12 13or alternatively you can use CVS to get the very latest development 14version by setting the cvsroot to 15 16 :pserver:anonymous@cvs.sourceforge.net:/cvsroot/fuse 17 18and checking out the 'fuse' module. 19 20Dependencies 21============ 22 23Linux kernel version 2.4.X where X >= 21 (some vendor kernels earlier 24than this are also known to work). 25 26Linux kernel version 2.6.X where X >= 0. 27 28Installation 29============ 30 31./configure 32make 33make install 34modprobe fuse 35 36You may also need to add '/usr/local/lib' to '/etc/ld.so.conf' and/or 37run ldconfig. 38 39Linux kernels 2.6.14 or later contain FUSE support out of the box. If 40FUSE support is detected, the kernel module in this package will not 41be compiled. It is possible to override this with the 42'--enable-kernel-module' configure option. 43 44If './configure' cannot find the kernel source or it says the kernel 45source should be prepared, you may either try 46 47 ./configure --disable-kernel-module 48 49or if your kernel does not already contain FUSE support, do the 50following: 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 59For more details see the file 'INSTALL' 60 61How To Use 62========== 63 64FUSE is made up of three main parts: 65 66 - A kernel filesystem module 67 68 - A userspace library 69 70 - A mount/unmount program 71 72 73Here's how to create your very own virtual filesystem in five easy 74steps (after installing FUSE): 75 76 1) Edit the file example/fusexmp.c to do whatever you want... 77 78 2) Build the fusexmp program 79 80 3) run 'example/fusexmp /mnt/fuse -d' 81 82 4) ls -al /mnt/fuse 83 84 5) Be glad 85 86If it doesn't work out, please ask! Also see the file 'include/fuse.h' for 87detailed documentation of the library interface. 88 89Security 90======== 91 92If you run 'make install', the fusermount program is installed 93set-user-id to root. This is done to allow normal users to mount 94their own filesystem implementations. 95 96There must however be some limitations, in order to prevent Bad User from 97doing nasty things. Currently those limitations are: 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 105 - No other user (including root) can access the contents of the mounted 106 filesystem. 107 108Configuration 109============= 110 111Some options regarding mount policy can be set in the file 112'/etc/fuse.conf' 113 114Currently these options are: 115 116mount_max = NNN 117 118 Set the maximum number of FUSE mounts allowed to non-root users. 119 The default is 1000. 120 121user_allow_other 122 123 Allow non-root users to specify the 'allow_other' or 'allow_root' 124 mount options. 125 126 127Mount options 128============= 129 130These are FUSE specific mount options that can be specified for all 131filesystems: 132 133default_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 142allow_other 143 144 This option overrides the security measure restricting file access 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. 149 150allow_root 151 152 This option is similar to 'allow_other' but file access is limited 153 to the user mounting the filesystem and root. This option and 154 'allow_other' are mutually exclusive. 155 156kernel_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 168large_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 175direct_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 189max_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 195hard_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 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 218debug 219 220 Turns on debug information printing by the library. 221 222fsname=NAME 223 224 Sets the filesystem name. The default is the program name. 225 226use_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 235readdir_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 243nonempty 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. 249 250umask=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 256uid=N 257 258 Override the 'st_uid' field set by the filesystem. 259 260gid=N 261 262 Override the 'st_gid' field set by the filesystem. 263