How to Improve mergerfs Storage Reliability
During my journey using Jellyfin with mergerfs and removable USB drives, I found that a missing or disconnected disk can cause unexpected behavior during startup or when the pool is mounted, which can be annoying.
In my setup, the physical disks use different filesystems:
:::code usbdisk01 = NTFS usbdisk02 = exFAT :::The following configuration makes mergerfs more tolerant when one of these storage disks is temporarily unavailable.
1. Improve the mergerfs Mount Configuration
My original mergerfs configuration was:
:::code /mnt/hdd/usbdisk* /mnt/media mergerfs defaults,allow_other,cache.files=off,category.create=pfrd,func.getattr=newest,dropcacheonclose=false,minfreespace=500M,fsname=jellyfin-media 0 0 :::Replace it with:
:::code /mnt/hdd/usbdisk* /mnt/media mergerfs defaults,allow_other,cache.files=off,category.create=pfrd,func.getattr=newest,dropcacheonclose=false,minfreespace=500M,branches-mount-timeout=5,branches-mount-timeout-fail=false,x-systemd.mount-timeout=10s,fsname=jellyfin-media 0 0 :::The important additions are:
:::code branches-mount-timeout=5 branches-mount-timeout-fail=false x-systemd.mount-timeout=10s :::branches-mount-timeout=5 gives the physical disks up to five seconds to become available when mergerfs starts.
branches-mount-timeout-fail=false prevents the entire mergerfs pool from failing just because one branch is unavailable after the timeout.
x-systemd.mount-timeout=10s gives systemd more time than mergerfs itself, preventing systemd from terminating the mergerfs mount process while it is still waiting for the physical disks.
2. Mark the Physical Disk Mount Points
Because usbdisk01 uses NTFS and usbdisk02 uses exFAT, I use a mergerfs marker file instead of extended attributes.
The marker must be created on the underlying Proxmox mount directories, not inside the NTFS or exFAT filesystems.
First, stop the Jellyfin LXC and unmount the mergerfs pool:
:::code pct stop 101 umount /mnt/media :::Then unmount both physical USB disks:
:::code umount /mnt/hdd/usbdisk01 umount /mnt/hdd/usbdisk02 :::Verify that the physical disks are no longer mounted:
:::code findmnt /mnt/hdd/usbdisk01 findmnt /mnt/hdd/usbdisk02 :::If both commands return no output, create the mergerfs marker files:
:::code touch /mnt/hdd/usbdisk01/.mergerfs.branch_mounts_here touch /mnt/hdd/usbdisk02/.mergerfs.branch_mounts_here :::The marker tells mergerfs that these directories are supposed to contain mounted filesystems and should not be treated as normal storage branches when a USB disk is missing.
Verify the marker files:
:::code ls -la /mnt/hdd/usbdisk01 ls -la /mnt/hdd/usbdisk02 :::You should see:
:::code .mergerfs.branch_mounts_here :::Now mount the physical disks again:
:::code mount /mnt/hdd/usbdisk01 mount /mnt/hdd/usbdisk02 :::Once the NTFS and exFAT disks are mounted, the underlying marker files are hidden by the mounted filesystems. This is expected.
3. Apply the New Configuration
Reload systemd and mount the mergerfs pool:
:::code systemctl daemon-reload mount /mnt/media :::Verify the physical disks and mergerfs pool:
:::code findmnt /mnt/hdd/usbdisk01 findmnt /mnt/hdd/usbdisk02 findmnt /mnt/media ls -lah /mnt/media :::Start the Jellyfin LXC again:
:::code pct start 101 :::Jellyfin can continue using exactly the same library paths:
:::code /media/movies /media/music /media/series :::Before and After
:::code BEFORE usbdisk01 - NTFS ─┐ usbdisk02 - exFAT ├── mergerfs → /mnt/media │ Missing USB disk ─┘ │ └── Empty mountpoint may still exist AFTER usbdisk01 - NTFS ─┐ usbdisk02 - exFAT ├── mergerfs → /mnt/media │ Missing USB disk ─┘ │ └── mergerfs checks the branch mount status → waits up to 5 seconds → missing branch does not fail the whole pool → underlying mountpoint is identified by marker :::Why Use .mergerfs.branch_mounts_here?
mergerfs works with directory paths, so an empty directory such as /mnt/hdd/usbdisk02 still exists even when the actual USB disk is disconnected.
The marker file:
:::code .mergerfs.branch_mounts_here :::tells mergerfs that the directory itself is only a mountpoint and that another filesystem is expected to be mounted there.
This is particularly useful with removable storage because mergerfs can distinguish between an actual mounted USB filesystem and the empty underlying directory on the Proxmox host.
Important Note About USB Disconnects
This configuration mainly improves mergerfs behavior when a disk is missing during startup or when the mergerfs pool is mounted.
It does not make sudden USB removal completely safe. If Jellyfin is actively reading a movie, TV episode, or music file from a disk that is physically disconnected, that playback session can still fail or generate an I/O error.
Whenever possible, stop access to the disk and unmount it before physically disconnecting the USB drive.
When the disk is connected again and mounted back to the same path, such as /mnt/hdd/usbdisk02, mergerfs can use the branch again without changing the Jellyfin library paths.
Final /etc/fstab Example
My final configuration uses an NTFS filesystem for usbdisk01 and an exFAT filesystem for usbdisk02:
Conclusion
Adding a short branch timeout, allowing mergerfs to continue when a disk is unavailable, and marking the underlying physical disk mount points makes a Jellyfin mergerfs pool more tolerant of removable USB storage.
For this setup, usbdisk01 uses NTFS and usbdisk02 uses exFAT. Using the .mergerfs.branch_mounts_here marker file avoids relying on extended attributes on those removable filesystems.
The Jellyfin library configuration does not need to change because the combined storage remains available through /mnt/media on Proxmox and /media inside the Jellyfin LXC.
:::toc enable
Post a Comment for "How to Improve mergerfs Storage Reliability"
Post a Comment