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.\" 3. 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 November 17, 2018 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. 56In practice, the daemon is assigned a 57.Ar special 58file automatically, which can then be indentified via 59.Xr fstat 1 . 60That special file can then be mounted by 61.Nm . 62.Pp 63However, the procedure of spawning a daemon will usually be automated 64so that it is performed by 65.Nm . 66If the command invoking a given 67.Ar fuse_daemon 68is appended to the list of arguments, 69.Nm 70will call the 71.Ar fuse_daemon 72via that command. 73In that way the 74.Ar fuse_daemon 75will be instructed to attach itself to 76.Ar special . 77From that on mounting goes as in the simple case. (See 78.Sx DAEMON MOUNTS . ) 79.Pp 80The 81.Ar special 82argument will normally be treated as the path of the special file to mount. 83.Pp 84However, if 85.Pa auto 86is passed as 87.Ar special , 88then 89.Nm 90will look for a suitable free fuse device by itself. 91.Pp 92Finally, if 93.Ar special 94is an integer it will be interpreted as the number 95of the file descriptor of an already open fuse device 96(used when the Fuse library invokes 97.Nm . 98(See 99.Sx DAEMON MOUNTS ) . 100.Pp 101The options are as follows: 102.Bl -tag -width indent 103.It Fl A , Ic --reject-allow_other 104Prohibit the 105.Cm allow_other 106mount flag. 107Intended for use in scripts and the 108.Xr sudoers 5 109file. 110.It Fl S , Ic --safe 111Run in safe mode (i.e. reject invoking a filesystem daemon) 112.It Fl v 113Be verbose 114.It Fl D, Ic --daemon Ar daemon 115Call the specified 116.Ar daemon 117.It Fl O, Ic --daemon_opts Ar opts 118Add 119.Ar opts 120to the daemon's command line 121.It Fl s, Ic --special Ar special 122Use 123.Ar special 124as special 125.It Fl m, Ic --mountpath Ar node 126Mount on 127.Ar node 128.It Fl h, Ic --help 129Show help 130.It Fl V, Ic --version 131Show version information 132.It Fl o 133Mount options are specified via 134.Fl o . 135The following options are available (and also their negated versions, 136by prefixing them with 137.Dq no ) : 138.Bl -tag -width indent 139.It Cm default_permissions 140Enable traditional (file mode based) permission checking in kernel 141.It Cm allow_other 142Do not apply 143.Sx STRICT ACCESS POLICY . 144Only root can use this option 145.It Cm max_read Ns = Ns Ar n 146Limit size of read requests to 147.Ar n 148.It Cm private 149Refuse shared mounting of the daemon. 150This is the default behaviour, to allow sharing, expicitly use 151.Fl o Cm noprivate 152.It Cm neglect_shares 153Do not refuse unmounting if there are secondary mounts 154.It Cm push_symlinks_in 155Prefix absolute symlinks with the mountpoint 156.El 157.El 158.Pp 159Besides the above mount options, there is a set of pseudo-mount options which 160are supported by the Fuse library. 161One can list these by passing 162.Fl h 163to a Fuse daemon. 164Most of these options only have affect on the behavior of the daemon (that is, 165their scope is limited to userspace). 166However, there are some which do require in-kernel support. 167Currently the options supported by the kernel are: 168.Bl -tag -width indent 169.It Cm direct_io 170Bypass the buffer cache system 171.It Cm kernel_cache 172By default cached buffers of a given file are flushed at each 173.Xr open 2 . 174This option disables this behaviour 175.El 176.Sh DAEMON MOUNTS 177Usually users do not need to use 178.Nm 179directly, as the Fuse library enables Fuse daemons to invoke 180.Nm . 181That is, 182.Pp 183.Dl fuse_daemon device mountpoint 184.Pp 185has the same effect as 186.Pp 187.Dl mount_fusefs auto mountpoint fuse_daemon 188.Pp 189This is the recommended usage when you want basic usage 190(eg, run the daemon at a low privilege level but mount it as root). 191.Sh STRICT ACCESS POLICY 192The strict access policy for Fuse filesystems lets one to use the filesystem 193only if the filesystem daemon has the same credentials (uid, real uid, gid, 194real gid) as the user. 195.Pp 196This is applied for Fuse mounts by default and only root can mount without 197the strict access policy (i.e. the 198.Cm allow_other 199mount option). 200.Pp 201This is to shield users from the daemon 202.Dq spying 203on their I/O activities. 204.Pp 205Users might opt to willingly relax strict access policy (as far they 206are concerned) by doing their own secondary mount (See 207.Sx SHARED MOUNTS ) . 208.Sh SHARED MOUNTS 209A Fuse daemon can be shared (i.e. mounted multiple times). 210When doing the first (primary) mount, the spawner and the mounter of the daemon 211must have the same uid, or the mounter should be the superuser. 212.Pp 213After the primary mount is in place, secondary mounts can be done by anyone 214unless this feature is disabled by 215.Cm private . 216The behaviour of a secondary mount is analogous to that of symbolic 217links: they redirect all filesystem operations to the primary mount. 218.Pp 219Doing a secondary mount is like signing an agreement: by this action, the mounter 220agrees that the Fuse daemon can trace her I/O activities. 221From then on she is not banned from using the filesystem 222(either via her own mount or via the primary mount), regardless whether 223.Cm allow_other 224is used or not. 225.Pp 226The device name of a secondary mount is the device name of the corresponding 227primary mount, followed by a '#' character and the index of the secondary 228mount; e.g. 229.Pa /dev/fuse0#3 . 230.Sh SECURITY 231System administrators might want to use a custom mount policy (ie., one going 232beyond the 233.Va vfs.usermount 234sysctl). 235The primary tool for such purposes is 236.Xr sudo 8 . 237However, given that 238.Nm 239is capable of invoking an arbitrary program, one must be careful when doing this. 240.Nm 241is designed in a way such that it makes that easy. 242For this purpose, there are options which disable certain risky features (i.e. 243.Fl S 244and 245.Fl A ) , 246and command line parsing is done in a flexible way: mixing options and 247non-options is allowed, but processing them stops at the third non-option 248argument (after the first two has been utilized as device and mountpoint). 249The rest of the command line specifies the daemon and its arguments. 250(Alternatively, the daemon, the special and the mount path can be 251specified using the respective options.) Note that 252.Nm 253ignores the environment variable 254.Ev POSIXLY_CORRECT 255and always behaves as described. 256.Pp 257In general, to be as scripting / 258.Xr sudoers 5 259friendly as possible, no information has a fixed 260position in the command line, but once a given piece of information is 261provided, subsequent arguments/options cannot override it (with the 262exception of some non-critical ones). 263.Sh ENVIRONMENT 264.Bl -tag -width ".Ev MOUNT_FUSEFS_SAFE" 265.It Ev MOUNT_FUSEFS_SAFE 266This has the same effect as the 267.Fl S 268option. 269.It Ev MOUNT_FUSEFS_VERBOSE 270This has the same effect as the 271.Fl v 272option. 273.It Ev MOUNT_FUSEFS_IGNORE_UNKNOWN 274If set, 275.Nm 276will ignore uknown mount options. 277.It Ev MOUNT_FUSEFS_CALL_BY_LIB 278Adjust behavior to the needs of the FUSE library. 279Currently it effects help output. 280.El 281.Pp 282Although the following variables do not have any effect on 283.Nm 284itself, they affect the behaviour of fuse daemons: 285.Bl -tag -width ".Ev FUSE_DEV_NAME" 286.It Ev FUSE_DEV_NAME 287Device to attach. 288If not set, the multiplexer path 289.Ar /dev/fuse 290is used. 291.It Ev FUSE_DEV_FD 292File desciptor of an opened Fuse device to use. 293Overrides 294.Ev FUSE_DEV_NAME . 295.It Ev FUSE_NO_MOUNT 296If set, the library will not attempt to mount the filesystem, even 297if a mountpoint argument is supplied. 298.El 299.Sh FILES 300.Bl -tag -width /dev/fuse 301.It Pa /dev/fuse 302Fuse device with which the kernel and Fuse daemons can communicate. 303.It Pa /dev/fuse 304The multiplexer path. 305An 306.Xr open 2 307performed on it automatically is passed to a free Fuse device by the kernel 308(which might be created just for this puprose). 309.El 310.Sh EXAMPLES 311Mount the example filesystem in the Fuse distribution (from its directory): 312either 313.Pp 314.Dl ./fusexmp /mnt/fuse 315.Pp 316or 317.Pp 318.Dl mount_fusefs auto /mnt/fuse ./fusexmp 319.Pp 320Doing the same in two steps, using 321.Pa /dev/fuse0 : 322.Pp 323.Dl FUSE_DEV_NAME=/dev/fuse ./fusexmp && 324.Dl mount_fusefs /dev/fuse /mnt/fuse 325.Pp 326A script wrapper for fusexmp which ensures that 327.Nm 328does not call any external utility and also provides a hacky 329(non race-free) automatic device selection: 330.Pp 331.Dl #!/bin/sh -e 332.Pp 333.Dl FUSE_DEV_NAME=/dev/fuse fusexmp 334.Dl mount_fusefs -S /dev/fuse /mnt/fuse \(lq$@\(rq 335.Sh SEE ALSO 336.Xr fstat 1 , 337.Xr mount 8 , 338.Xr sudo 8 , 339.Xr umount 8 340.Sh HISTORY 341.Nm 342was written as the part of the 343.Fx 344implementation of the Fuse userspace filesystem framework (see 345.Xr https://github.com/libfuse/libfuse ) 346and first appeared in the 347.Pa sysutils/fusefs-kmod 348port, supporting 349.Fx 6.0 . 350It was added to the base system in 351.Fx 10.0 . 352.Sh CAVEATS 353This user interface is 354.Fx 355specific. 356Secondary mounts should be unmounted via their device name. 357If an attempt is made to unmount them via their filesystem root path, 358the unmount request will be forwarded to the primary mount path. 359In general, unmounting by device name is less error-prone than by mount path 360(although the latter will also work under normal circumstances). 361.Pp 362If the daemon is specified via the 363.Fl D 364and 365.Fl O 366options, it will be invoked via 367.Xr system 3 , 368and the daemon's command line will also have an 369.Dq & 370control operator appended, so that we do not have to wait for its termination. 371You should use a simple command line when invoking the daemon via these options. 372.Sh BUGS 373.Ar special 374is treated as a multiplexer if and only if it is literally the same as 375.Pa auto 376or 377.Pa /dev/fuse . 378Other paths which are equivalent with 379.Pa /dev/fuse 380(eg., 381.Pa /../dev/fuse ) 382are not. 383