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