Skip to content

Home

Jump to bottom
Alex Fishman edited this page Sep 25, 2022 · 24 revisions

About

This page is for providing a guidance for developers who wish to implement a filesystem based on fuse or port an existing one. In general, the code that worked with osxfuse should work as-is without any changes except linking to a new fuse-t library provided in the installation package.
The installation package copies the following files to your system:

  • FUSE include headers in /usr/local/include/fuse
  • FUSE dynamic and static library in /usr/local/include/lib: libfuse-t.dylib and libfuse-t.a
  • NFS server and support files in /Library/Application Support/fuse-t

Getting started

Take a look at examples provided by libfuse. It contains samples of working filesystems. In particular take a look at fusexmp_fh which implements a mirror filesystem.
Compilation settings to change or add:
CXX flags: -I/usr/local/include/fuse
LDD flags: -L/usr/local/lib -lfuse-t

Supported mount options

The following mount options are supported at this moment:

  • -r: Mount a read-only filesystem. Usage: [exec] -r or [exec] -o,ro
  • -volname: Name a volume in Finder. Usage: [exec] -o,volname=somename
  • -nonamedattr: Disable named attributes on the mounted volume. Usage: [exec] -o,nonamedattr

Additional options:

  • -d: Debug mode. Usage: [exec] -d . The NFS sever will write debug logs to /Application Support/Logs/fuse-t folder
  • -l: Set NFS listen address instead of a default one. Usage: [exec] -l 0:1234 . Pay attention that this might expose the NFS server to external connectivity and currently there's no authentication implemented.

Unsupported features

Some of the FUSE features are not supported at the moment

  • Locks: Work in progress All types of file locks (flock, lockf, fcntl) are supported natively by macOS but currently bypassing FUSE calls
  • Notifications: Work in progress
  • IOCTL call
  • BMAP call
  • FALLOCATE call
  • ACCESS call: unused

Caveats

  • A call sequence might look very different from the original osxfuse. It shouldn't cause issues unless the filesystem implementation is buggy.
  • READDIR call should return all results in the first pass. This limitation hopefully should be dropped for the next release
  • Caching of attributes is done by the NFS client. Currently the caching attributes returned by the filesystem implementation are ignored.
  • File access and modification times cannot be set separately as it seems to be an issue with the NFS client which always modifies both. Can be reproduced with 'touch -m' and 'touch -a' commands

FAQ

  • How to to uninstall FUSE-T
    Run sudo "/Library/Application Support/fuse-t/uninstall.sh"
  • What happens after I install it?
    Actually not much: it's useless for an end user unless you install another package that depends on it such as SSHFS. FUSE-T package is intended for developers wishing to implements their own FUSE based file system. It provides necessary header files, libraries and the runtime. That's it.
  • You claim in your README that fuse-t is a "Drop-in replacement for 'macfuse' (https://osxfuse.github.io/)", but my precompiled binary doesn't work after installing FUSE-T runtime
    FUSE-T installation package doesn't overwrite macfuse shared library. You still have an option to manually overwrite macfuse library with libfuse-t.dylib in /usr/local/lib but the preferred way is to recompile your package and point it to libfuse-t.dylib

Sample filesystems

Clone this wiki locally