1.\" Copyright (c) 1980, 1989, 1991, 1993 2.\" The Regents of the University of California. 3.\" Copyright (c) 2005, 2006 Csaba Henk 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 4. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd October 11, 2012 33.Dt MOUNT_FUSEFS 8 34.Os 35.Sh NAME 36.Nm mount_fusefs 37.Nd mount a Fuse file system daemon 38.Sh SYNOPSIS 39.Nm 40.Op Fl A 41.Op Fl S 42.Op Fl v 43.Op Fl D Ar fuse_daemon 44.Op Fl O Ar daemon_opts 45.Op Fl s Ar special 46.Op Fl m Ar node 47.Op Fl h 48.Op Fl V 49.Op Fl o Ar option ... 50.Ar special node 51.Op Ar fuse_daemon ... 52.Sh DESCRIPTION 53Basic usage is to start a fuse daemon on the given 54.Ar special 55file. In practice, the daemon is assigned a 56.Ar special 57file automatically, which can then be indentified via 58.Xr fstat 1 . 59That special file can then be mounted by 60.Nm . 61.Pp 62However, the procedure of spawning a daemon will usually be automated 63so that it is performed by 64.Nm . 65If the command invoking a given 66.Ar fuse_daemon 67is appended to the list of arguments, 68.Nm 69will call the 70.Ar fuse_daemon 71via that command. In that way the 72.Ar fuse_daemon 73will be instructed to attach itself to 74.Ar special . 75From that on mounting goes as in the simple case. (See 76.Sx DAEMON MOUNTS . ) 77.Pp 78The 79.Ar special 80argument will normally be treated as the path of the special file to mount. 81.Pp 82However, if 83.Pa auto 84is passed as 85.Ar special , 86then 87.Nm 88will look for a suitable free fuse device by itself. 89.Pp 90Finally, if 91.Ar special 92is an integer it will be interpreted as the number 93of the file descriptor of an already open fuse device 94(used when the Fuse library invokes 95.Nm . 96(See 97.Sx DAEMON MOUNTS ) . 98.Pp 99The options are as follows: 100.Bl -tag -width indent 101.It Fl A , Ic --reject-allow_other 102Prohibit the 103.Cm allow_other 104mount flag. Intended for use in scripts and the 105.Xr sudoers 5 106file. 107.It Fl S , Ic --safe 108Run in safe mode (i.e. reject invoking a filesystem daemon) 109.It Fl v 110Be verbose 111.It Fl D, Ic --daemon Ar daemon 112Call the specified 113.Ar daemon 114.It Fl O, Ic --daemon_opts Ar opts 115Add 116.Ar opts 117to the daemon's command line 118.It Fl s, Ic --special Ar special 119Use 120.Ar special 121as special 122.It Fl m, Ic --mountpath Ar node 123Mount on 124.Ar node 125.It Fl h, Ic --help 126Show help 127.It Fl V, Ic --version 128Show version information 129.It Fl o 130Mount options are specified via 131.Fl o . 132The following options are available (and also their negated versions, 133by prefixing them with 134.Dq no ) : 135.Bl -tag -width indent 136.It Cm default_permissions 137Enable traditional (file mode based) permission checking in kernel 138.It Cm allow_other 139Do not apply 140.Sx STRICT ACCESS POLICY . 141Only root can use this option 142.It Cm max_read Ns = Ns Ar n 143Limit size of read requests to 144.Ar n 145.It Cm private 146Refuse shared mounting of the daemon. This is the default behaviour, 147to allow sharing, expicitly use 148.Fl o Cm noprivate 149.It Cm neglect_shares 150Do not refuse unmounting if there are secondary mounts 151.It Cm push_symlinks_in 152Prefix absolute symlinks with the mountpoint 153.El 154.Pp 155.El 156.Pp 157Besides the above mount options, there is a set of pseudo-mount options which 158are supported by the Fuse library. One can list these by passing 159.Fl h 160to a Fuse daemon. Most of these options have effect only on the behaviour of 161the daemon (that is, their scope is limited to userspace). However, 162there are some which do require in-kernel support. 163Currently the options supported by the kernel are: 164.Bl -tag -width indent 165.It Cm direct_io 166Bypass the buffer cache system 167.It Cm kernel_cache 168By default cached buffers of a given file are flushed at each 169.Xr open 2 . 170This option disables this behaviour 171.El 172.Sh DAEMON MOUNTS 173Usually users do not need to use 174.Nm 175directly, as the Fuse library enables Fuse daemons to invoke 176.Nm . 177That is, 178.Pp 179.Dl fuse_daemon device mountpoint 180.Pp 181has the same effect as 182.Pp 183.Dl mount_fusefs auto mountpoint fuse_daemon 184.Pp 185This is the recommended usage when you want basic usage 186(eg, run the daemon at a low privilege level but mount it as root). 187.Sh STRICT ACCESS POLICY 188The strict access policy for Fuse filesystems lets one to use the filesystem 189only if the filesystem daemon has the same credentials (uid, real uid, gid, 190real gid) as the user. 191.Pp 192This is applied for Fuse mounts by default and only root can mount without 193the strict access policy (ie. the 194.Cm allow_other 195mount option). 196.Pp 197This is to shield users from the daemon 198.Dq spying 199on their I/O activities. 200.Pp 201Users might opt to willingly relax strict access policy (as far they 202are concerned) by doing their own secondary mount (See 203.Sx SHARED MOUNTS ) . 204.Sh SHARED MOUNTS 205A Fuse daemon can be shared (ie. mounted multiple times). 206When doing the first (primary) mount, the spawner and the mounter of the daemon 207must have the same uid, or the mounter should be the superuser. 208.Pp 209After the primary mount is in place, secondary mounts can be done by anyone 210unless this feature is disabled by 211.Cm private . 212The behaviour of a secondary mount is analogous to that of symbolic 213links: they redirect all filesystem operations to the primary mount. 214.Pp 215Doing a secondary mount is like signing an agreement: by this action, the mounter 216agrees that the Fuse daemon can trace her I/O activities. From then on 217she is not banned from using the filesystem (either via her own mount or 218via the primary mount), regardless whether 219.Cm allow_other 220is used or not. 221.Pp 222The device name of a secondary mount is the device name of the corresponding 223primary mount, followed by a '#' character and the index of the secondary 224mount; e.g. 225.Pa /dev/fuse0#3 . 226.Sh SECURITY 227System administrators might want to use a custom mount policy (ie., one going 228beyond the 229.Va vfs.usermount 230sysctl). The primary tool for such purposes is 231.Xr sudo 8 . 232However, given that 233.Nm 234is capable of invoking an arbitrary program, one must be careful when doing this. 235.Nm 236is designed in a way such that it makes that easy. For this purpose, 237there are options which disable certain risky features (ie. 238.Fl S 239and 240.Fl A ) , 241and command line parsing is done in a flexible way: mixing options and 242non-options is allowed, but processing them stops at the third non-option 243argument (after the first two has been utilized as device and mountpoint). 244The rest of the command line specifies the daemon and its arguments. 245(Alternatively, the daemon, the special and the mount path can be 246specified using the respective options.) Note that 247.Nm 248ignores the environment variable 249.Ev POSIXLY_CORRECT 250and always behaves as described. 251.Pp 252In general, to be as scripting / 253.Xr sudoers 5 254friendly as possible, no information has a fixed 255position in the command line, but once a given piece of information is 256provided, subsequent arguments/options cannot override it (with the 257exception of some non-critical ones). 258.Sh ENVIRONMENT 259.Bl -tag -width ".Ev MOUNT_FUSEFS_SAFE" 260.It Ev MOUNT_FUSEFS_SAFE 261This has the same effect as the 262.Fl S 263option. 264.It Ev MOUNT_FUSEFS_VERBOSE 265This has the same effect as the 266.Fl v 267option. 268.It Ev MOUNT_FUSEFS_IGNORE_UNKNOWN 269If set, 270.Nm 271will ignore uknown mount options. 272.It Ev MOUNT_FUSEFS_CALL_BY_LIB 273Adjust behaviour to the needs of the FUSE library. Currently it effects 274help output. 275.El 276.Pp 277Although the following variables do not have any effect on 278.Nm 279itself, they affect the behaviour of fuse daemons: 280.Bl -tag -width ".Ev FUSE_DEV_NAME" 281.It Ev FUSE_DEV_NAME 282Device to attach. If not set, the multiplexer path 283.Ar /dev/fuse 284is used. 285.It Ev FUSE_DEV_FD 286File desciptor of an opened Fuse device to use. Overrides 287.Ev FUSE_DEV_NAME . 288.It Ev FUSE_NO_MOUNT 289If set, the library will not attempt to mount the filesystem, even 290if a mountpoint argument is supplied. 291.El 292.Sh FILES 293.Bl -tag -width /dev/fuse 294.It Pa /dev/fuse 295Fuse device with which the kernel and Fuse daemons can communicate. 296.It Pa /dev/fuse 297The multiplexer path. An 298.Xr open 2 299performed on it automatically is passed to a free Fuse device by the kernel 300(which might be created just for this puprose). 301.El 302.Sh EXAMPLES 303Mount the example filesystem in the Fuse distribution (from its directory): 304either 305.Pp 306.Dl ./fusexmp /mnt/fuse 307.Pp 308or 309.Pp 310.Dl mount_fusefs auto /mnt/fuse ./fusexmp 311.Pp 312Doing the same in two steps, using 313.Pa /dev/fuse0 : 314.Pp 315.Dl FUSE_DEV_NAME=/dev/fuse ./fusexmp && 316.Dl mount_fusefs /dev/fuse /mnt/fuse 317.Pp 318A script wrapper for fusexmp which ensures that 319.Nm 320does not call any external utility and also provides a hacky 321(non race-free) automatic device selection: 322.Pp 323.Dl #!/bin/sh -e 324.Pp 325.Dl FUSE_DEV_NAME=/dev/fuse fusexmp 326.Dl mount_fusefs -S /dev/fuse /mnt/fuse \(lq$@\(rq 327.Sh SEE ALSO 328.Xr fstat 1 , 329.Xr mount 8 , 330.Xr umount 8 , 331.Xr sudo 8 332.Sh HISTORY 333.Nm 334appears as the part of the FreeBSD implementation of the Fuse userspace filesystem 335framework (see http://fuse.sourceforge.net). This user interface is FreeBSD specific. 336.Sh CAVEATS 337Secondary mounts should be unmounted via their device name. If an attempt is 338made to be unmount them via their filesystem root path, the unmount request 339will be forwarded to the primary mount path. 340In general, unmounting by device name is less error-prone than by mount path 341(although the latter will also work under normal circumstances). 342.Pp 343If the daemon is specified via the 344.Fl D 345and 346.Fl O 347options, it will be invoked via 348.Xr system 3 , 349and the daemon's command line will also have an 350.Dq & 351control operator appended, so that we do not have to wait for its termination. 352You should use a simple command line when invoking the daemon via these options. 353.Sh BUGS 354.Ar special 355is treated as a multiplexer if and only if it is literally the same as 356.Pa auto 357or 358.Pa /dev/fuse . 359Other paths which are equivalent with 360.Pa /dev/fuse 361(eg., 362.Pa /../dev/fuse ) 363are not. 364