cberner / fuser

Filesystem in Userspace (FUSE) for Rust

FUSE (Filesystem in Userspace) for Rust

About

FUSE-Rust is a Rust library crate for easy implementation of FUSE filesystems in userspace.

FUSE-Rust does not just provide bindings, it is a rewrite of the original FUSE C library to fully take advantage of Rust's architecture.

This library was originally forked from the fuse crate with the intention of continuing development. In particular adding features from ABIs after 7.19

Documentation

FUSE-Rust reference

Details

A working FUSE filesystem consists of three parts:

1. The kernel driver that registers as a filesystem and forwards operations into a communication channel to a userspace process that handles them.
2. The userspace library (libfuse) that helps the userspace process to establish and run communication with the kernel driver.
3. The userspace implementation that actually processes the filesystem operations.

The kernel driver is provided by the FUSE project, the userspace implementation needs to be provided by the developer. FUSE-Rust provides a replacement for the libfuse userspace library between these two. This way, a developer can fully take advantage of the Rust type interface and runtime features when building a FUSE filesystem in Rust.

Except for a single setup (mount) function call and a final teardown (umount) function call to libfuse, everything runs in Rust, and on Linux these calls to libfuse are optional. They can be removed by building without the "libfuse" feature flag.

Dependencies

FUSE must be installed to build or run programs that use FUSE-Rust (i.e. kernel driver and libraries. Some platforms may also require userland utils like fusermount). A default installation of FUSE is usually sufficient.

To build FUSE-Rust or any program that depends on it, pkg-config needs to be installed as well.

Linux

FUSE for Linux is available in most Linux distributions and usually called fuse or fuse3 (this crate is compatible with both). To install on a Debian based system:

sudo apt-get install fuse3 libfuse3-dev

Install on CentOS:

sudo yum install fuse

To build, FUSE libraries and headers are required. The package is usually called libfuse-dev or fuse-devel. Also pkg-config is required for locating libraries and headers.

sudo apt-get install libfuse-dev pkg-config

sudo yum install fuse-devel pkgconfig

macOS (untested)

Installer packages can be downloaded from the FUSE for macOS homepage. This is the kernel part that needs to be installed always.

To install using Homebrew

brew install macfuse

To install using Nix

nix-env -iA nixos.osxfuse

And pkg-config (required for building):

nix-env -iA nixos.pkg-config

When using nix it is required that you specify PKG_CONFIG_PATH environment variable to point at where osxfuse is installed:

export PKG_CONFIG_PATH=${HOME}/.nix-profile/lib/pkgconfig

FreeBSD

Install packages fusefs-libs and pkgconf.

pkg install fusefs-libs pkgconf

Usage

Put this in your Cargo.toml:

[dependencies]
fuser = "0.7"

To create a new filesystem, implement the trait fuser::Filesystem. See the documentation for details or the examples directory for some basic examples.

To Do

Most features of libfuse up to 3.10.3 are implemented. Feel free to contribute. See the list of issues on GitHub and search the source files for comments containing "TODO" or "FIXME" to see what's still missing.

Compatibility

Developed and tested on Linux. Tested under Linux and FreeBSD using stable Rust (see CI for details).

License

Licensed under MIT License, except for those files in examples/ that explicitly contain a different license.

Contribution

Fork, hack, submit pull request. Make sure to make it useful for the target audience, keep the project's philosophy and Rust coding standards in mind. For larger or essential changes, you may want to open an issue for discussion first. Also remember to update the Changelog if your changes are relevant to the users.

fuser's Issues

Make capabilities configurable in init()

• FUSE_ASYNC_READ
• FUSE_POSIX_LOCKS
• FUSE_FILE_OPS
• FUSE_ATOMIC_O_TRUNC
• FUSE_EXPORT_SUPPORT
• FUSE_BIG_WRITES
• FUSE_DONT_MASK
• FUSE_SPLICE_WRITE
• FUSE_SPLICE_MOVE
• FUSE_SPLICE_READ
• FUSE_FLOCK_LOCKS
• FUSE_HAS_IOCTL_DIR
• FUSE_AUTO_INVAL_DATA
• FUSE_DO_READDIRPLUS
• FUSE_READDIRPLUS_AUTO
• FUSE_ASYNC_DIO
• FUSE_WRITEBACK_CACHE
• FUSE_NO_OPEN_SUPPORT
• FUSE_PARALLEL_DIROPS
• FUSE_HANDLE_KILLPRIV
• FUSE_POSIX_ACL
• FUSE_ABORT_ERROR
• FUSE_MAX_PAGES
• FUSE_CACHE_SYMLINKS
• FUSE_NO_OPENDIR_SUPPORT
• FUSE_EXPLICIT_INVAL_DATA

Support FUSE_INTERRUPT

Enable Cirrus CI for FreeBSD testing

Make time_gran configurable

add FUSE_WRITEBACK_CACHE

Cleanup Clippy warnings in examples/simple.rs

add FUSE_POSIX_ACL

add FATTR_CTIME

add FUSE_MAX_PAGES, add max_pages to init_out

Support building against libfuse3

add FUSE_ABORT_ERROR

add FUSE_NO_OPENDIR_SUPPORT flag

add FUSE_HANDLE_KILLPRIV

Remove dependency on native libfuse library

This can be done by reimplementing the mount and unmount functions from libfuse, including the IPC with fusemount binary

AutoUnmount requires AllowRoot or AllowOther

The AutoUnmount option requires that AllowRoot or AllowOther also be provided, unless the user is root, so that the fusermount3 binary can unmount the filesystem. We should check this during check_option_conflicts

add FUSE_RENAME2 request

Update README

• Document that libfuse is optional on Linux
• Explain how this create is different from fuse

add ctime and ctimensec to fuse_setattr_in

add time_gran to fuse_init_out

Add support for building without libfuse on FreeBSD

add FUSE_LSEEK for SEEK_HOLE and SEEK_DATA support

add FOPEN_CACHE_DIR

Support FUSE_BATCH_FORGET

Add option compatibility checking to mount2()

It should not allow things like setting both suid and nosuid

Use Slightly Higher Level Types

A lot of places in the code use base level types to mean lots of different things. For example, ReplyCreated:

pub fn created(
    self,
    ttl: &Duration,
    attr: &FileAttr,
    generation: u64,
    fh: u64,
    flags: u32
)

I propose creating types called GenerationId and FileHandleID etc. which are .into()d when passed to the kernel. This way, it is more difficult to confuse arguments and values by mistake. This is especially true when calling the created function, since you don't even have the benefit of naming the argument being passed. What I mean by this is constructing a struct it would be easier to tell the mistake:

Foo {
  generation: fh,
  fh: generation
}

vs:

created(duration, attr, fh, generation, flags)

Support FUSE_FALLOCATE

add FUSE_EXPLICIT_INVAL_DATA

Make congestion_threshold configurable

Update open flags from u32 to i32

Hello,

thanks for the work you are doing forking this library.

The open call get as input the flag argument as u32, is there a reason for this?

fuser/src/lib.rs

Line 271 in abe89cc

fn open(&mut self, _req: &Request<'_>, _ino: u64, _flags: u32, reply: ReplyOpen) {

I will be in favor to update that to a i32 to match the C (int) and Rust interface (i32).

I can submit a PR if this will help in getting this API fix in.

Make max_write configurable

add FUSE_IOCTL_COMPAT_X32

add FUSE_PARALLEL_DIROPS

Support FUSE_IOCTL

add FUSE_NO_OPEN_SUPPORT flag

Enable xfstests and pjdfstests as part of CI

add FUSE_WRITE_KILL_PRIV flag

Support notifications

Extend simple.rs example to implement new features in 0.6

Support splice()

add FUSE_CACHE_SYMLINKS

Support max_read mount parameter

Support FUSE_READDIRPLUS

Make max_readahead configurable

Setup Clippy and other build tools

Request: explain motivation and goals for fuser compared to other rust FUSE libs (e.g. fuse-rs)

I'm looking at Rust FUSE libs for a distributed filesystem and am looking at fuse-rs and polyfuse, and possibly fuser. I see fuse-rs is popular has little recent activity and that fuser is very new.

Without looking deeply they seem similar, are there reasons to choose one or the other at this time, and what do you have in mind for fuser going forward? Oh, and any other low-level FUSE options in Rust I should look at? Thanks.

Fix signed vs unsigned parameters to match libfuse & syscalls

for example fallocate should be signed offsets: https://man7.org/linux/man-pages/man2/fallocate.2.html

Support FUSE_POLL

add reserved space to fuse_init_out

add FUSE_COPY_FILE_RANGE

Support configurable INIT flags