====== MergerFS - Combine multiple hard drives into a single mountpoint ======

===== Objective =====

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

<code>
/srv/media
  |- movies
  |- music
  |- photos
  |- tv
</code>

<WRAP info>
**NOTE:** **/srv/media** is the unified mount point.

</WRAP>

----

===== Download MergerFS =====

Get the latest release from the MergerFS [[https://github.com/trapexit/mergerfs/releases/latest|GitHub]] page.

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

<WRAP info>
**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: <code bash>
sudo apt install mergerfs
</code>

</WRAP>

----

===== Install MergerFS =====

<code bash>
dpkg -i mergerfs_2.40.2.debian-bookworm_amd64.deb
</code>

----

===== Try to Manually Mount =====

==== Mount the individual disks to be included into mergerfs ====

<code bash>
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
</code>

<WRAP info>
**NOTE:** These locations and devices are just examples.

  * Use the actual devices in the system.

</WRAP>

----

==== Mount mergerfs from the individual mounted disks ====

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

<WRAP info>
**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
</WRAP>

----

===== Try to Access the Mount =====

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

<WRAP info>
**NOTE:**  If after mounting, there are problems with the permissions:

  * Set **user_allow_other** in /etc/fuse.conf
</WRAP>


----

===== Configure fstab =====

Edit /etc/fstab.

<file bash /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

</file>

<WRAP info>
**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 <code bash>lsblk -d -o NAME,PATH,SIZE,SERIAL,UUID,LABEL</code>

</WRAP>


<WRAP info>
**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/


</WRAP>

----

===== Create the new mount points =====

<code bash>
sudo umount /mnt/media1 /mnt/media2 /mnt/media3
mkdir /srv/media
</code>

----

===== Reboot =====

<code bash>
sudo reboot
</code>

<WRAP info>
**NOTE:**  The fstab config should take effect and mount the drives to the new mount point.
</WRAP>

----

===== Check =====

Check if everything shows up:

<code bash>
ls /mnt/media
</code>

returns:

<code>
movies  music  photos  tvshows
</code>

<WRAP info>
**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.
</WRAP>


----

===== 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/