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