README

Fuse perl bindings
==================

Fuse is combination of Linux kernel module and user space library which
enables you to write user-space filesystems. This module enables you to
write filesystems using perl.

Additional file-systems using Fuse module are released on CPAN using Fuse::
namespace. Currently that includes only Fuse::DBI which allows you to mount
database as file system, but there will be more.

This is a pre-production release.  It seems to work quite well.  In fact, I
can't find any problems with it whatsoever.  If you do, I want to know.

INSTALLATION

To install this module type the standard commands as root:

   perl Makefile.PL
   make
   make test
   make install


DEPENDENCIES

This module requires the FUSE C library and the FUSE kernel module.
See http://fuse.sourceforge.net/

If you intend to use FUSE in threaded mode, you need a version of Perl which
has been compiled with USE_ITHREADS.  Then, you need to use threads and
threads::shared.


COPYRIGHT AND LICENCE

This is contributed to the FUSE project by Mark Glines <mark@glines.org>,
and is therefore subject to the same license and copyright as FUSE itself.
Please see the AUTHORS and COPYING files from the FUSE distribution for
more information.


EXAMPLES

There are a few example scripts.  You can find them in the examples/
subdirectory.  These are:

* example.pl, a simple "Hello world" type of script

* loopback.pl, a filesystem loopback-device.  like fusexmp from
               the main FUSE dist, it simply recurses file operations
               into the real filesystem.  Unlike fusexmp, it only
               re-shares files under the /tmp/test directory.

* rmount.pl, an NFS-workalike which tunnels through SSH.  It requires
             an account on some ssh server (obviously), with public-key
             authentication enabled.  (if you have to type in a password,
             you don't have this.  man ssh_keygen.).  Copy rmount_remote.pl
             to your home directory on the remote machine, and create a
             subdir somewhere, and then run it like:
             ./rmount.pl host /remote/dir /local/dir

* rmount_remote.pl, a ripoff of loopback.pl meant to be used as a backend
                    for rmount.pl.


BUGS

Currently tests have been attempted and succeeded on:
  * Ubuntu 13.04/amd64
  * Fedora 19/amd64
  * CentOS 6.4/amd64
  * CentOS 5.9/amd64
  * CentOS 5.9/i386
  * OpenSuSE 12.3/amd64
  * Debian 7.1/powerpc
  * Slackware 13.1/amd64
  * NetBSD 6.1.1/amd64
  * FreeBSD 9.1/amd64
  * MacOS X 10.6.8 [OSXFUSE 2.6.1]
  * MacOS X 10.7.5 [OSXFUSE 2.6.1]


NOTES FOR BSD USERS

On NetBSD, there is a potential issue with readdir() only being called
once when using librefuse. However, currently using Perfuse causes other
issues (readlink() drops the last character from the read link path, and
the block count in stat() is incorrect). We will be addressing these
concerns with the appropriate developers in the near future.

If you are using Perfuse on NetBSD, you should do the following (as root):

cat >> /etc/sysctl.conf <<_EOT_
kern.sbmax=2621440
net.inet.tcp.sendbuf_max=2621440
net.inet6.tcp6.sendbuf_max=2621440
_EOT_
sysctl -f /etc/sysctl.conf

Perfuse uses TCP sockets, and needs large send buffers.

On NetBSD and FreeBSD, extended attributes do not work. These are
specifically related to the FUSE implementations on those platforms.

Normally you can not mount FUSE filesystems as non-root users on FreeBSD
and NetBSD. They can allow non-root users to mount FUSE filesystems, but
instead of changing the mode of /dev/fuse or /bin/fusermount, you need
to use sysctl to allow user mounts. For FreeBSD, this involves (as root):

sysctl -w vfs.usermount=1
pw usermod <your username here> -G operator

And on NetBSD (also as root):

sysctl -w vfs.generic.usermount=1
chmod 0660 /dev/putter
usermod -G wheel <your username here>


NOTES FOR OPENBSD IN PARTICULAR

Oh, hello. You're an OpenBSD user. You like your secure, minimalist OS, but
you really want in on that FUSE-y goodness. Well, it's still pretty early
and kind of broken, but yes, FUSE has actually made its way onto OpenBSD.

That said, it's not (as of this writing) in a released version. It is
in OpenBSD -current; you probably shouldn't be running a production system
with -current, but a VM can be readily installed from the -current ISOs,
available from better OpenBSD mirrors near you.

If you're going to upgrade an existing install to -current, you should be
familiar with building a kernel, and your entire userspace; if not, read
the OpenBSD FAQ for more info.

For the tests, I recommend installing devel/p5-Lchown, and installing
Filesys::Statvfs, Unix::Mknod and Test::Pod out of CPAN.

Okay, once you've done all that, run (as root):

cd /dev
./MAKEDEV fuse

Now, in your perl-fuse distribution, run:

perl Makefile.PL
make

You'll probably need to 'make test' as root. If you want to run your FUSE
filesystem as non-root, run the following (as root):

sysctl kern.usermount=1
chmod 0660 /dev/fuse0

Now, you should be able to run 'make test'. Yes, there are some test
failures. No, those actually aren't our fault. Here are some things
you should know about the state of FUSE on OpenBSD:

 * There is a bug if a file is created in the fuse filesystem and goes
   away, then you create another file of the same name via FUSE and
   try to do utime(). Not sure if it's just utime() or if other things
   trip it too, but I discovered that via playing around. I *THINK*
   it's a vnode caching problem.
 * There is a known issue with readdir() when supplying numbered dirents
   to support progressive readdir(). The developer is investigating.
 * There is also a known issue with access() if all parent directories
   of a path haven't been explicitly accessed first. Developer is also
   investigating this.
 * You should probably implement all of chown(), chmod(), truncate(), and
   utime() and/or utimens(). The kernel driver will mask out future
   setattr() requests if it gets ENOSYS from ANY of these. Oops.

Anyway, happy FUSEing!