[BACK]Return to index.xml CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / htdocs / docs / puffs

File: [cvs.NetBSD.org] / htdocs / docs / puffs / index.xml (download)

Revision 1.16, Tue Apr 6 17:44:41 2021 UTC (7 months, 3 weeks ago) by nia
Branch: MAIN
CVS Tags: HEAD
Changes since 1.15: +7 -7 lines

Update for pkgsrc README.hmtl -> index.html transition

<?xml version="1.0"?>
<!DOCTYPE webpage
  PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
    "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">

<webpage id="docs-puffs-index">
<config param="desc" value="Filesystems in userspace: puffs, refuse, FUSE, and more"/>
<config param="cvstag" value="$NetBSD: index.xml,v 1.16 2021/04/06 17:44:41 nia Exp $"/>
<config param="rcsdate" value="$Date: 2021/04/06 17:44:41 $"/>
<head>
<!-- Copyright (c) 2005-2007
	The NetBSD Foundation, Inc.  ALL RIGHTS RESERVED. -->
<title>Filesystems in userspace: puffs, refuse, FUSE, and more</title>
</head>

<sect1 id="top">
</sect1>

<sect1 role="toc">

<sect2 id="puffs">
  <sect3 id="about">
    <title>About</title>
  
    <para>
      NetBSD now offers full support for running file systems in
      userspace. Major components are "puffs", which is the kernel
      subsystem that realizes the  pass-to-userspace framework file
      system, as well as the userland libraries that support
      constructing file system implementations.  These are libpuffs
      and the FUSE compatibility library, librefuse.
    </para>

    <para>
      This page describes the situation in NetBSD 5.0 and later.
    </para>
  </sect3>

  <sect3 id="components">
    <title>Components</title>

    <para>
      There are a number of components interacting to provide routines
      for userland file systems: puffs as the kernel part, and
      libpuffs and librefuse to provide functions for userland file
      systems to call. The following image gives an overview of the
      components and their connections:
    </para>

    <figure id="puffs-overview">
      <title>Overview about puffs</title>
      <mediaobject>
        <imageobject>
	  <imagedata fileref="puffs.png" format="PNG" />
	</imageobject>
      </mediaobject>
    </figure>

    <para>
      The components themselves are:
    </para>

    <itemizedlist>
      <listitem>
        <para>
          <emphasis role="bold">puffs</emphasis> is the core component
          inside the kernel. It exposes a file 
          system interface towards the userland programs (accessible via
          <filename>/dev/puffs</filename> and libpuffs), and
          communicates with the kernel's own idea of files,  
          which are represented as vnodes. 
          The puffs kernel component and how to interface it is described
          further in the &man.puffs.4; manpage. 
        </para>
      </listitem>
  
      <listitem>
        <para>
          The "<emphasis role="bold">libpuffs</emphasis>" library is the
          interface between userland 
          file systems and the kernel component. It provides a number of
          convenience routines that userland file systems can use, and is
          described in the &man.puffs.3; manpage. 
        </para>
      </listitem>
  
      <listitem>
        <para>
          To facilitate running the huge amount of file systems already
          available for the FUSE interface, but not dictate the
          capabilities of puffs by it, it was decided that FUSE support
          should be provided as a compatibility layer on top of the native
          puffs interface, which is offered by "<emphasis
          role="bold">librefuse</emphasis>".  The re-implementation of the
          FUSE functionality is designed to be source code compatible with
          FUSE, and it is further described in the &man.refuse.3; manpage.
        </para>
      </listitem>
    </itemizedlist>
  
    <para>
      Examples for puffs and refuse filesystems can be found in the
      following directory of the NetBSD source tree in
      <filename>src/share/examples/{puffs,refuse}</filename>.
    </para>
  </sect3>

  <sect3 id="enabling">
    <title>Enabling puffs</title>

      <para>
	puffs is enabled by default in GENERIC on major architectures
	starting from NetBSD 5.0.  For a custom kernel, the following
	are required in the kernel configuration.
    
      <screen>
file-system     PUFFS
pseudo-device   putter
      </screen>

      Alternatively, modules can be used.
    </para>
  </sect3>

  <sect3 id="examples">
    <title>Base system examples</title>
    
    <para>
      This section presents usage examples for file systems shipped with
      the NetBSD base system.
    </para>

    <sect4 id="example-psshfs">
      <title>psshfs, The NetBSD sshfs (&man.mount.psshfs.8;)</title>

      <screen>
# mount_psshfs host.name.tld:/directory /puffs
# ls /puffs
AdobeFnt.lst    OS                  bin     public_html
Desktop         OpenOffice.org1.1.0 in      tmp
...
# cd /puffs
# ls -l .cshrc
-rw-r--r--  1 39068  2000  4706 Jun 16 01:01 .cshrc
# head -2 .cshrc
# Default .cshrc for Solaris, Irix, ...
#
# md5 .cshrc
MD5 (.cshrc) = 2ad1d2606a5678f312709a388376c2e5
# ls -l test
ls: test: No such file or directory
# date >test
# ls -l test
-rw-r--r--  1 39068  2000  29 Nov 23 01:19 test
# cat test
Thu Nov 23 01:19:36 MET 2006
# umount /puffs
      </screen>
    </sect4>

    <sect4 id="example-9p">
      <title>
        <ulink url="http://www.cs.bell-labs.com/sys/man/5/INDEX.html">9P</ulink>
	file servers (&man.mount.9p.8;)
      </title>

      <screen>
# mount_9p nobody@192.168.1.2:/tmp /puffs
# cd /puffs
# echo 9puffs in action > msg_from_earth
# ls -l msg_from_earth
-rw-r--r--  1 nobody  wheel  17 Apr 25 23:24 msg_from_earth
# rsh 192.168.1.2 cat /tmp/msg_from_earth
9puffs in action
# 
</screen>
      <para>
	Since there is currently no support in the implementation for
	access control or support for authentication, the account
	nobody was picked just to prove a point.  The NFS nobody
	user really does not have anything to do with 9P.  Support
	for access control and use of pre-established secure
	connections will be added to <command>mount_9p</command>
	on a later date.
      </para>
    </sect4>

  </sect3>

  <sect3 id="pkgsrc">
    <title>pkgsrc &amp; FUSE</title>
    
    <para>
      FUSE compatibility was added within pkgsrc, and besides the
      required infrastructure work a number of FUSE packages were
      added to pkgsrc in the new "filesystem" category. Example
      packages that are currently available include:
    </para>

    <itemizedlist>
      <listitem>
        <ulink url="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse/">fuse</ulink>: Filesystem in Userspace (compat headers, pkg-config files,
         etc.), needed for pkgsrc on Linux 
      </listitem>
      <listitem>
        <ulink
      url="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-archivemount/">fuse-archivemount</ulink>:
        FUSE gateway to libarchive
      </listitem>
      <listitem>
        <ulink
      url="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-cddfs/">fuse-cddfs</ulink>:
        FUSE filesystem that uses libparanoia for audio CDs
      </listitem>
      <listitem>
        <ulink
        url="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-ntfs-3g/">fuse-ntfs-3g</ulink>:
        a NTFS driver with read and write support
      </listitem>
      <listitem>
	  ...
      </listitem>
    </itemizedlist>

    <para>
      More packages are currently being worked on, please see 
      <ulink
      url="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/">pkgsrc/filesystems</ulink>
      for a full list.
    </para>

    <para>
      Here is an example of installing and using the FUSE-enabled
      NTFS-3g implementation: 
    </para>

    <screen>
# cd pkgsrc/filesystems/fuse-ntfs-3g
# make install
# ntfs-3g ntfs.img /ntfs
    </screen>

    <para>
      Using FUSE file systems on NetBSD 4.0 is possible, but in
      addition to adding puffs support support to the kernel, it
      requires fetching and manually installing a backport of the
      ReFUSE library.  The library is available
      <ulink url="http://www.cs.hut.fi/~pooka/NetBSD/librefuse_nb4-20080115.tar.gz">here</ulink>
      and further instructions are available
      <ulink url="http://mail-index.NetBSD.org/netbsd-users/2008/01/15/msg000075.html">here</ulink>.
    </para>
  </sect3>

  <sect3 id="moreinfo">
    <title>Further Information</title>

    <para>An in-depth technical description of puffs was presented at
      <ulink url="http://www.asiabsdcon.org/">AsiaBSDCon</ulink> 2007
      in a paper entitled "puffs - Pass-to-Userspace Framework File System".
      The <ulink
      url="http://2007.asiabsdcon.org/papers/P04-paper.pdf">paper</ulink> and
      <ulink
      url="http://2007.asiabsdcon.org/papers/P04-slides.pdf">slides</ulink>
      are available.
    </para>

    <para>The ReFUSE emulation layer for FUSE file systems is described
      in "<ulink url="refuse.pdf">ReFUSE: Userspace FUSE
      Reimplementation Using puffs</ulink>" presented at EuroBSDCon 2007.
    </para>

    <para>A
      <ulink url="http://2008.asiabsdcon.org/papers/P4B-paper.pdf">paper</ulink>
      discussing the implementation of distributed file systems on top
      of puffs was presented at AsiaBSDCon 2008.
    </para>

    <para>The <ulink url="//man.NetBSD.org/puffs.3">puffs</ulink>
      manual pages provide further information from a development perspective.
    </para>

    <para>The source code in browsable form:
      <itemizedlist>
	<listitem><ulink url="http://cvsweb.NetBSD.org/bsdweb.cgi/src/sys/fs/puffs/">kernel code</ulink></listitem>
	<listitem><ulink url="http://cvsweb.NetBSD.org/bsdweb.cgi/src/lib/libpuffs/">libpuffs</ulink></listitem>
	<listitem><ulink url="http://cvsweb.NetBSD.org/bsdweb.cgi/src/lib/librefuse/">librefuse</ulink></listitem>
	<listitem><ulink url="http://cvsweb.NetBSD.org/bsdweb.cgi/src/usr.sbin/puffs/">puffs file systems in the base system</ulink></listitem>
	<listitem><ulink url="http://cvsweb.NetBSD.org/bsdweb.cgi/src/share/examples/puffs/">source code examples of other puffs file systems</ulink></listitem>
	<listitem><ulink url="http://cvsweb.NetBSD.org/bsdweb.cgi/src/share/examples/refuse/">source code examples for refuse</ulink></listitem>
      </itemizedlist>
    </para>

  </sect3>
  </sect2>
</sect1>

</webpage>