glfs/postlfs/filesystems/fuse3.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY fuse3-download-http "https://github.com/libfuse/libfuse/releases/download/fuse-&fuse3-version;/fuse-&fuse3-version;.tar.gz">
  <!ENTITY fuse3-download-ftp  " ">
  <!ENTITY fuse3-md5sum        "30421493d598a283687e0e69d44758fe">
  <!ENTITY fuse3-size          "13 MB">
  <!ENTITY fuse3-buildsize     "232 MB (with tests and documentation)">
  <!ENTITY fuse3-time          "0.2 SBU (add 0.3 SBU for tests)">
]>

<sect1 id="fuse3" xreflabel="Fuse-&fuse3-version;">
  <?dbhtml filename="fuse.html"?>


  <title>Fuse-&fuse3-version;</title>

  <indexterm zone="fuse3">
    <primary sortas="a-fuse-3">Fuse 3</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Fuse</title>

    <para>
      <application>FUSE</application> (Filesystem in Userspace) is a simple
      interface for userspace programs to export a virtual filesystem to the
      Linux kernel. <application>Fuse</application> also aims to provide a
      secure method for non privileged users to create and mount their own
      filesystem implementations.
    </para>

    &lfs113_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&fuse3-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&fuse3-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &fuse3-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &fuse3-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &fuse3-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &fuse3-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Fuse Dependencies</bridgehead>
    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="doxygen"/> (to rebuild the API documentation),
      <xref linkend="pytest"/> (required for tests), and
      <ulink url="https://pypi.org/project/looseversion/">looseversion</ulink>
      (for tests)
    </para>

  </sect2>

  <sect2 role="kernel" id="fuse-kernel">
    <title>Kernel Configuration</title>

    <para>
      Enable the following options in the kernel configuration and recompile the
      kernel if necessary:
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="fuse-kernel.xml"/>

    <para>
      Character devices in userspace should be enabled too for running the
      tests:
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="fuse-test-kernel.xml"/>

    <indexterm zone="fuse3 fuse-kernel">
      <primary sortas="d-fuse3">Fuse 3</primary>
    </indexterm>
  </sect2>

  <sect2 role="installation">
    <title>Installation of Fuse</title>

    <para>
      Install <application>Fuse</application> by running the following
      commands:
    </para>

<screen><userinput>sed -i '/^udev/,$ s/^/#/' util/meson.build &amp;&amp;

mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup --prefix=/usr --buildtype=release .. &amp;&amp;
ninja</userinput></screen>

    <para>
      The API documentation is included in the package, but
      if you have <xref linkend="doxygen"/> installed and wish to rebuild
      it, issue:
    </para>

<screen remap="doc"><userinput>pushd .. &amp;&amp;
  doxygen doc/Doxyfile &amp;&amp;
popd</userinput></screen>

    <para>
      To test the results, issue the following commands (as the <systemitem
      role="username">root</systemitem> user):
    </para>

    <!-- EDITORS NOTE:

         Don't use 'pytest' instead of 'python3 -m pytest'.  There is no
         testenv/bin/pytest (as at pytest-7.4.0) so 'pytest' resolves to
         /usr/bin/pytest, and the shebang of it is /usr/bin/python3.11.
         So it won't find the looseversion installed in testenv.

         To view the results of the tests, look for
         "short test summary info" at the end of your log. Below skipped tests,
         you will see "X passed, X skipped, X failed (if any) in X seconds" -->

<screen role="root" remap="test"><userinput>python3 -m venv --system-site-packages testenv &amp;&amp;
source testenv/bin/activate                    &amp;&amp;
pip3 install looseversion                      &amp;&amp;
python3 -m pytest                              &amp;&amp;
deactivate</userinput></screen>

    <para>
      The <xref linkend="pytest"/> Python
      module is required for the tests. One test named
      <filename>test_cuse</filename> will fail if the
      <parameter>CONFIG_CUSE</parameter> configuration item was not enabled
      when the kernel was built. One test,
      <filename>test/util.py</filename>, will output a warning due to the usage
      of an unknown mark in pytest.
      <!-- I really don't know why.  But it always happen for me, maybe
           kernel configuration issue... -->
      One test named
      <filename>test_notify_inval_entry[True-expire_entries]</filename>
      may fail under certain circumstances.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>ninja install                  &amp;&amp;
chmod u+s /usr/bin/fusermount3 &amp;&amp;

cd ..                          &amp;&amp;
cp -Rv doc/html -T /usr/share/doc/fuse-&fuse3-version; &amp;&amp;
install -v -m644   doc/{README.NFS,kernel.txt} \
                   /usr/share/doc/fuse-&fuse3-version;</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>sed ... util/meson.build</command>: This command disables the
      installation of a boot script and udev rule that are not needed.
    </para>

<!--
    <para>
      <command>sed ... meson.build</command>: This command fixes a bug with the
      test_passthrough_hp test.
    </para>
-->

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/meson-buildtype-release.xml"/>

  </sect2>

  <sect2 role="configuration" id="fuse-configuration">
    <title>Configuring fuse</title>

    <sect3 id="fuse-config">
      <title>Config Files</title>

      <para>
        Some options regarding mount policy can be set in the file
        <filename>/etc/fuse.conf</filename>. To install the file run the
        following command as the <systemitem class="username">root</systemitem>
        user:
      </para>

<screen role="root"><userinput>cat &gt; /etc/fuse.conf &lt;&lt; "EOF"
<literal># Set the maximum number of FUSE mounts allowed to non-root users.
# The default is 1000.
#
#mount_max = 1000

# Allow non-root users to specify the 'allow_other' or 'allow_root'
# mount options.
#
#user_allow_other</literal>
EOF</userinput></screen>

      <para>
        Additional information about the meaning of the configuration
        options are found in the man page.
      </para>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directory</segtitle>

      <seglistitem>
        <seg>
          fusermount3 and mount.fuse3
        </seg>
        <seg>
          libfuse3.so
        </seg>
        <seg>
          /usr/include/fuse3 and /usr/share/doc/fuse-&fuse3-version;
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="fusermount3">
        <term><command>fusermount3</command></term>
        <listitem>
          <para>
            is a suid root program to mount and unmount Fuse filesystems
          </para>
          <indexterm zone="fuse3 fusermount3">
            <primary sortas="b-fusermount3">fusermount3</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="mount.fuse3">
        <term><command>mount.fuse3</command></term>
        <listitem>
          <para>
            is the command <command>mount</command> calls to mount a Fuse
            filesystem
          </para>
          <indexterm zone="fuse3 mount.fuse3">
            <primary sortas="b-mount.fuse3">mount.fuse3</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libfuse3">
        <term><filename class="libraryfile">libfuse3.so</filename></term>
        <listitem>
          <para>
            contains the <application>FUSE</application> API functions
          </para>
          <indexterm zone="fuse3 libfuse3">
            <primary sortas="c-libfuse3">libfuse3.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>