Cross-platform FUSE library for Go

Cgofuse is a cross-platform FUSE library for Go. It is supported on multiple platforms and can be ported to any platform that has a FUSE implementation. It has cgo, !cgo (aka "nocgo") and FUSE (aka "FUSE2"), FUSE3 variants depending on the platform.

	cgo	!cgo	FUSE	FUSE3
Windows	✓	✓	✓
macOS	✓		✓	✓FUSE-T
Linux	✓		✓	✓
FreeBSD	✓		✓	✓
NetBSD	✓		✓
OpenBSD	✓		✓

About this fork

This repository is a fork of winfsp/cgofuse, maintained for the gMountie project.

The original cgofuse library is the work of Bill Zissimopoulos and remains his copyright (Copyright 2017-2022 Bill Zissimopoulos). cgofuse is licensed under the MIT license — see LICENSE.txt. All credit for the original library belongs to its author and the upstream contributors; this fork makes no claim of authorship over cgofuse.

This fork adds a handful of gMountie-specific enhancements (a lock-free handle table, additional FUSE3 operations and capability setters, and an extra libfuse3 loader fallback) on top of upstream. See Changelog.md for details. For the canonical, upstream library please refer to https://github.com/winfsp/cgofuse.

How to build

Windows

• Prerequisites: WinFsp, gcc (e.g. from Mingw-builds)
• Build cgo:

  > set CPATH=C:\Program Files (x86)\WinFsp\inc\fuse
  > go install -v ./fuse ./examples/memfs
  

• Build !cgo:

  > set CGO_ENABLED=0
  > go install -v ./fuse ./examples/memfs
  

macOS

• Prerequisites: macFUSE (FUSE2) or FUSE-T (FUSE3), command line tools
• Build (macFUSE / FUSE2, the default):

  $ go install -v ./fuse ./examples/memfs ./examples/passthrough
  

• Build (FUSE-T / FUSE3):

  $ go install -tags=fuse3 -v ./fuse ./examples/memfs
  

• Notes:
  • macFUSE's own FUSE3 is a Darwin-specific API dialect and is not supported. On macOS, macFUSE is used via FUSE2 (the default) and FUSE3 is provided by FUSE-T, whose libfuse3 is upstream-API-compatible.
  • FUSE-T has two mount backends. Prefer FSKit (-o backend=fskit, macOS 15+) over the default NFS backend: on real hardware FUSE-T/NFS fails fsx mmap data-consistency checks and is several times slower for metadata, while FSKit is data-consistent and the fastest backend. macFUSE (FUSE2) passes the full pjdfstest/fsx conformance suite.

Linux

• Prerequisites: libfuse-dev, libfuse3-dev, gcc
• Build (FUSE3 is the default):

  $ go install -v ./fuse ./examples/memfs ./examples/passthrough
  

• Build FUSE2:

  $ go install -tags=fuse2 -v ./fuse ./examples/memfs ./examples/passthrough
  

FreeBSD

• Prerequisites: fusefs-libs, fusefs-libs3
• Build (FUSE3 is the default):

  $ go install -v ./fuse ./examples/memfs ./examples/passthrough
  

• Build FUSE2:

  $ go install -tags=fuse2 -v ./fuse ./examples/memfs ./examples/passthrough
  

• Note: You may also need the following in order to run FUSE file system. Commands must be run as root.

  $ vi /boot/loader.conf                      # add: fuse_load="YES"
  $ sysctl vfs.usermount=1                    # allow user mounts
  $ pw usermod USERNAME -G operator           # allow user to open /dev/fuse
  

NetBSD

• Prerequisites: NONE
• Build:

  $ go install -v ./fuse ./examples/memfs ./examples/passthrough
  

• Note: You may also need the following in order to run FUSE file systems. Commands must be run as root.

  $ chmod go+rw /dev/puffs
  $ sysctl -w vfs.generic.usermount=1
  

• Note: Support is experimental. There are known issues that stem from the differences in the NetBSD librefuse implementation from the reference libfuse implementation.

OpenBSD

• Prerequisites: NONE
• Build:

  $ go install -v ./fuse ./examples/memfs ./examples/passthrough
  

• Note: OpenBSD 6 removed the kern.usermount option, which allowed non-root users to mount file systems [link]. Therefore you must be root in order to use FUSE and cgofuse.
• Note: Support is experimental. There are known issues that stem from the differences in the OpenBSD libfuse implementation from the reference libfuse implementation.

How to use

User mode file systems are expected to implement fuse.FileSystemInterface. To make implementation simpler a file system can embed ("inherit") a fuse.FileSystemBase which provides default implementations for all operations. To mount a file system one must instantiate a fuse.FileSystemHost using fuse.NewFileSystemHost.

The full documentation is available at GoDoc.org: package fuse

There are currently four example file systems:

• Hellofs is an extremely simple file system. Runs on all OS'es.
• Memfs is an in memory file system. Runs on all OS'es.
• Passthrough is a file system that passes all operations to the underlying file system. Runs on all OS'es except Windows.
• Notifyfs is a file system that can issue file change notifications. Runs on Windows only.

How it is tested

The following software is being used to test cgofuse.

Windows (cgo and !cgo)

• winfsp-tests
• fsx

macOS

• fstest
• fsx

Linux

• fstest
• fsx

FreeBSD

• fsx