FUSE: Filesystem in Userspace Explained

What if You Could Invent Your Own Filesystem?

Imagine you want to create a filesystem where every file is automatically encrypted, or one that transparently fetches data from a cloud service, or even one that shows your database tables as files. Traditionally, this meant writing kernel code—a terrifying prospect involving C, kernel panics, and months of debugging.

FUSE (Filesystem in Userspace) changes everything. It lets you write filesystems as regular programs in Python, Go, Rust, or any language you like. Your code runs safely in userspace, and FUSE handles the kernel communication for you.

The Problem FUSE Solves

Traditional filesystem development is intimidating:

• Dangerous: Kernel bugs crash the entire system
• Complex: Deep understanding of kernel internals required
• Slow iteration: Reboot after every change
• Root required: Can't test as a normal user
• Language locked: Must use C

FUSE eliminates all of these barriers:

• Safe: Crashes only affect your filesystem
• Simple: Implement ~10 functions and you're done
• Fast iteration: Just restart your program
• User-friendly: Run as your normal user
• Language-free: Use Python, Go, Rust, anything!

The Kernel/Userspace Boundary

This is THE key insight to understanding FUSE. Every Unix system has two worlds: kernel space (privileged, dangerous) and userspace (safe, restricted). FUSE bridges them.

How FUSE Works

When your application reads a file on a FUSE mount, here's what happens:

// FUSE filesystem implementation
static int my_read(const char *path, 
                   char *buf, 
                   size_t size, 
                   off_t offset,
                   struct fuse_file_info *fi) {
    // Your logic here
    int fd = open(path, O_RDONLY);
    pread(fd, buf, size, offset);
    close(fd);
    return size;
}

The Request Flow in Detail

1. Application makes a system call (open, read, write)
2. VFS Layer receives the request and routes it
3. FUSE Kernel Module intercepts requests for FUSE mounts
4. Request Queue: The kernel queues the request to /dev/fuse
5. libfuse in userspace reads from the queue
6. Your Filesystem handles the request (this is YOUR code!)
7. Response travels back through the same path

# The key components:
# 1. FUSE kernel module - handles kernel-side communication
lsmod | grep fuse

# 2. /dev/fuse - the bridge between kernel and userspace
ls -l /dev/fuse

# 3. Your FUSE daemon - runs in userspace, handles requests
ps aux | grep myfs

The Performance Trade-off

FUSE isn't free—there's a performance cost for the safety and flexibility it provides. Let's see it in action:

Why FUSE is Slower

Every FUSE operation crosses the kernel/userspace boundary four times:

1. App → Kernel (syscall)
2. Kernel → FUSE daemon (via /dev/fuse)
3. FUSE daemon → Kernel (response)
4. Kernel → App (return)

Compare to native filesystems: only two crossings (syscall in, return out).

Real-World FUSE Filesystems

FUSE powers some of the most useful filesystem tools in the Linux ecosystem:

Building Your Own FUSE Filesystem

Ready to build your own? Here's what you need to implement:

Minimal Example: Hello World Filesystem

Here's a complete, working FUSE filesystem in Python:

#!/usr/bin/env python3
from fuse import FUSE, Operations
import stat
import errno

class HelloFS(Operations):
    def getattr(self, path, fh=None):
        if path == '/':
            return {'st_mode': stat.S_IFDIR | 0o755, 'st_nlink': 2}
        if path == '/hello.txt':
            content = b'Hello from FUSE!\n'
            return {
                'st_mode': stat.S_IFREG | 0o444,
                'st_nlink': 1,
                'st_size': len(content)
            }
        raise OSError(errno.ENOENT)

    def readdir(self, path, fh):
        return ['.', '..', 'hello.txt']

    def open(self, path, flags):
        return 0

    def read(self, path, length, offset, fh):
        if path == '/hello.txt':
            content = b'Hello from FUSE!\n'
            return content[offset:offset + length]
        raise OSError(errno.ENOENT)

if __name__ == '__main__':
    import sys
    FUSE(HelloFS(), sys.argv[1], foreground=True)

Run it:

# Install fusepy
pip install fusepy

# Create mount point and run
mkdir /tmp/hello
python hello_fs.py /tmp/hello

# In another terminal:
ls /tmp/hello          # Shows: hello.txt
cat /tmp/hello/hello.txt  # Shows: Hello from FUSE!

# Unmount when done
fusermount -u /tmp/hello

That's it! ~30 lines of Python and you have a working filesystem.

Performance Optimization

Kernel Caching

FUSE can cache data in the kernel to reduce round-trips:

# Enable kernel page cache (default)
./myfs /mountpoint -o kernel_cache

# Enable attribute caching
./myfs /mountpoint -o attr_timeout=60

# Disable caching for always-fresh data
./myfs /mountpoint -o direct_io

Batch Operations

For better throughput:

# Increase max read/write size
./myfs /mountpoint -o max_read=131072 -o max_write=131072

# Enable multi-threading
./myfs /mountpoint -o max_threads=16

Common Mount Options

# Allow other users to access the mount
mount -o allow_other /dev/fuse /mountpoint

# Set ownership
mount -o uid=1000,gid=1000 ...

# Read-only mount
mount -o ro ...

# Debug mode (foreground with verbose output)
./myfs -f -d /mountpoint

Debugging FUSE Filesystems

Verbose Logging

import logging
logging.basicConfig(level=logging.DEBUG)

def read(self, path, length, offset, fh):
    logging.debug(f"READ: {path}, len={length}, off={offset}")
    # ... implementation

Strace the FUSE Process

# Trace all system calls
strace -p $(pidof myfs) -f

# Just file operations
strace -e open,read,write,close -p $(pidof myfs)

Common Issues

"Transport endpoint is not connected"

# FUSE daemon crashed - unmount and restart
fusermount -u /mountpoint
./myfs /mountpoint

"Permission denied"

# Check /etc/fuse.conf has: user_allow_other
# And mount with: -o allow_other

When to Use FUSE (and When Not To)

The Future of FUSE

FUSE 3.x

The latest FUSE version brings:

• Better performance through improved caching
• Enhanced security model
• Splice support for zero-copy I/O

virtiofs

For virtual machines, virtiofs combines FUSE with virtio for near-native performance:

# Inside a VM, mount host directory
mount -t virtiofs myfs /mnt/host

io_uring Integration

Future versions may use io_uring for:

• Reduced context switches via batching
• Better async I/O performance

Key Takeaways

FUSE democratized filesystem development. Before FUSE, creating a new filesystem meant months of kernel hacking. Now, you can prototype a working filesystem in an afternoon. Whether you're mounting remote servers with SSHFS, accessing Windows drives with NTFS-3G, or building your own specialized filesystem, FUSE provides the bridge between your ideas and the kernel's VFS layer.

Related Concepts