Mergerfs Union Filesystem on Arch Linux

Arch Linux logo

Mergerfs is a FUSE based union filesystem that allows pooling of mount points or other directories into a single virtual directory. While it does consume significant CPU resources and somewhat limit maximum throughput it works well otherwise and is easy to set up. It still offer sufficient performance for a home server use. It is very similar to other union file systems such as MHDDFS.

 

Install Mergerfs

Install Packer on Arch Linux or install Yaourt on Arch Linux or another package wrapper.

 

Install with packer.

packer -S mergerfs

 

Setup Mergerfs Mount Points

Mount Filesystem Partitions in Arch Linux

 

Create a directory that will be used as a mount point for the virtual pool.

sudo mkdir /mnt/merger

 

In the case where mergerfs fails to mount at boot time or gets unmounted for any reason the mount point is still accessible. This means that any application will still see a volume but instead of the pooled volume it will be a directory on the underlying file system. This means that data can be written to this directory potentially filling the system drive. This unwanted behaviour can be prevented by allowing only root access and setting the immutable attribute on the mount point.

 

Set the mount point ownership to root user and group.

sudo chown root:root /mnt/merger

 

Set the mount point permissions to allow full access to the owner and group.

sudo chmod 770 /mnt/merger

 

Set immutable flag on the mount point to prevent accidental changes to ownership or permissions.

sudo chattr +i /mnt/merger

When set the immutable flag will prevent changing permissions or ownership by anyone including root user. The flag can be removed with -i option as superuser.

 

Mount Mergerfs manually

Mount the volume with desired options.

sudo mergerfs -o defaults,allow_other,direct_io,use_ino,fsname=mergerfs,minfreespace=50G,func.getattr=newest /mnt/disk\* /mnt/merger

The defaults option sets several recommended option at once. To allow access to users other than the one that mounted mergerfs volume use allow_other option. Enabling direct_io disables caching which can improve write speeds at the cost of read speed reduction. It is also generally recommended to enable use_ino option so that hard linked files share the same inode value. By default the name of the volume will appear as a list of source paths concatenated together with longest common prefix removed, to change this to something more readable fsname option is used.

Optionally set a minimum limit to prevent a physical hard drive from filling up beyond a certain point. Minimum limit value can be specified in megabytes M, kilobytes K or gigabytes with minfreespace option. If omitted the the default value of 4G will be used. This means the limit can be set to a very low value to spread data on all drives. If you want directories to fill up before moving on to the next drive the default of 4GB is sufficient to prevent severe performance loss. For optimal performance it’s a good idea to leave 5% to 10% of the storage device free.

Kodi, Plex, Subsonic and other applications can use modified date attribute to speed up scanning. This attribute can be inconsistent on a mergerfs volume. This can be worked around in at least some of the applications. A catch all fix is to use funct.getattr=newest option which will show the directory with the most recent mdate attribute. Note that this option can cause drives to spin up more often.

 

Mount Mergerfs with fstab

Open the file systems table file.

sudo nano /etc/fstab

 

Add the mount command at the end of the file.

/mnt/disk* /mnt/merger fuse.mergerfs defaults,allow_other,direct_io,use_ino,fsname=mergerfs,minfreespace=50G,func.getattr=newest 0 0

 

Mount the fstab entry.

sudo mount /mnt/merger

Optionally all entries in can be mounted with -a option instead of the specific mount.

 

Mount Mergerfs with Systemd

The advantage of mounting with systemd service is that it is much easier to remember systemd start command than it is to remember the full mhddfs mount command. It is also a good practice to mount mergerfs after physical disks in fstab have been mounted. Mergerfs package does not come with a systemd script by default so a custom script needs to be created.

 

Create the mount script.

sudo nano /etc/systemd/system/mnt-merger.mount

Note that the name of the systemd mount file has to match the Where =   field. Slashes ( / ) in the path are replaced by dashes ( ). So /mnt/merger becomes mnt-merger. Non matching name will result in a failed start of the script with error “Where= setting doesn’t match unit name. Refusing.“.

 

Copy the script and save.

 

[Unit]
Description = Mount mergerfs volume
Requires = mnt-disk1.mount
Requires = mnt-disk2.mount
Requires = mnt-disk3.mount
Requires = mnt-disk4.mount
Requires = mnt-disk5.mount
Requires = mnt-disk6.mount
Requires = mnt-disk7.mount
Requires = mnt-disk8.mount

After = mnt-disk1.mount
After = mnt-disk2.mount
After = mnt-diks3.mount
After = mnt-diks4.mount
After = mnt-diks5.mount
After = mnt-diks6.mount
After = mnt-diks7.mount
After = mnt-diks8.mount
After = mnt-diks9.mount
After = mnt-diks10.mount

[Mount]
What = /mnt/disk*
Where = /mnt/merger
Type = fuse.mergerfs
Options = defaults,allow_other,direct_io,use_ino,fsname=mergerfs,minfreespace=50G,func.getattr=newest

[Install]
WantedBy = multi-user.target

 

Start the service.

sudo systemctl start mnt-merger.mount

 

Enable the service to run on boot.

sudo systemctl enable mnt-merger.mount

dom