A Practical Guide to rustfs: Understanding, Installing, and Benchmarking a Rust-based Filesystem Library

This guide provides a practical overview of rustfs, a Rust-based user-space filesystem library designed to be mounted via FUSE on Linux and macOS. It allows developers to create custom filesystems without needing to write kernel modules, offering a safer and more accessible approach to filesystem development.

What rustfs Is and Why It Matters

Definition: rustfs is a Rust-based user-space filesystem library that can be mounted via FUSE (Filesystem in Userspace) on Linux and macOS. It enables the creation of custom filesystems without the need for kernel modules.

Core Architecture: It features a trait-based API with essential filesystem operations such as getattr, readdir, read, write, mkdir, and unlink. It supports asynchronous I/O and, where feasible, zero-copy reads for enhanced performance.

Common Use-Cases:

• In-memory caches
• Virtualized data stores
• Data federation
• Rapid prototyping of domain-specific filesystems

Installation Prerequisites: A working Rust toolchain (rustup + cargo) is required. On Linux, you’ll need libfuse-dev; on macOS, macFUSE; and on Windows, WinFSP. Ensure you have the necessary mounting privileges.

E-E-A-T Context: The project emphasizes verifiable code, reproducible benchmarks, and direct references to official rustfs documentation to build trust. There are no explicit third-party signals mentioned.

Getting Started: Understanding API, Architecture, and a Minimal Code Skeleton

Understanding the rustfs API and Core Types

Understanding the rustfs API and core types is your fast track to building a practical, fast, user-space filesystem in Rust. This section breaks down the essential core types and how they come together to map POSIX calls to your logic.

The Core API: The Filesystem Trait

The heart of rustfs is the Filesystem trait. You implement its lifecycle and filesystem operations to define how your filesystem behaves. The core methods you’ll implement include:

• init: Called when the filesystem is mounted to perform one-time setup.
• destroy: Cleanup when the filesystem is unmounted.
• getattr: Retrieve attributes (stat-like data) for a path.
• readdir: List directory contents.
• read: Read file data at a given offset.
• write: Write data to a file at a given offset.
• create: Create a new file within a directory.
• unlink: Remove a file.
• mkdir: Create a directory.
• rmdir: Remove a directory.
• rename: Move or rename a file or directory.

In your code, you implement these methods to express the exact filesystem logic you want to expose to user-space applications.

Abstractions: Context, Inode, and DirEntry

Rustfs introduces a few key abstractions to simplify core tasks like path resolution, permission checks, and directory listings. These abstractions also enable metadata caching and faster lookups as your filesystem grows in complexity.

Error Handling and errno Mapping

All filesystem operations return a Result<T, rustfs::Error>. When the user-space FUSE layer translates these errors, rustfs maps them to standard errno values so familiar tools (ls, cat, etc.) receive predictable feedback.

Common variants and their typical errno mappings:

Conceptually, you write your Rust code to return rustfs::Error values where something goes wrong, and rustfs ensures the user-space tools see familiar errno results.

Mounting: How to Bring Your Filesystem to Life

Mounting entry points can be provided by a CLI tool (for example, rustfs-cli) or by using the rustfs library directly from your binary. Common options you’ll encounter during testing include -o allow_other (let all users access the FS) and -o ro (read-only mount for safety during development).

CLI-based Mounting: Use a tooling flow such as:

rustfs-cli mount --mountpoint /mnt/rustfs --fs MyFs --allow_other

(plus any -o options you need).

Library-based Mounting: Build a small binary that constructs your filesystem instance and mounts it directly from code, with options to toggle permissions and caching behavior. Typical steps involve creating your filesystem struct (e.g., MyFs), implementing the Filesystem trait for it, and then calling into the FUSE mounting API with your mountpoint and options.

Minimal Working Skeleton: A Practical Starting Point

Follow this lightweight path to a runnable, in-memory filesystem that you can test with basic commands like ls and cat.

1. Create a Rust project: cargo new rustfs_demo
2. Define a simple filesystem: Create a struct, say MyFs, and implement the Filesystem trait for it, perhaps using a HashMap to represent a simple in-memory directory tree.
3. Mount for testing: Use either a CLI helper or embed the library:
   • CLI approach: rustfs-cli mount --mountpoint /mnt/rustfs --fs MyFs --allow_other
   • Library approach: Instantiate your MyFs struct, then call the FUSE mount routine with options like allow_other or ro.
4. Verify basic operations: Mount to /mnt/rustfs, then run:
   • ls -la /mnt/rustfs to see the directory listing.
   • cat /mnt/rustfs/hello.txt to read a file.
5. Iterate: Enhance your in-memory tree, add more test paths, and observe that getattr, readdir, read, and write behaviors align with the core API.

With these core types and patterns in place, you’re ready to evolve a tiny, real filesystem that demonstrates fast path resolution, clear permission checks, and resilient error handling—all while keeping your Rust code clean and testable.

Installing rustfs Across Platforms: Linux, macOS, and Windows

sudo apt-get update
sudo apt-get install libfuse3-dev
cargo add rustfs
cargo build --release
sudo ./target/release/rustfs --mount /mnt/rustfs --data ./data

brew install macfuse
cargo add rustfs
cargo build --release
sudo ./target/release/rustfs --mount /Volumes/rustfs --data ./data

cargo add rustfs
cargo build --release
rustfs-cli --mount C:\mount\rustfs --data C:\data

Benchmarking rustfs: A Practical Methodology

Benchmark Plan

The benchmark plan includes micro-benchmarks using fio for I/O patterns (sequential and random) with criteria such as IOPS, throughput (MB/s), and latency (ms) across workloads: 128 KiB sequential reads/writes, 4 KiB random reads/writes, and metadata-heavy operations.

A baseline comparison against a traditional libfuse-based filesystem and a simple in-memory FS is planned to establish relative performance under identical hardware and mount options.

Reproducibility: The plan emphasizes pinning the rustfs version in Cargo.lock, documenting OS and kernel versions, libfuse version, and hardware specs. A GitHub Actions workflow is suggested for automated benchmarks on Linux runners.

Notes on Tradeoffs

Rustfs offers memory safety, a clean API, and modularity. However, users might observe context-switch overhead in extremely latency-sensitive workloads compared to kernel-level implementations.