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