share/man/man5/fusefs.5

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2019 The FreeBSD Foundation
   5 .\"
   6 .\" This software was developed by BFF Storage Systems, LLC under sponsorship
   7 .\" 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 .\"
  30 .\" $FreeBSD$
  31 .Dd April 13, 2019
  32 .Dt FUSEFS 5
  33 .Os
  34 .Sh NAME
  35 .Nm fusefs
  36 .Nd "File system in USErspace"
  37 .Sh SYNOPSIS
  38 To link into the kernel:
  39 .Bd -ragged -offset indent
  40 .Cd "options FUSEFS"
  41 .Ed
  42 .Pp
  43 To load as a loadable kernel module:
  44 .Pp
  45 .Dl "kldload fusefs"
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 driver implements a file system that is serviced by a userspace program.
  50 .Pp
  51 There are many uses for
  52 .Nm .
  53 Userspace daemons can access libraries or programming languages that cannot run
  54 in kernel-mode, for example.
  55 .Nm
  56 is also useful for developing and debugging file systems, because a crash of
  57 the daemon will not take down the entire operating system.
  58 Finally, the
  59 .Nm
  60 API is portable.
  61 Many daemons can run on multiple operating systems with minimal modifications.
  62 .Sh SYSCTL VARIABLES
  63 The following variables are available as both
  64 .Xr sysctl 8
  65 variables and
  66 .Xr loader 8
  67 tunables:
  68 .Bl -tag -width indent
  69 .It Va vfs.fusefs.kernelabi_major
  70 Major version of the FUSE kernel ABI supported by this driver.
  71 .It Va vfs.fusefs.kernelabi_minor
  72 Minor version of the FUSE kernel ABI supported by this driver.
  73 .It Va vfs.fusefs.data_cache_mode
  74 Controls how
  75 .Nm
  76 will cache file data.
  77 A value of 0 will disable caching entirely.
  78 Every data access will be forwarded to the daemon.
  79 A value of 1 will select write-through caching.
  80 Reads will be cached in the VFS layer as usual.
  81 Writes will be immediately forwarded to the daemon, and also added to the cache.
  82 A value of 2 will select write-back caching.
  83 Reads and writes will both be cached, and writes will occasionally be flushed
  84 to the daemon by the page daemon.
  85 Write-back caching is usually unsafe, especially for FUSE file systems that
  86 require network access.
  87 .It Va vfs.fusefs.lookup_cache_enable
  88 Controls whether
  89 .Nm
  90 will cache lookup responses from the file system.
  91 FUSE file systems indicate whether lookup responses should be cacheable, but
  92 it may be useful to globally disable caching them if a file system is
  93 misbehaving.
  94 .\" Undocumented sysctls
  95 .\" ====================
  96 .\" Counters: I intend to rename to vfs.fusefs.stats.* for clarity
  97 .\" vfs.fusefs.lookup_cache_{hits, misses}
  98 .\" vfs.fusefs.filehandle_count
  99 .\" vfs.fusefs.ticker_count
 100 .\" vfs.fusefs.node_count
 101 .\"
 102 .\" vfs.fusefs.version - useless since the driver moved in-tree
 103 .\" vfs.fusefs.reclaim_revoked: I don't understand it well-enough
 104 .\" vfs.fusefs.enforce_dev_perms: I don't understand it well enough.
 105 .\" vfs.fusefs.iov_credit: I don't understand it well enough
 106 .\" vfs.fusefs.iov_permanent_bufsize: I don't understand it well enough
 107 .\" vfs.fusefs.fix_broken_io: I don't understand it well enough
 108 .\" vfs.fusefs.refresh_size: probably useless?
 109 .\" vfs.fusefs.mmap_enable: why is this optional?
 110 .\" vfs.fusefs.data_cache_invalidate: what is this needed for?
 111 .Sh SEE ALSO
 112 .Xr mount_fusefs 8
 113 .Sh HISTORY
 114 The
 115 .Nm fuse
 116 driver was written as the part of the
 117 .Fx
 118 implementation of the FUSE userspace file system framework (see
 119 .Xr https://github.com/libfuse/libfuse )
 120 and first appeared in the
 121 .Pa sysutils/fusefs-kmod
 122 port, supporting
 123 .Fx 6.0 .
 124 It was added to the base system in
 125 .Fx 10.0 ,
 126 and renamed to
 127 .Nm
 128 for
 129 .Fx 12.1 .
 130 .Sh AUTHORS
 131 .An -nosplit
 132 The
 133 .Nm fuse
 134 driver was originally written by
 135 .An Csaba Henk
 136 as a Google Summer of Code project in 2005.
 137 It was further developed by
 138 .An Ilya Putsikau
 139 during Google Summer of Code 2011, and that version was integrated into the
 140 base system by
 141 .An Attilio Rao Aq Mt attilio@FreeBSD.org .
 142 .Pp
 143 This manual page was written by
 144 .An Alan Somers Aq Mt asomers@FreeBSD.org .