<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta name="generator" content="Website XSL Stylesheet V2.6.0">
<link rel="home" href="../../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
<link rel="up" href="../../docs/." title="NetBSD Documentation">
<link rel="previous" href="../../docs/power-mgmt/." title="NetBSD Documentation: Power Management">
<link rel="next" href="../../docs/puffs/rump.html" title="Runnable Userspace Meta Programs (RUMPs)">
<link rel="first" href="../../docs/Hardware/." title="Hardware Documentation">
<link rel="last" href="../../docs/x/." title="NetBSD Documentation: The X Window System">
<link rel="stylesheet" href="../../global.css" type="text/css">
<title>Filesystems in userspace: puffs, refuse, FUSE, and more</title>
</head>
<body class="website"><div class="webpage">
<a name="docs-puffs-index"></a><div id="top"><a href="#mainContent" class="doNotDisplay doNotPrint">Skip to main content.</a></div>
<div id="header">
<div class="topNavigation">
<span>» </span><a href="../../docs/guide/en/">
The Guide</a> |
<a href="http://man.NetBSD.org/">Manual pages</a> |
<a href="../../mailinglists/">
Mailing lists</a> and
<a href="http://mail-index.NetBSD.org/">Archives</a> |
<a href="http://cvsweb.NetBSD.org/">CVS repository</a> |
<a href="http://www.NetBSD.org/cgi-bin/sendpr.cgi?gndb=netbsd">Report</a>
or
<a href="../../support/query-pr.html">
query</a> a bug |
<a href="../../docs/software/packages.html">
Software Packages
</a>
</div>
<div class="centralHeader">
<a href="../../"><img alt="[NetBSD Logo]" width="506" height="90" src="../../images/NetBSD-headerlogo.png"></a><div class="headerTools"><div id="headerSearch"><form method="get" action="http://www.google.com/custom">
<input class="whiteOnBlack" type="text" name="q" onfocus="if(this.value==this.defaultValue ) this.value='';" size="12" maxlength="255" value="Search"><input type="hidden" name="cof" value="L:http://www.NetBSD.org/images/NetBSD-smaller.png;LH:200;LW:200;AH:center;AWFID:4f6b0499f0f58d2c;"><input type="hidden" name="domains" value="NetBSD.org"><input type="hidden" name="sitesearch" value="www.NetBSD.org"><input type="submit" value="Search">
</form></div></div>
</div>
<div class="navBar">
<span class="doNotDisplay">
Navigation:
</span><a href="../../">
Home</a> ü <a href="../../about/">
About</a> ü <a href="../../releases/">
Download</a> ü <a href="../../docs/">
Documentation</a> ü <a href="../../support/">
Support</a> ü <a href="../../community/">
Community</a> ü <a href="../../ports/">
Ports</a>
</div>
</div>
<div id="content"><div class="fullWidth"><div class="rowOfBoxes">
<h1>Filesystems in userspace: puffs, refuse, FUSE, and more</h1>
<div class="sect1" lang="en">
<div class="titlepage"></div>
</div>
<h3 class="title"><a name="puffs"></a></h3>
<ul>
<li><a href="#about">About</a></li>
<li><a href="#components">Components</a></li>
<li><a href="#enabling">Enabling puffs in the base system</a></li>
<li><a href="#examples">Base system examples</a></li>
<li><a href="#pkgsrc">pkgsrc & FUSE</a></li>
<li><a href="#moreinfo">Further Information</a></li>
<li><a href="#history">History</a></li>
</ul>
<hr>
<h3 class="title"></h3>
<h4 class="title">
<a name="about"></a>About (<a href="#puffs">top</a>)
</h4>
<p>
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.
</p>
<p>
These components are experimental and may become available
as part of the standard distribution in a future release.
</p>
<h4 class="title">
<a name="components"></a>Components (<a href="#puffs">top</a>)
</h4>
<p>
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:
</p>
<div class="figure">
<a name="puffs-overview"></a><p class="title"><b>Figure. Ïverview about puffs</b></p>
<div class="figure-contents">
<div class="mediaobject"><img src="puffs.png" alt="Overview about puffs"></div>
</div>
</div>
<br class="figure-break">
<p>
The components themselves are:
</p>
<div class="itemizedlist"><ul type="disc">
<li>
<p>
<span class="bold"><strong>puffs</strong></span> is the core component
inside the kernel. It exposes a file
system interface towards the userland programs (accessible via
<code class="filename">/dev/puffs</code> 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 <a href="http://netbsd.gw.com/cgi-bin/man-cgi?puffs+4+NetBSD-current">puffs(4)</a> manpage.
</p>
</li>
<li>
<p>
The "<span class="bold"><strong>libpuffs</strong></span>" 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 <a href="http://netbsd.gw.com/cgi-bin/man-cgi?puffs+3+NetBSD-current">puffs(3)</a> manpage.
</p>
</li>
<li>
<p>
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 "<span class="bold"><strong>librefuse</strong></span>". The re-implementation of the
FUSE functionality is designed to be source code compatible with
FUSE, and it is further described in the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?refuse+3+NetBSD-current">refuse(3)</a> manpage.
</p>
</li>
</ul></div>
<p>
Examples for puffs and refuse filesystems can be found in the
following directory of the NetBSD source tree in
<code class="filename">src/share/examples/{puffs,refuse}</code>.
</p>
<h4 class="title">
<a name="enabling"></a>Enabling puffs in the base system (<a href="#puffs">top</a>)
</h4>
<p>
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.
</p>
<pre class="programlisting">
/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
</pre>
<p>
</p>
<p>
Also make sure that the device node <code class="filename">/dev/puffs</code>
exists by running <span class="command"><strong>(cd /dev ; sh MAKEDEV puffs)</strong></span>.
This is automatically done for new installations from sources
after January 2007.
</p>
<p>
In November 2007 part of the functionality written for
puffs was generalized into the Pass-to-Userspace Transporter
or <span class="emphasis"><em>putter</em></span>. To use puffs, you also need to
include putter in your kernel:
</p>
<pre class="programlisting">
# Pass-to-Userspace Transporter
pseudo-device putter
</pre>
<p>
</p>
<h4 class="title">
<a name="examples"></a>Base system examples (<a href="#puffs">top</a>)
</h4>
<p>
This section presents usage examples for file systems shipped with
the NetBSD base system.
</p>
<div class="sect4" lang="en">
<div class="titlepage"><div><div><h5 class="title">
<a name="example-psshfs"></a>puffs sshfs</h5></div></div></div>
<pre class="programlisting">
# 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
</pre>
</div>
<div class="sect4" lang="en">
<div class="titlepage"><div><div><h5 class="title">
<a name="example-9p"></a>
<a class="ulink" href="http://www.cs.bell-labs.com/sys/man/5/INDEX.html" target="_top">9P</a>
file servers
</h5></div></div></div>
<pre class="programlisting">
# 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
#
</pre>
<p>
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 <span class="command"><strong>mount_9p</strong></span>
on a later date.
</p>
</div>
<h4 class="title">
<a name="pkgsrc"></a>pkgsrc & FUSE (<a href="#puffs">top</a>)
</h4>
<p>
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:
</p>
<div class="itemizedlist"><ul type="disc">
<li>
<a class="ulink" href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse/README.html" target="_top">fuse</a>: Filesystem in Userspace (compat headers, pkg-config files,
etc.), needed for pkgsrc on Linux
</li>
<li>
<a class="ulink" href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-archivemount/README.html" target="_top">fuse-archivemount</a>:
FUSE gateway to libarchive
</li>
<li>
<a class="ulink" href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-cddfs/README.html" target="_top">fuse-cddfs</a>:
FUSE filesystem that uses libparanoia for audio CDs
</li>
<li>
<a class="ulink" href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-ntfs-3g/README.html" target="_top">fuse-ntfs-3g</a>:
a NTFS driver with read and write support
</li>
<li>
...
</li>
</ul></div>
<p>
More packages are currently being worked on, please see
<a class="ulink" href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/README.html" target="_top">pkgsrc/filesystems</a>
for a full list.
</p>
<p>
Here is an example of installing and using the FUSE-enabled
NTFS-3g implementation:
</p>
<pre class="programlisting">
# cd pkgsrc/filesystems/fuse-ntfs-3g
# make install
# ntfs-3g ntfs.img /ntfs
</pre>
<p>
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
<a class="ulink" href="http://www.cs.hut.fi/~pooka/NetBSD/librefuse_nb4-20080115.tar.gz" target="_top">here</a>
and further instructions are available
<a class="ulink" href="http://mail-index.netbsd.org/netbsd-users/2008/01/15/msg000075.html" target="_top">here</a>.
</p>
<h4 class="title">
<a name="moreinfo"></a>Further Information (<a href="#puffs">top</a>)
</h4>
<p>An in-depth technical description of puffs was presented at
<a class="ulink" href="http://www.asiabsdcon.org/" target="_top">AsiaBSDCon</a> 2007
in a paper entitled "puffs - Pass-to-Userspace Framework File System".
The <a class="ulink" href="http://2007.asiabsdcon.org/papers/P04-paper.pdf" target="_top">paper</a> and
<a class="ulink" href="http://2007.asiabsdcon.org/papers/P04-slides.pdf" target="_top">slides</a>
are available.
</p>
<p>The ReFUSE emulation layer for FUSE file systems is described
in "<a class="ulink" href="refuse.pdf" target="_top">ReFUSE: Userspace FUSE
Reimplementation Using puffs</a>" presented at EuroBSDCon 2007.
</p>
<p>A
<a class="ulink" href="http://2008.asiabsdcon.org/papers/P4B-paper.pdf" target="_top">paper</a>
discussing the implementation of distributed file systems on top
of puffs was presented at AsiaBSDCon 2008.
</p>
<p>The <a class="ulink" href="http://man.NetBSD.org/man/puffs+3" target="_top">puffs</a>
manual pages provide further information from a development perspective.
</p>
<p>The source code in browsable form:
</p>
<div class="itemizedlist"><ul type="disc">
<li><a class="ulink" href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/sys/fs/puffs/" target="_top">kernel code</a></li>
<li><a class="ulink" href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/lib/libpuffs/" target="_top">libpuffs</a></li>
<li><a class="ulink" href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/lib/librefuse/" target="_top">librefuse</a></li>
<li><a class="ulink" href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/usr.sbin/puffs/" target="_top">puffs file systems in the base system</a></li>
<li><a class="ulink" href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/share/examples/puffs/" target="_top">source code examples of other puffs file systems</a></li>
<li><a class="ulink" href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/share/examples/refuse/" target="_top">source code examples for refuse</a></li>
</ul></div>
<p>
</p>
<h4 class="title">
<a name="history"></a>History (<a href="#puffs">top</a>)
</h4>
<p>
puffs was originally developed during the Google Summer of Code
2005 "<a class="ulink" href="http://NetBSD-soc.sourceforge.net/projects/userfs/" target="_top">userfs</a>"
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.
</p>
</div></div></div>
<div class="navfoot"></div>
<div id="footer"><center>
<span class="footfeed"><a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">
Contact</a> |
</span><span class="footcopy"><a href="../../about/disclaimer.html">
Disclaimer</a> |
<span class="copyright">Copyright 1994-2008 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>/sup> is a registered trademark of The NetBSD
Foundation, Inc.</span>
</center></div>
</div></body>
</html>