Table of Contents

MergerFS - Combine multiple hard drives into a single mountpoint

Objective

To have all media held across various disks under a single mountpoint. 

/srv/media
  |- movies
  |- music
  |- photos
  |- tv

NOTE: /srv/media is the unified mount point.

Download MergerFS

Get the latest release from the MergerFS GitHub page. 

wget https://github.com/trapexit/mergerfs/releases/download/2.40.2/mergerfs_2.40.2.debian-bookworm_amd64.deb

NOTE: It is preferred to use the GitHub version, rather than from APT repository, as the APT one may not be the most up-to-date version.

  • If the APT repository were to be used, install it via: 
    sudo apt install mergerfs

Install MergerFS

dpkg -i mergerfs_2.40.2.debian-bookworm_amd64.deb

Try to Manually Mount

Mount the individual disks to be included into mergerfs

sudo mkdir /mnt/disk01
sudo mkdir /mnt/disk02
sudo mkdir /mnt/disk03
 
sudo mount /dev/sdb1 /mnt/disk01
sudo mount /dev/sdc1 /mnt/disk02
sudo mount /dev/sdd1 /mnt/disk03

NOTE: These locations and devices are just examples.

  • Use the actual devices in the system.

Mount mergerfs from the individual mounted disks

sudo mergerfs -o defaults,allow_other,use_ino,category.create=mfs,moveonenospc=true /mnt/disk01:/mnt/disk02:/mnt/disk03 /mnt/media

NOTE: The mount point for mergerfs, in this example, is /mnt/media.

  • If after mounting, there are problems with the permissions,
    • Set user_allow_other in /etc/fuse.conf

Try to Access the Mount

cd /mnt
/mnt$ ls -l  
ls: cannot access 'virt': No such file or directory  
total 0  
d????????? ? ? ? ?            ? virt

NOTE: If after mounting, there are problems with the permissions:

  • Set user_allow_other in /etc/fuse.conf

Configure fstab

Edit /etc/fstab.

/etc/fstab
...
UUID=b8548ed6-a3e9-44b2-845c-648892491c2d   /mnt/disk01   ext4    errors=remount-ro   0   0
UUID=c09544b8-0dc3-4532-a1c7-31fd63c8c97e   /mnt/disk02   ext4    errors=remount-ro   0   0
UUID=347f34a3-b4b1-47c9-bec9-3ea0c4aa3715   /mnt/disk03   ext4    errors=remount-ro   0   0
/mnt/disk* /mnt/media fuse.mergerfs defaults,allow_other,nonempty,moveonenospc=true,dropcacheonclose=true,category.create=epmfs,fsname=mergerfs 0 0
 
# Another way.
#/mnt/disk01:/mnt/disk02:/mnt/disk03 /mnt/media fuse.mergerfs defaults,allow_other,nonempty,moveonenospc=true,dropcacheonclose=true,category.create=epmfs,fsname=mergerfs 0 0
 
#OLD /mnt/disk* /mnt/media fuse.mergerfs defaults,allow_other,nonempty,use_ino,moveonenospc=true,dropcacheonclose=true,category.create=mspmfs,fsname=mergerfs 0 0

NOTE: It is recommended to have the mount points for each drive to be /mnt/disk01, /mnt/disk02, and /mnt/disk03, and so on.

  • This way by using /mnt/disk* for the new mergerfs entry in fstab, it will pick up all the drives and any future ones added that uses the same naming scheme.
  • The new unified single mount point will be in /mnt/media.
  • To get the UUID values for the disks, use 
    lsblk -d -o NAME,PATH,SIZE,SERIAL,UUID,LABEL

NOTE: The options used against the bottom line shown in the config are:

  • defaults: Use default options.
    • The default depends on the kernel and the filesystem.
  • allow_other: To make the drive available to regular users.
  • nonempty: Mount the filesystem on to an existing (non-empty) directory.
  • moveonenospc=true: If a write fails with ENOSPC (no space left on device) or EDQUOT (disk quota exceeded) the policy selected will run to find a new location for the file.
    • An attempt to move the file to that branch will occur (keeping all metadata possible) and if successful the original is unlinked and the write retried. (default: pfrd).
  • dropcacheonclose=true: When a file is requested to be closed call posix_fadvise on it first to instruct the kernel that we no longer need the data and it can drop its cache.
    • Recommended when cache.files=partial|full|auto-full|per-process to limit double caching. (default: false).
  • category.create=epmfs: Existing path, most free space.
    • OLD category.create=mspmfs: Most shared path, most free space.
  • fsname=mergerfs:

Obsolete option:

  • use_ino: Causes mergerfs to supply file/directory inodes rather than libfuse.
    • While not a default it is recommended it be enabled so that linked files share the same inode value.
    • Effectively replaced with inodecalc.
      • inodecalc=passthrough|path-hash|devino-hash|hybrid-hash: Selects the inode calculation algorithm. (default: hybrid-hash).

See https://trapexit.github.io/mergerfs/config/options/#types

See https://trapexit.github.io/mergerfs/config/functions_categories_policies/

Create the new mount points

sudo umount /mnt/media1 /mnt/media2 /mnt/media3
mkdir /srv/media

Reboot

sudo reboot

NOTE: The fstab config should take effect and mount the drives to the new mount point.

Check

Check if everything shows up: 

ls /mnt/media

returns: 

movies  music  photos  tvshows

NOTE: The unified mount point should show all the data.

  • This example assumes the original disks included into the mergerfs had those directories or files that are returned.

References

https://github.com/trapexit/mergerfs

https://github.com/trapexit/mergerfs/blob/2.40.2/README.md

https://www.man7.org/linux/man-pages/man5/fstab.5.html

https://perfectmediaserver.com/02-tech-stack/mergerfs/