Fuse module

This text is about a port of [http://fuse.sourceforge.net/ Fuse] to FreeBSD. To get the context of this work, see my personal wiki page, CsabaHenk.

In the sequel I describe how to get started with Fuse under FreeBSD.

The main part of Fuse for FreeBSD is a kernel module which provides a kernel messaging interface to the Fuse library in userspace which is compatible with that of the Linux module. The userspace part is pretty portable. A lightweight patch is enough to get that compile and work.

The module can be excepted to work with RELENG_6 and HEAD (ie., 7.x) snapshots.

What can be considered as a public homepage for the project is FuseFilesystem]; for updates, further info go there. Get in contact with me via the soc-chenk email addrees of the FreeBSD organization (freebsd.org).

I'll describe here the installation of the core Fuse components and a Fuse based filesystem, sshfs, which lets you mount a machine remotely by means of an ssh conncetion.

You need to get a bunch of things.

• Fuse itself. Get Fuse 2.4.0 from their [http://sourceforge.net/projects/fuse Sourceforge project page]. If this is not availabe there (because a newer (pre)release has taken its place), you can either try to adopt these instructions to the newer (pre)release, or fetch it from my download directory, ].
• The FreeBSD module. Source tarballs are provided at ] under the name fuse4bsd-<version>.tar.* (latest release is 0.2.20pre4, date of release: 16th Oct 2005). The current code is available via [http://www.freshports.org/devel/darcs Darcs], you can fetch it by

 darcs get http://creo.hu/~csaba/darcs-repos/fuse4bsd}}}
 command, or via
 [http://perforce.freebsd.org/depotTreeBrowser.cgi?FSPC=/depot/projects/soc2005/fuse4bsd2 Perforce]
 (you can use this latter link for online source code browsing).

 ''Release tarballs and SCM snapshots include a version of this wiki page as {{{README.html}}}. Always act according to the included version.

 <!> '''Warning''': on rare occasions the wiki version may refer to a not yet committed state of the module code.''
 * Fuse sshfs. The latest release (1.2 as of writing this) should do, fetch the sshfs-fuse package also from the
 [http://sourceforge.net/projects/fuse Fuse SF project page].

=== Compilation ===

Let's start with the module.

 * From your Fuse distribution copy over {{{kernel/fuse_kernel.h}}} as {{{fuse_module/fuse_kernel.h.orig}}}.
 * For older snapshots, you'll need a special make flag. If you use a 6.x kernel and its {{{__FreeBSD_version}}} is lesser than
 {{{600034}}}, or you use a 7.x kernel and its {{{__FreeBSD_version}}} is lesser than {{{700002}}}, you will also have to add
 {{{-DUSE_OLD_CLONEHANDLER_API}}} to {{{make}}}'s parameters below. You can check this variable by the 
 {{{
 awk '/#define/{if ($2 == "__FreeBSD_version") { print $3; exit }}' /sys/sys/param.h}}}
 command.
 * Type {{{make}}}. If you want normal quantity of debug output, use the make flag {{{-DDEBUG2G}}}, if you want tons of debug output,
 use {{{-DDEBUG}}}.

Now go for the fuse userspace. We will assume that you have my module at {{{../fuse4bsd}}}.

 * Apply the patch with {{{
 patch -Np1 < ../fuse4bsd/fuselib/fuselib-2.4.0.diff}}}
 * Do 
 {{{
 cp ../fuse4bsd/fuse_module/fuse_kernel.h include/ &&
 cp ../fuse4bsd/fuse_module/linux_compat.h include/}}}
 (as {{{fuse_kernel.h}}} is used by both of kernel and userspace, the necessary patch is separated from the all-over userspace patch,
 and is kept by the module code).
 * We will do a non-privileged install (I'd say that's easier than set up a jail), I'll use
 {{{~/meta/fuse-2.4.0}}} as the prefix.
 Type the following commands: 
 {{{
 mkdir junk &&
 ln -s /usr/bin/true junk/chown &&
 ln -s /usr/bin/true junk/mknod &&
 echo 'echo "$1" | grep -q /etc/udev || /bin/mkdir "$@"' > junk/mkdir &&
 echo 'echo "$@" | grep -q udev || /usr/bin/install "$@"' > junk/install &&
 chmod a+x junk/mkdir junk/install &&
 (export PATH=`pwd`/junk:$PATH &&
 ./configure --prefix=$HOME/meta/fuse-2.4.0 --bindir=`pwd`/junk --disable-kernel-module MOUNT_FUSE_PATH=`pwd`/junk &&
 make &&
 make install)}}}

You have successfully installed fuse libs. Go on to sshfs.

 * Edit {{{sshfs.c}}}: add a {{{#include <sys/socket.h>}}} line to its includes.
 * Type 
 {{{
 env PKG_CONFIG_PATH=~/meta/fuse-2.4.0/lib/pkgconfig/ ./configure && make}}}

Congratulations, you have all components prepared!

=== Using the Fuse based ssh filesystem ===

Here we will show how to setup Fuse so that non-privileged users can use it, too.

As the superuser, do
{{{
kldload fuse_module/fuse.ko
sysctl vfs.usermount=1}}}

Now you'll have to act as a user belonging to the {{{operator}}} group. (A different access policy
could be set by [http://www.freebsd.org/cgi/man.cgi?query=devfs&sektion=8 devfs(8)]; eg., deleting
all barriers would look like {{{devfs rule add path 'fuse*' mode 666}}}. Think of permissions of fuse
devices directly as mount permissions of Fuse filesystems.)

Proceed on with the user you chose (nevertheless,
we will assume you use the same user as the one who did the installation).

Pick your favourite ssh accessible account (though maybe you'd better
stick to servers running OpenSSH -- I've seen commits in sshfs' CVS for better
interoperability with other servers, which show there might occur problems with them), 
say, it's {{{foo@bar.baz}}}. 

Go to sshfs' directory. First prepare the mount:
{{{
mkdir -p ~/fuse &&
export LD_LIBRARY_PATH=~/meta/fuse-2.4.0/lib/}}}
and also make sure that {{{mount_fusefs}}} (of FreeBSD Fuse) is in your path.
Then do:
{{{
mount_fusefs auto ~/fuse ./sshfs foo@bar.baz:}}}

If you want the daemon print the messages she gots from the kernel, you can append the {{{-d}}} flag to the end of
the mount command (standard Fuse flag, as ''debug''). However, this can be a little annoying, as the daemon will
go to background, but will also muck up the terminal with its reports (unlike when you use {{{-d}}} under Linux).
To keep it foreground, you can do the following:
{{{
env FUSE_DEV_NAME=/dev/fuse0 ./sshfs foo@bar.baz: -d}}}
Then open another terminal, and type there:
{{{
mount_fusefs /dev/fuse0 ~/fuse}}}
(If {{{/dev/fuse0}}} happens to be busy, use any other free Fuse device {{{/dev/fuseN}}}; most free of all is the one
who doesn't exist.)

Finally, you will have to umount the filesystem by {{{umount ~/fuse}}}.

For more details, see the man page ({{{mount_fusefs(8)}}}).

== Miscellaneous ==

You can get more info on Fuse based filesystems under FreeBSD at the Fuse wiki,
[http://fuse.sourceforge.net/wiki/index.php/FileSystemsOnFreeBSD]. Feel encouraged to add your experiences.

== Bugs ==

See the respective section of {{{mount_fusefs(8)}}}.

== TODO ==
 * Make autotools play nice with Fuse (generating configure files doesn't work with CVS snapshots)

 /!\ '''Autotools gurus, help please! It might be just a five minutes work for you to fix it.'''
 * Implement attr/name caching (with timeouts)
 * Implement various missing parts, optimize