Under the hood

How PolicyFS works

PolicyFS is a FUSE daemon that sits between your apps and physical storage. It routes each filesystem call based on explicit rules. For archive disks marked indexed: true, a local SQLite database serves readdir and getattr calls so the HDD can stay spun down. Three maintenance jobs — pfs move, pfs prune, and pfs index — run on a schedule and handle housekeeping.

Architecture

How pfs handles a filesystem call

1

POSIX syscall

Your application issues a normal POSIX syscall — pfs is transparent to userspace.

2

FUSE dispatch

The kernel forwards the call over FUSE to the pfs daemon.

3

Routing & index

The router matches the path to a rule. For indexed storage, metadata may be served from the index.

4

Physical I/O

File content I/O hits physical storage through pfs, typically via a cached file descriptor.

Indexed storage

How pfs index reduces HDD wakeups

With indexed: true, pfs index scans physical storage and upserts metadata into index.db. readdir and getattr for indexed storage can be served from the database, reducing HDD wakeups. File content I/O still hits the underlying storage. Non-indexed storage paths (indexed: false) are accessed via the filesystem directly (no metadata index).

HDD · indexed: true hdd1 hdd2 hdd3 pfs index periodic · systemd timer scan & upsert index.db SQLite readdir / getattr open/read/write · file content I/O SSD · indexed: false ssd1 ssd2 filesystem I/O · no index pfs daemon metadata reads via index.db data bytes → HDD direct SSD: direct I/O reads & writes no index

Deferred operations

How pfs prune replays deferred operations

On indexed storage, delete/rename/setattr operations are recorded to events.ndjson and reflected in the index without immediately touching the physical disk. pfs prune replays the log and applies pending operations to physical storage, freeing space and making changes persistent.

pfs daemon defer ops events.ndjson event log DELETE RENAME SETATTR reads log pfs prune periodic · systemd timer hdd1 hdd2 hdd3

Tiered storage

How pfs move migrates files

As new files land on SSD storage, the fast tier fills up. pfs move copies eligible files — based on minimum age, size, and disk usage threshold — from the fast tier to destination storage (typically an indexed HDD archive). If the daemon control socket is available, open files are skipped.

SSD · fast tier ssd1 ssd2 pfs move age · size · free space HDD · archive tier hdd1 hdd2 hdd3 queries: skip open files daemon.sock

Limitations

Not a good fit for…

Go deeper in the docs

The deep dive explains routing semantics, indexed storage invariants, and the maintenance cycle in detail.

Read the deep dive → Concepts reference