Unlocking FUSE: Deep Dive into User‑Space Filesystem Architecture and Optimization

Introduction

FUSE (Filesystem in Userspace) allows file systems to run in user space, simplifying development and debugging by avoiding kernel code changes. It is widely used in open‑source file systems such as CephFS, GlusterFS, ZFS, sshfs, and mailfs, and has a Windows counterpart called Dokan.

Environment

All analyses and operations were performed on:

Operating System: CentOS Linux release 7.6.1810 (Core)

Kernel Version: 3.10.0-862.2.3.el7.x86_64

libfuse Version: libcurl-7.29.0-57

FUSE Overview

FUSE enables mounting by ordinary users, with metadata and data operations handled by a user‑space process. It supports multiple programming languages via libfuse bindings (C, C++, Java, Go, Python). The main drawback is performance overhead due to multiple user‑kernel space switches.

Mountable by regular users

Runs in user space

Easy development, debugging, installation, and maintenance

Multi‑platform support

Language bindings for user‑space interface

Performance lower than kernel file systems

Architecture

FUSE consists of three parts:

Kernel module (fuse.ko) : Interacts with VFS, packages system calls into fuse requests and sends them to user space.

User‑space library (libfuse.*) : Communicates with the kernel module, receives requests, and writes back results.

Mount tool (fusermount) : Allows ordinary users to mount and unmount file systems.

Kernel Module Loading

<code># modprobe fuse</code><code># modinfo fuse</code>

The module initialization creates caches, registers the fuse device (/dev/fuse), and sets up sysfs entries for control.

Module Parameters

max_user_bgreq: Maximum number of background requests per unprivileged user.

max_user_congthresh: Threshold for congestion control.

Mount Parameters

fd= : File descriptor for /dev/fuse (required).

rootmode= : Permissions for the root directory (required).

user_id= / group_id= : UID/GID of the user‑space process (required).

default_permissions : Enables kernel‑level permission checks.

allow_other : Allows other users to access the mount point.

max_read=, blksize=, etc.: Various I/O limits.

Mount Process

The mount operation invokes fuse_mount , which allocates a superblock and calls fuse_fill_super to initialize the file system.

FUSE Request Flow

Requests travel through several queues inside the kernel:

pending queue

io queue

processing queue

bg_queue (background requests)

interrupts queue

forget list

Priorities: interrupt queue > forget list > pending queue.

FUSE Control Filesystem

When the kernel module loads, a control filesystem (fusectl) is created. Each channel appears under /sys/fs/fuse/connections/ with files such as abort , congestion_threshold , max_background , and waiting for monitoring and control.

<code># mount -t fusectl none /sys/fs/fuse/connections/</code><code># ll /sys/fs/fuse/connections/</code>

User‑Space Library (libfuse)

libfuse provides two APIs:

low_level : Direct inode operations, offering fine‑grained control.

high_level : Path‑based operations, simpler but less flexible.

Typical workflow:

fuse_mount : Mounts the file system and creates the communication channel.

fuse_lowlevel_new : Registers callbacks and creates a session.

fuse_session_loop_mt : Multi‑threaded request polling and handling.

Practical Example

<code>$ git clone https://github.com/libfuse/libfuse.git</code><code>$ cd libfuse/</code><code>$ git checkout fuse_2_9_2</code><code>$ ./makeconf.sh</code><code>$ ./configure</code><code>$ make</code><code>$ ./example/hello_ll -o fsname=hello,subtype=ll /tmp/fuse/</code>

After mounting, the file /tmp/fuse/hello contains "Hello World!".

Optimization Tips

Increase FUSE_MAX_PAGES_PER_REQ in fs/fuse/fuse_i.h to allow larger I/O requests.

Raise max_write in libfuse (e.g., modify lib/fuse_kern_chan.c ).

Adjust kernel read‑ahead limits via VM_MAX_READAHEAD or sysfs.

Increase entry_timeout and attr_timeout to reduce metadata traffic.

Enable multi‑threaded request handling with fuse_session_loop_mt .

Conclusion

The article analyzed the core principles of the FUSE user‑space file system, explained the roles of kernel and user‑space components, described their interaction, and listed optional optimizations to improve performance and usability.