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 July 31, 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 be delayed and/or reordered. 151.It Cm default_permissions 152Enable traditional (file mode based) permission checking in kernel. 153.It Cm intr 154Allow signals to interrupt operations that are blocked waiting for a reply from the server. 155When this option is in use, system calls may fail with 156.Er EINTR 157whenever a signal is received. 158.It Cm max_read Ns = Ns Ar n 159Limit size of read requests to 160.Ar n . 161.It Cm neglect_shares 162Do not refuse unmounting if there are secondary mounts. 163.It Cm private 164Refuse shared mounting of the daemon. 165This is the default behaviour, to allow sharing, expicitly use 166.Fl o Cm noprivate . 167.It Cm push_symlinks_in 168Prefix absolute symlinks with the mountpoint. 169.It Cm subtype Ns = Ns Ar fsname 170Suffix 171.Ar fsname 172to the file system name as reported by 173.Xr statfs 2 . 174This option can be used to identify the file system implemented by 175.Ar fuse_daemon . 176.El 177.El 178.Pp 179Besides the above mount options, there is a set of pseudo-mount options which 180are supported by the Fuse library. 181One can list these by passing 182.Fl h 183to a Fuse daemon. 184Most of these options only have affect on the behavior of the daemon (that is, 185their scope is limited to userspace). 186However, there are some which do require in-kernel support. 187Currently the options supported by the kernel are: 188.Bl -tag -width indent 189.It Cm direct_io 190Bypass the buffer cache system. 191.It Cm kernel_cache 192By default cached buffers of a given file are flushed at each 193.Xr open 2 . 194This option disables this behaviour. 195.El 196.Sh DAEMON MOUNTS 197Usually users do not need to use 198.Nm 199directly, as the Fuse library enables Fuse daemons to invoke 200.Nm . 201That is, 202.Pp 203.Dl fuse_daemon device mountpoint 204.Pp 205has the same effect as 206.Pp 207.Dl mount_fusefs auto mountpoint fuse_daemon 208.Pp 209This is the recommended usage when you want basic usage 210(eg, run the daemon at a low privilege level but mount it as root). 211.Sh STRICT ACCESS POLICY 212The strict access policy for Fuse filesystems lets one to use the filesystem 213only if the filesystem daemon has the same credentials (uid, real uid, gid, 214real gid) as the user. 215.Pp 216This is applied for Fuse mounts by default and only root can mount without 217the strict access policy (i.e., the 218.Cm allow_other 219mount option). 220.Pp 221This is to shield users from the daemon 222.Dq spying 223on their I/O activities. 224.Pp 225Users might opt to willingly relax strict access policy (as far they 226are concerned) by doing their own secondary mount (See 227.Sx SHARED MOUNTS ) . 228.Sh SHARED MOUNTS 229A Fuse daemon can be shared (i.e., mounted multiple times). 230When doing the first (primary) mount, the spawner and the mounter of the daemon 231must have the same uid, or the mounter should be the superuser. 232.Pp 233After the primary mount is in place, secondary mounts can be done by anyone 234unless this feature is disabled by 235.Cm private . 236The behaviour of a secondary mount is analogous to that of symbolic 237links: they redirect all filesystem operations to the primary mount. 238.Pp 239Doing a secondary mount is like signing an agreement: by this action, the mounter 240agrees that the Fuse daemon can trace her I/O activities. 241From then on she is not banned from using the filesystem 242(either via her own mount or via the primary mount), regardless whether 243.Cm allow_other 244is used or not. 245.Pp 246The device name of a secondary mount is the device name of the corresponding 247primary mount, followed by a '#' character and the index of the secondary 248mount; e.g., 249.Pa /dev/fuse0#3 . 250.Sh SECURITY 251System administrators might want to use a custom mount policy (ie., one going 252beyond the 253.Va vfs.usermount 254sysctl). 255The primary tool for such purposes is 256.Xr sudo 8 . 257However, given that 258.Nm 259is capable of invoking an arbitrary program, one must be careful when doing this. 260.Nm 261is designed in a way such that it makes that easy. 262For this purpose, there are options which disable certain risky features ( 263.Fl S 264and 265.Fl A ) , 266and command line parsing is done in a flexible way: mixing options and 267non-options is allowed, but processing them stops at the third non-option 268argument (after the first two has been utilized as device and mountpoint). 269The rest of the command line specifies the daemon and its arguments. 270(Alternatively, the daemon, the special and the mount path can be 271specified using the respective options.) Note that 272.Nm 273ignores the environment variable 274.Ev POSIXLY_CORRECT 275and always behaves as described. 276.Pp 277In general, to be as scripting / 278.Xr sudoers 5 279friendly as possible, no information has a fixed 280position in the command line, but once a given piece of information is 281provided, subsequent arguments/options cannot override it (with the 282exception of some non-critical ones). 283.Sh ENVIRONMENT 284.Bl -tag -width ".Ev MOUNT_FUSEFS_SAFE" 285.It Ev MOUNT_FUSEFS_SAFE 286This has the same effect as the 287.Fl S 288option. 289.It Ev MOUNT_FUSEFS_VERBOSE 290This has the same effect as the 291.Fl v 292option. 293.It Ev MOUNT_FUSEFS_IGNORE_UNKNOWN 294If set, 295.Nm 296will ignore uknown mount options. 297.It Ev MOUNT_FUSEFS_CALL_BY_LIB 298Adjust behavior to the needs of the FUSE library. 299Currently it effects help output. 300.El 301.Pp 302Although the following variables do not have any effect on 303.Nm 304itself, they affect the behaviour of fuse daemons: 305.Bl -tag -width ".Ev FUSE_DEV_NAME" 306.It Ev FUSE_DEV_NAME 307Device to attach. 308If not set, the multiplexer path 309.Ar /dev/fuse 310is used. 311.It Ev FUSE_DEV_FD 312File desciptor of an opened Fuse device to use. 313Overrides 314.Ev FUSE_DEV_NAME . 315.It Ev FUSE_NO_MOUNT 316If set, the library will not attempt to mount the filesystem, even 317if a mountpoint argument is supplied. 318.El 319.Sh FILES 320.Bl -tag -width /dev/fuse 321.It Pa /dev/fuse 322Fuse device with which the kernel and Fuse daemons can communicate. 323.It Pa /dev/fuse 324The multiplexer path. 325An 326.Xr open 2 327performed on it automatically is passed to a free Fuse device by the kernel 328(which might be created just for this puprose). 329.El 330.Sh EXAMPLES 331Mount the example filesystem in the Fuse distribution (from its directory): 332either 333.Pp 334.Dl ./fusexmp /mnt/fuse 335.Pp 336or 337.Pp 338.Dl mount_fusefs auto /mnt/fuse ./fusexmp 339.Pp 340Doing the same in two steps, using 341.Pa /dev/fuse0 : 342.Pp 343.Dl FUSE_DEV_NAME=/dev/fuse ./fusexmp && 344.Dl mount_fusefs /dev/fuse /mnt/fuse 345.Pp 346A script wrapper for fusexmp which ensures that 347.Nm 348does not call any external utility and also provides a hacky 349(non race-free) automatic device selection: 350.Pp 351.Dl #!/bin/sh -e 352.Pp 353.Dl FUSE_DEV_NAME=/dev/fuse fusexmp 354.Dl mount_fusefs -S /dev/fuse /mnt/fuse \(lq$@\(rq 355.Sh SEE ALSO 356.Xr fstat 1 , 357.Xr mount 8 , 358.Xr sudo 8 , 359.Xr umount 8 360.Sh HISTORY 361.Nm 362was written as the part of the 363.Fx 364implementation of the Fuse userspace filesystem framework (see 365.Lk https://github.com/libfuse/libfuse ) 366and first appeared in the 367.Pa sysutils/fusefs-kmod 368port, supporting 369.Fx 6.0 . 370It was added to the base system in 371.Fx 10.0 . 372.Sh CAVEATS 373This user interface is 374.Fx 375specific. 376Secondary mounts should be unmounted via their device name. 377If an attempt is made to unmount them via their filesystem root path, 378the unmount request will be forwarded to the primary mount path. 379In general, unmounting by device name is less error-prone than by mount path 380(although the latter will also work under normal circumstances). 381.Pp 382If the daemon is specified via the 383.Fl D 384and 385.Fl O 386options, it will be invoked via 387.Xr system 3 , 388and the daemon's command line will also have an 389.Dq & 390control operator appended, so that we do not have to wait for its termination. 391You should use a simple command line when invoking the daemon via these options. 392.Sh BUGS 393.Ar special 394is treated as a multiplexer if and only if it is literally the same as 395.Pa auto 396or 397.Pa /dev/fuse . 398Other paths which are equivalent with 399.Pa /dev/fuse 400(eg., 401.Pa /../dev/fuse ) 402are not. 403