Skip to content

MergerFS

gitsync edited this page Jul 14, 2026 · 1 revision

MergerFS Support is an optional feature that pools multiple datasets or paths into a single union mountpoint — ideal for media libraries spread across several disks or pools, where you want one big folder without the rigidity of a single ZFS pool.

ZNAS uses trapexit/mergerfs, installed automatically from the official GitHub releases for your exact OS and version.

Installing

Go to Requisites → Optional Features and click Install on the MergerFS Support card:

Requisites — Optional Features

Installing MergerFS renames the sidebar item Datasets & Zvol to Datasets & FS and adds a + Other ▾ → Create a MergerFS option to that page.

Creating a union

Create a MergerFS

  1. On Datasets & FS, click + Other ▾ → Create a MergerFS
  2. Give it a name and a mountpoint (must be under /mnt or a pool mountpoint, e.g. /mnt/media)
  3. Add branches — pick datasets from the dropdown or enter any path manually; branches can span different pools
  4. Review the settings (sensible defaults are pre-selected, each with an explanation in the dropdown):
Setting Default Purpose
Create policy mfs (recommended) Where new files go — mfs = most free space, epmfs = existing path first, pfrd = proportional random
minfreespace 50G Skip branches with less free space than this
moveonenospc on Move the file to another branch if a write hits ENOSPC
cache.files off Page-cache behavior (leave off for media workloads)
allow_other on Let non-root users access the mount
inodecalc path-hash Stable inode calculation
nofail on Boot continues even if the union can't mount
  1. If all branches are ZFS datasets, you can also pick a shared ZFS compression applied to every member dataset (lz4 recommended)
  2. Click Create — the union mounts immediately and a systemd mount unit is written so it remounts automatically at reboot, waiting (up to 30 s) for all ZFS pools/datasets to be available first

The union tab

Each MergerFS union appears as its own tab on Datasets & FS:

MergerFS tab

The panel shows a live Mounted status, total capacity bar, and per-branch usage with ZFS dataset badges. Buttons at the top right:

  • File Browser — browse the union content (see File Browser)
  • Snapshots — coordinated ZFS snapshots (below); shown when all branches are ZFS datasets
  • Edit — change runtime-settable options (create policy, minfreespace, moveonenospc, cache.files, branches, shared compression) — applied live to the mounted union and persisted
  • Delete — unmounts and removes the union (branch data is never touched)

Coordinated snapshots (all-ZFS unions)

When every branch is a ZFS dataset, the Snapshots button opens union-wide snapshot management:

MergerFS snapshots

  • Take now — snapshots all member datasets in parallel with one shared timestamp, so the union has a single consistent restore point even across pools
  • Restore — rolls back every member dataset to the chosen point in time (with a clear data-loss warning)
  • Delete — removes the snapshot set from all members
  • Schedule — automatic snapshots every N hours/days/weeks at a chosen time, with a Keep last N retention that prunes old sets on all members

If any branch is not a ZFS dataset, the Snapshots button is hidden and the panel explains why.

Notes

  • The union's mountpoint can be shared over SMB / NFS like any other path
  • MergerFS is a union of existing branches — it adds no redundancy of its own; protect the underlying datasets with normal ZFS redundancy and snapshots
  • Runtime option changes use the mergerfs control interface — no remount, no interruption

Clone this wiki locally