Skip to content

Home

Jump to bottom
Alex Fishman edited this page May 29, 2024 · 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

Experimental fuse-t framework

Allows embedding fuse into macOS apps without the need to install the fuse-t package.
It's located in /Library/Frameworks/fuse-t.framework
To use: #include <fuse-t/fuse-t.h>

Supported mount options

The following mount options are supported at this moment:

  • -r: Mount a read-only filesystem. Usage: [exec] -r [mountpoint] or [exec] -o ro [mountpoint]
  • -volname: Name a volume in Finder. Usage: [exec] -o volname=somename [mountpoint]
  • -nonamedattr: Disable named attributes on the mounted volume. Usage: [exec] -o nonamedattr [mountpoint]
  • -noattrcache: Disable attribute caching. Usage: [exec] -o noattrcache [mountpoint]
  • -rwsize=[value]: Set read and write data sizes, value should be a power of two (default is 32768). Usage: [exec] -o rwsize=64536 [mountpoint]
  • -nobrowse: Makes volume invisible in Finder. Usage: [exec] -o nobrowse [mountpoint]
  • -nfc: Use NFC unicode encoding for file names. Usage: [exec] -o nfc [mountpoint]
  • -nomtime: Don't change modify time on setattr call. This is a workaround for Finder Preview changing file modify time. Usage: [exec] -o nomtime
  • -location: Customize the name of the root folder for fuse-t mounts in Finder from localhost. You need to edit /etc/hosts and add your own alias to 127.0.0.1. After this: [exec] -o location=[alias]
  • -backend=[smb|nfs]: Set a backend which can be either NFS of SMB. The default is NFS.

Additional options:

  • -d: Debug mode. Usage: [exec] -d [mountpoint]. The NFS sever will write debug logs to ~/Library/Logs/fuse-t folder
  • -l: Set NFS listen address instead of a default one. Usage: [exec] -l 0:1234 [mountpoint]. 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
  • Volume icons (There's no macOS support for setting a volume icon for a network drive)

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 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
  • A FUSE-T mount point is visible in the Finder as ”localhost”. How can it be hidden/removed?
    Create a hidden or temporary folder. For example "~/.hidden". It won't appear in Finder by default.

Sample filesystems

Clone this wiki locally