mergerfs does not care about the underlying filesystem type. All policies work exactly as described in the docs in relation to selection algorithm, filtering, response to readonly, etc.

 

If `/boot` is first and doesn't get filtered out for whatever reason as described in the docs... it would be selected by `ff`.

8 minutes ago, trapexit said:

mergerfs does not care about the underlying filesystem type. All policies work exactly as described in the docs in relation to selection algorithm, filtering, response to readonly, etc.

 

If `/boot` is first and doesn't get filtered out for whatever reason as described in the docs... it would be selected by `ff`.

 

Thanks for chiming in, indeed it's probably best to check out again the documentation here and play around with it some more: https://trapexit.github.io/mergerfs/. Many thanks for providing the new website and even more detailed documentation alongside the software. For what it's worth, many of our power users had great success implementing mergerFS into their storage setups on UNRAID and I've heard a lot of positive feedback. 🙂 

 

For anyone who wishes to see exactly what mergerfs is doing here... https://github.com/trapexit/mergerfs/blob/latest-release/src/policy_epff.cpp#L108

 

You don't need to be a developer to understand this is extremely trivial. 

 

@Rysz Glad it is useful. And thank you for building and maintaining this plugin.

36 minutes ago, Rysz said:

But, why do you even want to pool /boot in the first place? It seems odd to use the USB flash drive, which Unraid loads the OS into RAM from, for media consumption? If it's for intermediate, fast-access (cached) files why not a ramdisk or otherwise better suited storage like SSD/NVMe?

 

 

45 minutes ago, alturismo said:

just made a quick & dirty test run today morning

 

because it was just a quick & dirty test IF it works like expected, dont care about it, no intention to use /boot at all, all good and funtional as expected, im fine ...

may another general question

 

messages in syslog, just information when i read the docs ?

 

Jan 25 20:50:42 AlsServerII mergerfs[947693]: running basic garbage collection
Jan 25 20:56:29 AlsServerII mergerfs[590046]: running basic garbage collection
Jan 25 20:58:54 AlsServerII mergerfs[595830]: running basic garbage collection
Jan 25 21:00:06 AlsServerII mergerfs[2630418]: running basic garbage collection
Jan 25 21:00:38 AlsServerII mergerfs[2631845]: running basic garbage collection
Jan 25 21:05:42 AlsServerII mergerfs[947693]: running basic garbage collection

 

https://trapexit.github.io/mergerfs/runtime_interfaces/#ioctl

17 minutes ago, alturismo said:

may another general question

 

messages in syslog, just information when i read the docs ?

 

Jan 25 20:50:42 AlsServerII mergerfs[947693]: running basic garbage collection
Jan 25 20:56:29 AlsServerII mergerfs[590046]: running basic garbage collection
Jan 25 20:58:54 AlsServerII mergerfs[595830]: running basic garbage collection
Jan 25 21:00:06 AlsServerII mergerfs[2630418]: running basic garbage collection
Jan 25 21:00:38 AlsServerII mergerfs[2631845]: running basic garbage collection
Jan 25 21:05:42 AlsServerII mergerfs[947693]: running basic garbage collection

 

https://trapexit.github.io/mergerfs/runtime_interfaces/#ioctl

 

It's normal, just informative that simple garbage collection is occurring. 

I've updated the version to the latest release: https://github.com/trapexit/mergerfs/releases/tag/2.41.0

Please ideally unmount all pools before updating and read carefully the changelog linked above.

On 9/12/2023 at 8:02 AM, Admin9705 said:

 

MergerFS is super useful. I wrote plexguide in utilizing unionfs/mergerfs. There is one warning I do have and maybe you're well ahead of this one. There are rare times mergerfs can fail and I mean super rare. Also, other locations if they go offline, it can cause problems.

 

I had to write a script in the program to shutdown the docker containers when mergerfs would go offline. Plex assumed everything just went missing. When that happens, plex will remove all of its own content because it assumes that you deleted it. To fix the problem, I wrote a background script check a dummy file every 1 minute. If that dummy file went missing, it would check it 2 more times. If it was still missing, then the containers would all shutdown... and then the script would attempt to bring mergerfs back and when the dummy file was found again. When found, the script would restart all the containers.

 

Anyways, good luck and yes adding cloud and other locations can be super useful.

 

Is this still an issue? I was looking to use it for transcoding to ram+ssd, but your post has given me pause.

On 1/27/2026 at 10:06 PM, rpj2 said:

Is this still an issue? I was looking to use it for transcoding to ram+ssd, but your post has given me pause.

It's not an issue if you orchestrate startup/stop correctly using the provided hook scripts.

In general you'd want the mergerFS mounts to mount at array start and unmount at array stop.

Intermittent failures I've not seen, it seems to work extremely reliably for most people from what I've heard.

just thought i'd comment on here and document my setup a little so that anybody who wants to make use of the information can and if they have any suggestions or improvements please poke / quote me and i'll edit the post.

as just a general entrypoint note for someone considering this, it genuinely seems to solve all the problems with unraids FUSE implementation which sees 30x slower reads

https://www.phoronix.com/news/Linux-6.9-FUSE-Passthrough

i have very predictable workloads, and the disappointment with Unraid from the start in relation to its poor performance (SHFS) is finally gone.

The only gotcha i've found so far is in relation to hdd activity. you'll generally see a power increase (less spin down on hdd's) in using this because of how mergerfs walks the directories when looking for files. this probably can be mitigated a lot through the policies but currently i don't have good insight into ones which would. hopefully this thread can help us groupthink some. this problem is also documented here https://trapexit.github.io/mergerfs/latest/faq/limit_drive_spinup/

I do think though that there exists a series of potential options which can fix this, we just need to properly go through and figure them out and create something we can all live with. some of the options are tradeoffs in greater performance for lesser efficiency. file placement and general grouping is also another, i'm sure we can move directories around to better localise them and prevent spinups.

i need to check over the mergerfs scripts some more because some exist to do that i believe. we also have that unraid plugin which can do similar in terms of the scatter / gather of files.

even with that gotcha i'm still going with this, it turns your system into actually being usable again

for some stats, look at this

^ gigabit saturated connection download utilisation, the best part being no huge 100% CPU usage spikes anymore and just regular, what you'd expect performance. not the crippled and diminished performance of SHFS

In using mergerfs the CPU utilisation at LOAD was LOWER than SHFS at IDLE

SHFS IDLE: 10-13%
MergerFS IDLE: 1%

SHFS LOAD: 28-35%

MergerFS LOAD: 13%

As always the docs should be the source of truth for everything, this is just my first attempt at fumbling through them https://trapexit.github.io/mergerfs/latest/

After installing the plugin, in my /etc/mergerfsp/array_start.sh i've placed

#!/bin/bash
mkdir -p /mnt/addons/mergerfs
sleep 1
# Put any commands to run at ARRAY START (after disks mounted but services not yet started) here!
mergerfs -o category.create=ff,category.search=ff,func.getattr=newest,dropcacheonclose=false,passthrough.io=rw,cache.files=auto-full,cache.writeback=false,minfreespace=105G,inodecalc=path-hash,never-forget-nodes=true,lazy-umount-mountpoint=false '/mnt/nvme_cache:/mnt/cache:/mnt/disk1:/mnt/disk2:/mnt/disk3:/mnt/disk4:/mnt/disk5:/mnt/disk6:/mnt/disk7:/mnt/disk8:/mnt/disk9:/mnt/disk10:/mnt/disk11:/mnt/disk12:/mnt/disk13:/mnt/disk14' /mnt/addons/mergerfs
sleep 15
exportfs -i -o fsid=110,async,no_subtree_check,sec=sys,rw,all_squash,insecure,anonuid=99,anongid=100,nohide,crossmnt 192.168.xx.xx:/mnt/addons/mergerfs/data
exportfs -i -o fsid=110,async,no_subtree_check,sec=sys,rw,all_squash,insecure,anonuid=99,anongid=100,nohide,crossmnt 192.168.xx.xx:/mnt/addons/mergerfs/data
exportfs -i -o fsid=110,async,no_subtree_check,sec=sys,rw,all_squash,insecure,anonuid=99,anongid=100,nohide,crossmnt 192.168.xx.xx:/mnt/addons/mergerfs/data

and i've also got in the dropdown menu to unmount on array stop

the exportfs is used to NFS export it, i've found NFS performs better in general than SMB (lower cpu usage and better at small files) but you can use either. theres some previous posts on how to set up SMB. who knows I might switch because NFS seems to be more edge cases in the docs but i'll wait to see if they manifest for myself

here are my settings and justification for them. in general what i want my setup to look like, is that files get placed onto the nvme ssd and then i can use other tooling (the advanced mover plugin etc) to place them onto the array

Setting	Commentary
passthrough.io=rw	this is the big one, native FUSE passthrough and thats where we get almost all the speed from
category.create=ff	this i've got a high confidence that will function how i want, since it walks the order you place on the mount so it will always create files on my nvme ssd first
category.search=ff	this is the default one but its likely something i'm going to change i'm just not 100% sold on all the options yet and need to consider their implications. its really bad at times because if you have say a file on disk 10, it'll walk through and spin up disks 1-9 checking for it before finding it on disk 10
func.getattr=newest	another one that im 50/50 on. it is really useful for what it does (it returns the newest file, since we are using first found in the search if you have multiples of the file then it could return an older one without it since it stops on the first found, but in how it does it means that it has to search through all the disk. this is one i think i'll experiment with and change to reduce spinup after i've audited a bit more
dropcacheonclose=false	if you turn this on, you'll end up purging your linux native page cache a hell of a lot more and just having tons of ram just being unused. keep it off unless you have some kind of high memory pressure.
cache.files=auto-full	we use passthrough.io so its needed
cache.writeback=false	needed for passthrough.io
minfreespace=105G	set whatever you want but I think its good that you don't fill up an entire disk. bad things can happen when you do and it avoids headaches
inodecalc=path-hash	nfs related recommendations in docs
never-forget-nodes=true	nfs related recommendations in docs
lazy-umount-mountpoint=false	nfs related recommendations in docs

my NFS export settings i'm lead to believe by the documentation are wrong but i've yet to experience a problem with them. i'm going to keep going with them until I do experience those problems or else i'll keep what I have and try to make it work around what I want.

theres more settings in here that I will likely play around with https://trapexit.github.io/mergerfs/latest/faq/limit_drive_spinup/

but for now i'm pretty happy with things the way they are.

in terms of how you interact with everything, all your docker containers that would otherwise have been using /mnt/user should now be using /mnt/addons/mergerfs as in the example. also remove your share exports for the old /mnt/user stuff in the shares tab. turn off NFS / SMB share exports in the share menus and do them yourself in their respective places and script it.

I am noticing on odd occasions my parity drive spinning up, which is an indicator that something is being written to the underlying array filesystem that shouldn't be. another thing that i'll need to dig into. i'm suspecting its something related to updating directory last accessed times because i noticed some of those changed even though I never did use the files.

possibly the search category being existing path first found rather than just first found and coupling the folders together more cleanly could help with the spinups - nobody wants 10 drives to spin up when browsing a directory of 10 songs.

the problem with existing path first found though would be that i am using mover tuner to migrate from nvme > array which wouldn't work well for this particular task since it'll just dump everything into the disk with the most space (or at least thats how i've previously set it up).

maybe using the shares tab and the watermarks it could more cleanly map out, but another option which i've read others do is to create something like unraids /mnt/user and /mnt/user0 where the user is ssds + hdds and user0 is just hdd's. then you can run some kind of rsync migration script from one to the other and it'll follow mergerfs policies on file creation (and you set up another mergerfs user0 pool with different settings, you'd want the category.creation to be the same as your /mnt/user category.search, so that it ends up being path preserving or just putting the files in such a way that it reduces spinups)

anybody who has any insight or tips on getting this all running better, please don't be shy and comment

EDITS:
modified dropcacheonclose=true to false

edit2:

the + are things i've added and - are things i've removed

+ noatime
- func.getattr=newest
+ cache.readdir=true
+ cache.symlinks=true
+ cache.statfs=120
+ cache.negative-entry=120
+ cache.attr=1800
+ cache.entry=1800

most of these are aimed at keeping disks spun down more / longer

Edited May 30May 30 by mrpops2ko

so whilst mover i think should still work, just using shfs instead of mergerfs - if you do want to make use of a mover which is based upon using mergerfs i've attached an example of muffins script

now in order to use this, you'll need to set up another mergerfs pool of just your hdds, i did this

mergerfs -o noatime,category.create=ff,category.search=ff,func.getattr=newest,dropcacheonclose=false,passthrough.io=rw,cache.files=auto-full,cache.writeback=false,minfreespace=105G,inodecalc=hybrid-hash,never-forget-nodes=true,lazy-umount-mountpoint=false,cache.readdir=true,cache.symlinks=true,cache.statfs=120,cache.negative-entry=120,cache.attr=1800,cache.entry=1800,fsname=mergerfs-cold '/mnt/disk1:/mnt/disk2:/mnt/disk3:/mnt/disk4:/mnt/disk5:/mnt/disk6:/mnt/disk7:/mnt/disk8:/mnt/disk9:/mnt/disk10:/mnt/disk11:/mnt/disk12:/mnt/disk13:/mnt/disk14' /mnt/addons/mergerfs-cold

the following bellow is a docker container which will run on startup and then stay up and rerun daily at 3am checking to see if you meet the criteria for movement to occur

in it im moving from `/mnt/nvme_cache` (my nvme ssd cache) to `/mnt/addons/mergerfs-cold` which is just my regular `/mnt/addons/mergerfs` without nvme / ssd's in it

the script is both better and worse than the advanced mover script. it is better because it uses copy on write techniques to avoid issues with file transfers (it will copy / rename / do size comparison etc checks / then delete and fix the naming) which is better in scenarios where powercuts happen or just various issues.

the bad sides to it, are that it doesn't have the advanced ability to pick based upon mtime (so moving the oldest files)

services:
  mergerfs-cache-mover-nvme:
    image: ghcr.io/monstermuffin/mergerfs-cache-mover:latest
    container_name: mergerfs-cache-mover-nvme
    privileged: true
    environment:
      INSTANCE_ID: nvme
      CACHE_PATH: /mnt/nvme_cache
      BACKING_PATH: /mnt/addons/mergerfs-cold
      SCHEDULE: "0 3 * * *"
      THRESHOLD_PERCENTAGE: 95
      TARGET_PERCENTAGE: 85
      MAX_WORKERS: 1
      LOG_LEVEL: DEBUG
      KEEP_EMPTY_DIRS: false
      EXCLUDED_DIRS: >-
        appdata,
        domains,
        system/docker,
        libvirt,
        shared_env
    volumes:
      - /mnt:/mnt:rw,rslave
      - ./var/log:/var/log:rw
    restart: unless-stopped

i kind of would like to have mtime ability, so i might look into adding it. always scary modifying scripts that are touching files though lol