**Contents**
[[!toc levels=2]]
# Filesystems in userspace: puffs, refuse, FUSE, and more
## About
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.
This page describes the situation in NetBSD 5.0 and later.
## Components
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:
![Overview about puffs](/puffs/puffs.png)
**Overview about puffs**
The components themselves are:
* **puffs** is the core component inside the kernel. It exposes a file system
interface towards the userland programs (accessible via `/dev/puffs` 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.
* The **libpuffs** 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.
* 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 **librefuse**. The
re-implementation of the FUSE functionality is designed to be source code
compatible with FUSE, and it is further described in the
[refuse(3)](http://netbsd.gw.com/cgi-bin/man-cgi?refuse+3+NetBSD-current+i386)
manpage.
Examples for puffs and refuse filesystems can be found in the the NetBSD source
tree in `src/share/examples/{puffs,refuse}`.
## Enabling puffs
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.
file-system PUFFS
pseudo-device putter
Alternatively, modules can be used.
## Base system examples
This section presents usage examples for file systems shipped with the NetBSD
base system.
### psshfs, The NetBSD sshfs
See the manpage for
[psshfs(8)](http://netbsd.gw.com/cgi-bin/man-cgi?mount_psshfs+8+NetBSD-5.1+i386).
# 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
### 9P file servers
See the [Bell manpage](http://www.cs.bell-labs.com/sys/man/5/INDEX.html) and
the [NetBSD manpage 9p(8)](http://netbsd.gw.com/cgi-bin/man-cgi?mount_9p+8+NetBSD-5.1+i386).
# 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
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
`mount_9p` on a later date.
## pkgsrc & FUSE
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:
* [fuse](ftp://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse/README.html)
-- filesystem in userspace (compat headers, pkg-config files, etc.), needed for
pkgsrc on Linux
* [fuse-archivemount](ftp://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-archivemount/README.html)
-- FUSE gateway to libarchive
* [fuse-cddfs](ftp://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-cddfs/README.html)
-- FUSE filesystem that uses libparanoia for audio CDs
* [fuse-ntfs-3g](ftp://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/filesystems/fuse-ntfs-3g/README.html)
-- a NTFS driver with read and write support
* ...
More packages are currently being worked on, please see
[pkgsrc/filesystems](ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/filesystems/README.html)
for a full list.
Here is an example of installing and using the FUSE-enabled NTFS-3g
implementation:
# cd pkgsrc/filesystems/fuse-ntfs-3g
# make install
# ntfs-3g ntfs.img /ntfs
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
[here](http://www.cs.hut.fi/~pooka/NetBSD/librefuse_nb4-20080115.tar.gz)
and further instructions are available
[here](http://mail-index.NetBSD.org/netbsd-users/2008/01/15/msg000075.html).
## Further Information
An in-depth technical description of puffs was presented at
[AsiaBSDCon](http://www.asiabsdcon.org/) 2007 in a paper entitled
*puffs - Pass-to-Userspace Framework File System*. The
[paper](http://2007.asiabsdcon.org/papers/P04-paper.pdf) and
[slides](http://2007.asiabsdcon.org/papers/P04-slides.pdf) are available.
The ReFUSE emulation layer for FUSE file systems is described in
*[ReFUSE: Userspace FUSE Reimplementation Using puffs](/puffs/refuse.pdf)*
presented at EuroBSDCon 2007.
A [paper](http://2008.asiabsdcon.org/papers/P4B-paper.pdf) discussing the
implementation of distributed file systems on top of puffs was presented at
AsiaBSDCon 2008.
The [puffs(3)](http://man.NetBSD.org/man/puffs+3) manual pages provide further
information from a development perspective.
The source code in browsable form:
* [kernel code](http://cvsweb.netbsd.org/bsdweb.cgi/src/sys/fs/puffs/)
* [libpuffs](http://cvsweb.netbsd.org/bsdweb.cgi/src/lib/libpuffs/)
* [librefuse](http://cvsweb.netbsd.org/bsdweb.cgi/src/lib/librefuse/)
* [puffs file systems in the base system](http://cvsweb.netbsd.org/bsdweb.cgi/src/usr.sbin/puffs/)
* [source code examples of other puffs file systems](http://cvsweb.netbsd.org/bsdweb.cgi/src/share/examples/puffs/)
* [source code examples for refuse](http://cvsweb.netbsd.org/bsdweb.cgi/src/share/examples/refuse/)