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