share/man/man5/fusefs.5

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause
   3 .\"
   4 .\" Copyright (c) 2019 The FreeBSD Foundation
   5 .\"
   6 .\" This documentation was written by BFF Storage Systems, LLC under
   7 .\" sponsorship from the FreeBSD Foundation.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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 .Dd July 31, 2019
  30 .Dt FUSEFS 5
  31 .Os
  32 .Sh NAME
  33 .Nm fusefs
  34 .Nd "File system in USErspace"
  35 .Sh SYNOPSIS
  36 To link into the kernel:
  37 .Bd -ragged -offset indent
  38 .Cd "options FUSEFS"
  39 .Ed
  40 .Pp
  41 To load as a loadable kernel module:
  42 .Pp
  43 .Dl "kldload fusefs"
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 driver implements a file system that is serviced by a userspace program.
  48 .Pp
  49 There are many uses for
  50 .Nm .
  51 Userspace daemons can access libraries or programming languages that cannot run
  52 in kernel-mode, for example.
  53 .Nm
  54 is also useful for developing and debugging file systems, because a crash of
  55 the daemon will not take down the entire operating system.
  56 Finally, the
  57 .Nm
  58 API is portable.
  59 Many daemons can run on multiple operating systems with minimal modifications.
  60 .Sh SYSCTL VARIABLES
  61 The following
  62 .Xr sysctl 8
  63 variables are available:
  64 .Bl -tag -width indent
  65 .It Va vfs.fusefs.kernelabi_major
  66 Major version of the FUSE kernel ABI supported by this driver.
  67 .It Va vfs.fusefs.kernelabi_minor
  68 Minor version of the FUSE kernel ABI supported by this driver.
  69 .It Va vfs.fusefs.data_cache_mode
  70 Controls how
  71 .Nm
  72 will cache file data for pre-7.23 file systems.
  73 A value of 0 will disable caching entirely.
  74 Every data access will be forwarded to the daemon.
  75 A value of 1 will select write-through caching.
  76 Reads will be cached in the VFS layer as usual.
  77 Writes will be immediately forwarded to the daemon, and also added to the cache.
  78 A value of 2 will select write-back caching.
  79 Reads and writes will both be cached, and writes will occasionally be flushed
  80 to the daemon by the page daemon.
  81 Write-back caching is usually unsafe, especially for FUSE file systems that
  82 require network access.
  83 .Pp
  84 FUSE file systems using protocol 7.23 or later specify their cache behavior
  85 on a per-mountpoint basis, ignoring this sysctl.
  86 .It Va vfs.fusefs.stats.filehandle_count
  87 Current number of open FUSE file handles.
  88 .It Va vfs.fusefs.stats.lookup_cache_hits
  89 Total number of lookup cache hits.
  90 .It Va vfs.fusefs.stats.lookup_cache_misses
  91 Total number of lookup cache misses.
  92 .It Va vfs.fusefs.stats.node_count
  93 Current number of allocated FUSE vnodes.
  94 .It Va vfs.fusefs.stats.ticket_count
  95 Current number of allocated FUSE tickets, which is roughly equal to the number
  96 of FUSE operations currently being processed by daemons.
  97 .\" Undocumented sysctls
  98 .\" ====================
  99 .\" vfs.fusefs.enforce_dev_perms: I don't understand it well enough.
 100 .\" vfs.fusefs.iov_credit: I don't understand it well enough
 101 .\" vfs.fusefs.iov_permanent_bufsize: I don't understand it well enough
 102 .El
 103 .Sh SEE ALSO
 104 .Xr mount_fusefs 8
 105 .Sh HISTORY
 106 The
 107 .Nm fuse
 108 driver was written as the part of the
 109 .Fx
 110 implementation of the FUSE userspace file system framework (see
 111 .Lk https://github.com/libfuse/libfuse )
 112 and first appeared in the
 113 .Pa sysutils/fusefs-kmod
 114 port, supporting
 115 .Fx 6.0 .
 116 It was added to the base system in
 117 .Fx 10.0 ,
 118 and renamed to
 119 .Nm
 120 for
 121 .Fx 12.1 .
 122 .Sh AUTHORS
 123 .An -nosplit
 124 The
 125 .Nm fuse
 126 driver was originally written by
 127 .An Csaba Henk
 128 as a Google Summer of Code project in 2005.
 129 It was further developed by
 130 .An Ilya Putsikau
 131 during Google Summer of Code 2011, and that version was integrated into the
 132 base system by
 133 .An Attilio Rao Aq Mt attilio@FreeBSD.org .
 134 .Pp
 135 This manual page was written by
 136 .An Alan Somers Aq Mt asomers@FreeBSD.org .