Balerion

A minimal Linux file system sentinel written in Rust using inotify.

Overview

Balerion is a lightweight file watcher that listens to file system events directly from the Linux kernel. It monitors directories, detects file changes, tracks content modifications using hashing, and handles rename operations by correlating kernel events.

The goal of this project is to understand how Linux exposes file system activity to user space and how systems react to those events in practice.

Features

• Watches directories using Linux inotify
• Dynamically tracks newly created subdirectories
• Detects file creation, modification, and deletion
• Tracks content changes using hashing
• Handles rename operations using event correlation
• Maintains internal state of files for accurate change detection

How it works

The system follows a simple pipeline:

Filesystem change
    ↓
Linux kernel (inotify)
    ↓
File descriptor (event queue)
    ↓
Raw bytes (inotify_event)
    ↓
Unsafe Rust parsing
    ↓
Event handling and state tracking

Balerion reads raw event data from the kernel, interprets it as C structs, and processes each event to determine what changed.

Key concepts

This project touches several low level concepts:

• File descriptors as kernel interfaces
• inotify event system
• Unsafe Rust for interacting with C memory
• Parsing structured data from raw byte buffers
• Event driven system design
• Content hashing for change detection
• Rename handling using cookies
• Dynamic recursive directory watching

Example output

New file: ./a.txt
Content changed: ./a.txt
Renamed: ./a.txt -> ./b.txt
Deleted: ./b.txt
Watching new directory: ./dir
New file: ./dir/x.txt

Running

Clone the repository and run:

cargo run

In another terminal, trigger events:

echo hello > a.txt
mv a.txt b.txt
mkdir dir
touch dir/x.txt
rm dir/x.txt
rmdir dir

Limitations

• Does not scan existing subdirectories on startup
• Uses a polling loop instead of epoll
• Limited handling of edge cases such as rapid file operations
• Does not clean up watches when directories are removed

Future work

• Replace polling with epoll for efficient event handling
• Add initial recursive directory scan
• Improve error handling and robustness
• Support daemon mode

Why this project

This project was built to understand how file system events propagate from the Linux kernel to user space and how real systems react to those events.

It focuses on clarity of implementation rather than completeness.