Skip to content

branches-mount-timeout

  • type: UINT (seconds)
  • default: 0

mergerfs is compatible with any path, whether it be a mount point or a directory on your root filesystem. It doesn’t require branch paths to be mounted or to match a specific filesystem at startup, and it operates effectively without needing details about the intended filesystem. This flexibility eliminates the need to manage mount ordering, which is particularly advantageous on modern systems where filesystems are mounted asynchronously, resulting in unpredictable mount sequences. While systemd offers a way to enforce mount dependencies using the x-systemd.requires=PATH option in /etc/fstab, applying this to every branch path is both cumbersome and susceptible to errors.

branches-mount-timeout will cause mergerfs to first attempt to mount each branch if the branch appears to be on the same filesystem as the mergerfs mount point and then wait for all branches to become "mounted." The logic to determine "mounted" is as follows.

  1. It is mounted if the branch directory has the extended attribute user.mergerfs.branch
  2. It is mounted if the branch directory contains a file named .mergerfs.branch
  3. It is not mounted if the branch directory has the extended attribute user.mergerfs.branch_mounts_here
  4. It is not mounted if the branch directory contains a file named .mergerfs.branch_mounts_here
  5. It is mounted if the st_dev value of the mergerfs mount point is different from the branch path.

These files and xattrs are used to help mergerfs know whether or not a directory happens to be a branch or is the underlying directory mount point.

Paths which appear after startup

The branches resolution process runs before this option starts waiting. A missing literal path is retained as a branch, so a configuration such as /mnt/hdd/disk0/foobar can work when /mnt/hdd/disk0 is mounted asynchronously and foobar only becomes visible afterward, provided the path then meets one of the "mounted" conditions above.

For each branch which is not ready, mergerfs first runs mount once with the full branch path as the target and then polls that same path until the timeout expires. It does not create the path, try to mount its parent, or rerun mount. In the example above, the initial mount /mnt/hdd/disk0/foobar may fail while the path is absent. If another service mounts /mnt/hdd/disk0 and /mnt/hdd/disk0/foobar appears and meets one of the "mounted" conditions before the deadline, mergerfs detects it during polling and continues.

Globs are different. If /mnt/hdd/disk0/* has no matches during branch resolution, the literal path /mnt/hdd/disk0/* is retained. The mount wait does not expand it again after /mnt/hdd/disk0 becomes available. Ensure the parent filesystem is mounted before mergerfs, configure a literal branch path, or update branches through the runtime API once the paths exist.

NOTE: If on a systemd based system and using fstab it is a good idea to set the mount option x-systemd.mount-timeout to some value longer than branches-mount-timeout otherwise systemd might kill mergerfs before it finishes waiting.

NOTE: The way mergerfs attempts to mount the branch is by calling out to the system command mount with the branch as the target. If that path is configured in /etc/fstab as a mount point then mount should attempt to mount it with the settings defined in fstab.

branches-mount-timeout-fail

Default: false

When set to true mergerfs will fail entirely after branches-mount-timeout expires without all branches being mounted. If set to false it will simply ignore the mount status of the branches and continue on. The details will be logged.