sbin/mount_fusefs/mount_fusefs.8

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