<?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.8 2008/03/19 08:31:56 mishka Exp $"/>
<config param="rcsdate" value="$Date: 2008/03/19 08:31:56 $"/>
<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, libpuffs and the
FUSE-compatible librefuse.
</para>
<para>
puffs is available on NetBSD-current and will be part of the
NetBSD 5.0 release.
</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 in the base system</title>
<para>
While puffs is stable for users, the library programming
interface and the binary interfaces are still likely to change,
and therefore puffs and the dependant librefuse are not built by
default (as of 20070309). For people tracking NetBSD-current,
the following should be used to enable the build and use of puffs.
<screen>
/etc/mk.conf:
MKPUFFS=yes
kernel config:
file-system PUFFS
OR
/etc/lkm.conf:
# change BEFOREMOUNT to BEFORENET if /var or /usr is puffs
puffs.o -s - - - BEFOREMOUNT
</screen>
</para>
<para>
Also make sure that the device node <filename>/dev/puffs</filename>
exists by running <command>(cd /dev ; sh MAKEDEV puffs)</command>.
This is automatically done for new installations from sources
after January 2007.
</para>
<para>
In November 2007 part of the functionality written for
puffs was generalized into the Pass-to-Userspace Transporter
or <emphasis>putter</emphasis>. To use puffs, you also need to
include putter in your kernel:
<screen>
# Pass-to-Userspace Transporter
pseudo-device putter
</screen>
</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>puffs sshfs</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
</screen>
</sect4>
<sect4 id="example-9p">
<title>
<ulink url="http://www.cs.bell-labs.com/sys/man/5/INDEX.html">9P</ulink>
file servers
</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 & 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="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse/README.html">fuse</ulink>: Filesystem in Userspace (compat headers, pkg-config files,
etc.), needed for pkgsrc on Linux
</listitem>
<listitem>
<ulink
url="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-archivemount/README.html">fuse-archivemount</ulink>:
FUSE gateway to libarchive
</listitem>
<listitem>
<ulink
url="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-cddfs/README.html">fuse-cddfs</ulink>:
FUSE filesystem that uses libparanoia for audio CDs
</listitem>
<listitem>
<ulink
url="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-ntfs-3g/README.html">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="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/README.html">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>
</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>The <ulink url="http://man.NetBSD.org/man/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>
<sect3 id="history">
<title>History</title>
<para>
puffs was originally developed during the Google Summer of Code
2005 "<ulink
url="http://netbsd-soc.sourceforge.net/projects/userfs/">userfs</ulink>"
project by Antti Kantee. It was further polished using funding
from the Ulla Tuominen Foundation and committed into the
NetBSD source tree in October 2006. The "refuse" library
was written by Alistair Crooks and committed to NetBSD in
February 2007. All components will be available in NetBSD
releases starting with NetBSD 5. Work for using FUSE-enabled
packages via pkgsrc was done by Juan Romero Pardines following
import of the "refuse" library. Hubert Feyrer prepared the
initial version of this webpage.
</para>
</sect3>
</sect2>
</sect1>
</webpage>
![[BACK]](/icons/back.gif){kind=icon}
Return to index.xml CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / htdocs / docs / puffs