Adding Mergerfs To Your Synology

(Psssst…. TLDR?… fast forward to “The Implementation” below)

What is it?

mergerfs is a union filesystem geared towards simplifying storage and management of files across numerous commodity storage devices. It is similar to mhddfsunionfs, and aufs.

Why would you do it?

Adding Mergerfs to your Synology could benefit you when you have multiple volumes with “the same type” data and you would like to have it accessed as a single mount point. For example on my Synology I have a SHR2 volume with 4 x 3TB disks summing up to 9TB (volume1) but I also have 1 single disk of 6TB (volume2) which I couldn’t (and didn’t want to) fit in volume1.

I have a DSM shared directory with some homevideos on volume1 (/video) and another directory with some more video on volume2 (/video2). I don’t want them all on volume1, so them divided in two shared directories. But I do want to them the be presented as one logical share to the outside world. Here Mergerfs comes in handy.

I would like to have /video and /video2 to be merged into a new logical shared folder called /videom (for example). The way Mergerfs does this is merging the two directory into one logical directory.

Why this page?

There is a clear wiki page explaining all this. But that setup comes with some issues (dated: 01-01-2022). 99% of the info is the way to go. In December 2021 I started to explore Mergerfs for my Synology. So I checked the wiki page from Mergerfs and I like the fact that I got an extra package manager (which is not maintained by the coder of mergerfs) with all the stuff Synology misses out on. But There are some problems.

The first problem is though that this package manager comes with a self-build version of Mergerfs that is not directly supported by Trapexit/Antonio (By the way Support Antonio if you can. His work is excellent on Mergerfs. I did support him too.). This version is at the moment: merge-with-ng-1131-gfe90b72b. Antiono helped me till the bitter end trying to get all of the below fixed, but he has no Synology and could not test much himself. So I was on my own. But I appreciated his help and efforts!!

The second problem is that the mergerfs mount command in the wiki mounts directly on the mointpoint of a shared directory made in DSM. This makes sense because you want the merged directories out in the world and it works on the first few looks of it, but when you start using it you soon run in more problems than you like. To name a few:

  1. The DSM reports that you are missing ACL on your shared directory after mergerfs mounts.
  2. When you would like to rename a file on the merged mount point, it does so with an error in the end.
  3. Hyperbackup will forever fail because it can’t read parts of the DSM config anymore (it seems Mergerfs fiddled with something on the share unintended)
  4. DSM also has a safety backup for the config, which backups to your Synology Account. This will fail too.

These are a few things I ran into in the first few days with the setup in the wiki. I started leaving Hyperback alone and started using Restic in a project I run on here and with a docker-image here. Did not like to be vendor locked by Synology on my backups anymore. But that’s out of scope for this blogpost. But the other stuff still was a problem.

The solution

After some sessions with Antiono to get issues fixes he couldn’t help me. 1. Mergerfs performed well on his systems. 2. The Synology was not the problem in itself either. What I understand from Antonio was that Synology made some custom implementations on they solution which would not be compatible with Mergerfs.

What I discovered was that mounting the merged directory not on a DSM shared directory but for instance on a mount point in /mnt like /mnt/videom would not have problems at all. But this mount point was not shared with the world and that was the whole point.

So I first tried to symlink this /mnt/videom to /volume1 which worked but I could not create the shared directory anymore and visa versa when I created the shared folder first I couldn’t symlink anymore. For the obvious reasons.

Then secondly I trying to mount mergerfs on a mount point within the shared directory. This worked, all the earlier problems were gone but Mergerfs only reports the maximum free disk space of the first branch, so I missed “half” the free disk space I would like to have.

The third try I used a mount -o bind on the directory in /mnt/videom and /volume1/videom, this was the Eureka moment! This fixed all problems but one. “The DSM reports that you are missing ACL on your shared directory after mergerfs mounts.” This is not a big problem since you set all config when creating the shared directory and not need to edit it anymore. But If you do, you can umount Mergerfs and edit it again. After that mounting Mergerfs again. I have understood that Synology has it’s own ACL implementation and Mergerfs is not compatible.

To get rid of the “unsupported” Mergerfs version from “Entware” I just got the correct version for my Synology from the releases page on GitHub. I guess this narrows down to the following builds for version 2.33.3 (date: 01-01-2022) but by the time you read this, the versions could have changed. I have a Synology DS1513+ with DSM 7.0. The DS1513+ has a Intel Atom processor. So I need to choose the “amd64” version from the pack. By the way, The custom build version from the Entware package manager works just fine, but when you get on the GitHub page and start issuing questions I know Antiono will tell you are not using an official release.

So for me all was fixed and I could happily use Mergerfs.

The implementation

SSH into you Synology box. And enter 'sudo su‘ to be superman for awhile. Be careful now you could mess up stuff in superuser mode.

  1. Create the directory where Entware will be installed. As said I like Entware as a package manager as it gives fast access to a lot of tool. I reckon you could get this to work without Entware, but I have not tried.
mkdir -p /volume1/@Entware/opt

2. Make sure we start fresh with an empty /opt directory. So remove it, recreate /opt and bind mount the this Entware

rm -rf /opt
mkdir /opt
mount -o bind "/volume1/@Entware/opt" /opt

3. Run install script depending on the processor. Use command ‘uname -m’ to find out. Then run the corresponding command.

armv8 (aarch64) – Realtek RTD129x

wget -O - http://bin.entware.net/aarch64-k3.10/installer/generic.sh | /bin/sh

armv5

wget -O - http://bin.entware.net/armv5sf-k3.2/installer/generic.sh | /bin/sh

armv7

wget -O - http://bin.entware.net/armv7sf-k3.2/installer/generic.sh | /bin/sh

x64

wget -O - http://bin.entware.net/x64-k3.2/installer/generic.sh | /bin/sh

4. Create the following scripts (init_entware.sh and init_mergerfs.sh) at a location of your liking.

init_entware.sh

#!/bin/sh

echo "*** Init Entware ***"

# Mount/Start Entware
mkdir -p /opt
mount -o bind "/volume1/@Entware/opt" /opt
/opt/etc/init.d/rc.unslung start

# Add Entware Profile in Global Profile
if grep  -qF  '/opt/etc/profile' /etc/profile; then
	echo "Confirmed: Entware Profile in Global Profile"
else
	echo "Adding: Entware Profile in Global Profile"
cat >> /etc/profile <<"EOF"

# Load Entware Profile
. /opt/etc/profile
EOF
fi

# Update Entware List
/opt/bin/opkg update

init_mergerfs.sh

#!/bin/sh

echo "*** Init Mergerfs ***"

# Check and create mountpoint in /mnt 
if [ ! -d "/mnt/videom" ]; then
    mkdir -p /mnt/videom/
fi

# Mount --bind the two directories
mount -o bind /mnt/videom/ /volume1/videom/

# Start Mergerfs
modprobe fuse
/opt/bin/mergerfs -o nonempty,rw,use_ino,allow_other,func.getattr=newest,category.action=all,category.create=mfs,dropcacheonclose=true /volume1/video:/volume2/video2 /mnt/videom

Notes:

  • /mnt/videom is the mount point you need for Mergerfs; Set this to for likings.
  • /volume1/videom is the shared directory you need to create in DSM and this will get you out in the world
  • /volume1/video:/volume2/video2 are the branches you will to be merged. To my understand you can have more than two.
  • category.create=mfs is set to mfs, because I like the branches to be evenly filled. see here for more information
  • I use the nonempty option because I don’t want the Synology controle files (.DStore and @eaDir) to get in the way.
  • I added ‘modprobe fuse' before mergerfs so it mounts correctly
  • And of course the BIND Mount between /mnt/videom and /volume1/videom

5. Create One Autostart Task On Synology to init Entware

Notes: Edit the Run Command to reflex your setup on your Synology.

Create a triggered user-defined task in Task Scheduler.

Go to: DSM > Control Panel > Task Scheduler
Create > Triggered Task > User Defined Script
General
Task: Entware
User: root
Event: Boot-up
Pretask: none
Task Settings
Run Command: /volume1/beheer/scripts/entware/init_entware.sh

Notes: If you like (optional) you can set your logging directiory in the settings of the task manager.

6. Reboot your NAS

7. SSH back into your nas and ‘sudo su‘, enter in your password. Then run the following command.

opkg update

8. Install Mergerfs

opkg install mergerfs

9. Make sure it is installed

ls /volume1/@Entware/opt/sbin

10. Download and installed the latest version of Mergerfs from the Github releases. At time of this writing the version is 2.33.3. Download the correct file for you Synology system to your MAC or PC, uncompress it and copy the files (mergerfs and mergerfs-fusermount) from the archive in the directory /usr/local/bin to your Synology in /opt/bin (which is mount bind to /volume1/@Entware/opt/bin).

If things work out fine ‘mergerfs --version' will give you the current installed version from the Github releases.

Hint: rename the existing files, so when things don’t work out you can revert.

11. Create another Autostart Task On Synology for the Mergerfs to start when rebooted.

Notes: Edit the Run Command to reflex your setup on your Synology.

Create a triggered user-defined task in Task Scheduler.

Go to: DSM > Control Panel > Task Scheduler
Create > Triggered Task > User Defined Script
General
Task: Mergerfs
User: root
Event: Boot-up
Pretask: Entware
Task Settings
Run Command: /volume1/beheer/scripts/mergerfs/init_mergerfs.sh

12. Reboot your systeem and let the magic from Trapexit be executed!