Fuse module

This text is about a port of 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 http://wikitest.freebsd.org/moin.cgi/FuseFilesystem; for updates, further info go there. Get in contact with me via the soc-chenk email addrees of the FreeBSD organization (freebsd.org).

Installation

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.

Downloads

You need to get a bunch of things.

• Fuse itself. Get Fuse 2.4.0 from their 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, http://creo.hu/~csaba/projects/fuse4bsd/downloads/.

• The FreeBSD module. Source tarballs are provided at http://creo.hu/~csaba/projects/fuse4bsd/downloads/ under the name fuse4bsd-<version>.tar.* (latest release is 0.2.20pre6, date of release: 18th Oct 2005). The current code is available via Darcs, you can fetch it by

   darcs get http://creo.hu/~csaba/darcs-repos/fuse4bsd

  command, or via 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 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 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