Could someone tell me if it is possible to install SnapRAiD and mergerFS on zimaos?
ZimaOS is Buildroot-based and intentionally minimal. It does not include apt or other traditional package managers, and native package installation is not supported. Any manual changes to the system layer can also be overwritten by updates.
That means you cannot natively install SnapRAID or mergerfs directly on the host OS.
What does work:
- Docker, recommended
ZimaOS is designed around Docker. Running SnapRAID and mergerfs inside a container is the most common and clean approach.
You would:
- Bind-mount your physical disks into the container
- Pass /dev/fuse and add SYS_ADMIN capability for mergerfs
- Run SnapRAID via scheduled tasks inside the container
This keeps the host clean and update-safe.
- ZVM virtual machine
You can create a Debian or Ubuntu VM using ZVM and install SnapRAID and mergerfs normally with apt inside the VM. This gives you a full standard Linux environment without modifying the host, but uses more resources.
Summary:
Native install on host: not supported
Docker: supported and recommended
ZVM: supported alternative
If you share your goal, for example flexible pooling, parity, or something else, we can suggest the best layout for your setup.
It’s plausible that at some point they may officially support it but right now there isn’t a simple way. I’m not sure if the docker setup is rootful or rootless but if the former you can do as @gelbuilding mentioned for mergerfs and can find more details here.
Very simple fact: I have mergerfs and snapraid natively running on my ZimaOS.
I tried to do it in Docker, but could not get it running. As I am not a Linux expert, I did it with GEMINI. I fed NotebookLM and GEMINI with some documentation about m and s, and with a lot of discussions and constantly staying heads-up during the configuration suggestions of GEMINI, I got it running.
I just built the executables in WSL2 and copied them over to ZimaOS.
It was a kind of LINUX course, and that is the best thing about this exercise.
I did it because of the bad things I read about RAID. It is a bit complicated, but the practical handling is straightforward. I can easily shuffle around my files with the Windows 11 Explorer. The FILES app of ZimaOS is too clumsy.
I could have gone for a system that makes a copy of the main Disk, but since I have 3 equal disks, I use 2 (2x4 TB) and one 4 TB for parity.
1 Like
mergerfs has static builds which if you’re installing manually should work on most any system.
Docker is complicated if they are using rootless containers as it won’t support sharing the mount like rootful mounts.
Yes, it is technically possible, but it is not officially supported or straightforward on ZimaOS.
A few users have successfully run SnapRAID and mergerfs natively by building or downloading static binaries externally, for example via WSL2 or another Linux machine, and then manually copying them onto ZimaOS.
mergerfs in particular provides static binaries, which makes this easier for advanced users.
That said, the cleaner and safer approach is still Docker or a Debian/Ubuntu ZVM VM. Those methods align much better with how ZimaOS is designed and are easier to maintain long term.
The important thing to understand is that ZimaOS is Buildroot-based, intentionally minimal, and does not provide a traditional package-management environment like apt. Any native modifications are manual and may be overwritten by OTA updates.
Also, be careful following AI-generated Linux instructions blindly. On an immutable-style OS like ZimaOS, manually changing system components can affect stability, break updates, or create problems that become very difficult to troubleshoot later.
So the current community consensus is basically:
Docker = recommended
ZVM = safe alternative
Native binaries = possible, but more of an advanced unsupported workaround
1 Like
You’d be very welcome to document the process and show us how you did. Hopefully it would get easier over time and, perhaps, implemented into future ZimaOS builds too.
1 Like
I was planning to do so, but I asked GEMINI to do it. It did, but all the little mistakes are not yet filtered from the document, and it might have missed some points. If you are a little bit fluent in LINUX, you can manage it together with some AI system. Sadly, I found out that AI also missed a few mechanisms in LINUX. And in ZimaOS things are limited, but can be overcome with the help of a computer with all necessary tools.
Interesting update after checking directly on my ZimaCube.
mergerfs does appear to already be included with ZimaOS:
which mergerfs
returns:
/usr/bin/mergerfs
and a wider search also shows:
/usr/bin/mergerfs
/usr/bin/mergerfs-fusermount
However, SnapRAID does not appear to be included:
which snapraid
snapraid --version
find / -name 'snapraid*' 2>/dev/null
returns no SnapRAID binary.
So from what I can verify on my system, mergerfs is already present on the ZimaOS host, but SnapRAID is not.
That makes the bigger question: is there a documented and update-safe way for users to configure mergerfs properly on ZimaOS, and could SnapRAID be added or supported in a clean way later?
As already discussed with you - here we go 
2 Likes
This is outstanding mate.
For anyone following this thread, Holger has not just talked about the problem, he has actually built a proper ZimaOS solution for it.
What makes this impressive is that ZimaOS is not a normal Linux distribution where you can simply install packages and modify the base system freely. It is a read-only, appliance-style OS, so adding something like SnapRAID safely is not simple.
Holger’s approach using a systemd-sysext module is exactly the kind of clean layered method that makes sense for ZimaOS. It adds the missing functionality without fighting the base OS or turning the system into a hacked-up install.
From what I can see, this is a very serious piece of work:
mergerfs + SnapRAID for ZimaOSstorage pool with parityboot-race safesystemd-sysext baseddesigned around the way ZimaOS actually works
Honestly mate, I take my hat off to you.
This is the kind of work that opens doors for ZimaOS users and shows that advanced storage features can be added in a clean, controlled and update-friendly way.
Superstar effort, Holger. Very impressive.
2 Likes
I did a controlled test on my ZimaCube Pro and can confirm Holger’s sysext layer works on my system.
Test environment:
ZimaCube Pro
ZimaOS
amd64
systemd-sysext available
Docker buildx available
What I tested:
- Cloned the repo.
- Built SnapRAID locally using the provided Docker build script.
- Built the sysext image locally.
- Installed the sysext.
- Confirmed systemd-sysext loaded mergerfs-snapraid.
- Confirmed the binaries are available:
mergerfs v2.42.0
SnapRAID CLI v14.5
I then did a safe manual mergerfs test using only a disposable test disk/folder. I created two test branches and one pool folder, mounted them manually with mergerfs, created a file through the pool, and confirmed the real file appeared on the underlying branch. I then unmounted the test pool cleanly.
So far, this confirms the sysext installs correctly and mergerfs works on ZimaOS.
Important note: I did not run a full SnapRAID parity/recovery test yet. For that, I would want a proper test layout with separate data and parity disks, ideally ext4 or xfs, and not any live production data.
Also worth noting: after install, the default timers/services were enabled, so I disabled them before configuring anything. Anyone testing this should check the default config first and make sure it does not point to real disks before starting services or timers.
Very impressive work from Holger. This looks like a proper ZimaOS-friendly layered approach rather than fighting the OS.
2 Likes
@777-Spider @trapexit @Zima-Jerry @ED209 - I guess we’re seeing ZimaOS history being written here
2 Likes
That may actually be true mate.
What Holger has shown here is more than just getting mergerfs and SnapRAID running. The important part is the method.
He has respected how ZimaOS is built and added functionality as a clean layer, instead of fighting the base OS.
If this approach keeps proving itself, it could become a very useful pattern for adding more advanced features to ZimaOS in the future.
So yes, this does feel like a bit of ZimaOS history being written. Credit to Holger and everyone helping test and shape it properly.
2 Likes
I did install this, but after a few failures from other sources. I now have uninstalled it and installed it again because after a reboot it doesn’t work anymore. After the first install it was okay, but now mergerFS task is not recognized or refused during startup. I can see it on my terminal there are red lines with those kind of text.after some investigations with a little help of AI I found out that there might be a race condition at the moment.Here is a copy of the services that have been started.
kmod-static-nodes.service loaded active exited Create List of Static Device Nodes
libvirt-guests.service loaded active exited libvirt guests suspend/resume service
â—Ź mergerfs-pool-watchdog.service loaded failed failed Ensure mergerfs pool started after sysext merge (boot-race guard)
mergerfs-pool.service loaded active exited mergerfs storage pool (ZimaOS)
minidlnad.service loaded active running minidlna server
NetworkManager-wait-online.service loaded active exited Network Manager Wait Online
There seems to be a race condition during startup (reboot) When started, I can start the system, mergerFS and snapRAID, and it all works very well.
Thanks for the detailed report — you nailed it, it’s a boot-race, and I tracked down the exact cause and fixed it.
What was happening: my extension does upgrade mergerfs to v2.42 — but that upgrade only takes effect after the extension has merged during boot. ZimaOS already ships an old mergerfs (v1.5.4) in its base system, so the file /usr/bin/mergerfs always exists, even in the short window before my extension merges. The old startup guard only checked “does /usr/bin/mergerfs exist?” — which is always true — so on a reboot it could start the pool in that pre-merge window, i.e. against the base v1.5.4. That old version rejects the modern mount options and exits with an error → mergerfs-pool.service failed → mergerfs-pool-watchdog.service failed (your red lines). Once the merge finished (v2.42), a manual start worked fine.
The fix (now on main):
- The boot guard now keys on /usr/bin/snapraid, which only my extension provides — so the pool starts only once the extension has truly merged (and never against the base v1.5.4).
- start-pool.sh now also waits for the data disks to be mounted before starting mergerfs (a second, independent race that could otherwise leave you with an empty pool).
- Bonus: if a future ZimaOS update ever drops the extension, the service now cleanly skips instead of failing.
Verified with two real cold reboots on ZimaOS v1.6.1: pool comes up active on v2.42, watchdog dead (no failure), pool mounted.
To get it: pull main and re-run sudo ./install.sh (config + data are preserved). Heads-up: uninstall keeps your existing pool.env, so if it’s left over from an earlier broken attempt, compare it against config/pool.env.example (especially BRANCHES). The installer now warns about this too.
Holger
I have worked with AI and found a solution in an override. Please follow next explanation of the AI.
Thread Title: How to fix MergerFS pool failing to mount on boot in ZimaOS (Boot-Race Guard Fix)
The Problem
If you are running a MergerFS setup on ZimaOS (for example, with external USB/PCIe drives or a TerraMaster DAS), you might notice that your MergerFS storage pool occasionally—or always—fails to mount automatically after a cold boot or a system restart.
When checking the status of the watchdog service, you will see a loaded failed failed status with an exit-code error:
Bash
sudo systemctl status mergerfs-pool-watchdog.service
Output snippet:
mergerfs-pool-watchdog.service: Main process exited, code=exited, status=1/FAILURE
Failed to start Ensure mergerfs pool started after sysext merge (boot-race guard).
However, if you manually start the service or mount the pool via SSH once the system is fully booted, everything works perfectly.
The Technical Cause
ZimaOS uses a gelaunched/layered system and custom startup scripts (via CasaOS components) to handle storage drives. During a cold boot, there is a massive race condition (boot-race).
The default mergerfs-pool-watchdog.service only waits a hardcoded maximum of 30 seconds for the /usr/bin/mergerfs binary to appear after the systemd-sysext.service merge. However, it completely ignores whether the underlying physical storage drives (like external DAS arrays) have actually spun up and finished mounting via the OS. Because external hard drives take longer to become ready, the watchdog checks for the pool too early, encounters an empty setup, triggers status=1/FAILURE, and gives up completely due to default systemd rate-limiting.
Trying to hardcode strict systemd drive dependencies (like After=media-DAS1.mount) usually leads to a deadlock because ZimaOS handles these mounts downstream outside the standard systemd boot sequence.
The Ultimate Solution: An Infinite Self-Healing Loop
The most elegant, robust, and permanent fix is to remove any rigid timing assumptions and convert the watchdog service into an infinite self-healing loop. Instead of guessing how long the drives take to spin up, the watchdog will aggressively check for the pool, and if it fails, it will wait 3 seconds and try again—forever—until the drives are ready.
Here is how to apply this fix via SSH:
Step 1: Open the Systemd Override Editor
Run the following command to create an override file for the watchdog service:
Bash
sudo systemctl edit mergerfs-pool-watchdog.service
Step 2: Insert the Infinite Loop Logic
Your editor will open a temporary file. Paste the following configuration exactly on the empty space between the top comment lines (above the line that says ### Edits below this comment will be discarded):
Ini, TOML
[Service]
Restart=on-failure
RestartSec=3s
StartLimitIntervalSec=0
Why this works flawlessly:
Restart=on-failure: If ZimaOS is still waking up the drives and the watchdog fails, systemd will automatically schedule a restart.
RestartSec=3s: It waits exactly 3 seconds between attempts, keeping the boot process moving without unnecessary long delays.
StartLimitIntervalSec=0: This is the magic key. It completely disables systemd’s rate-limiting. Normally, systemd gives up after 5 failed attempts. Setting this to 0 forces it to try infinitely until it succeeds.
Once the ZimaOS backend finally mounts your storage drives, the watchdog’s command will instantly succeed, the pool will mount, it will return a success code, and systemd will stop the loop.
Step 3: Save and Reload Systemd
Save and exit the editor (If you are using Nano, press Ctrl+O, then Enter, then Ctrl+X).
Tell systemd to reload its configuration files and apply the changes:
Bash
sudo systemctl daemon-reload
(Optional) You can test it immediately by manually launching the service:
Bash
sudo systemctl start mergerfs-pool-watchdog.service
Conclusion
Your ZimaOS MergerFS pool is now fully bulletproof against slow-spinning drives, hardware lag, or unexpected boot-sequence delays. Whether your drives take 5 seconds or 5 minutes to show up, the system will reliably heal itself and mount the pool without any manual intervention.
Yesterday I tried it with AI and we were just running around to find the solution for the problem to fix it with a Cron job. I was aware of your Cron application, but couldn’t find the right place. Until you gave me an answer here in this forum, I found out how this was all done, and at the same time you had made this merger FS plus snap rate script. So then things were going in the right way. Now, I found this little problem, and it was very speedy before we could find it out with AI. AI is not useless, but be careful. They are hallucinating in many ways.
And I’m absolutely not a Linux expert, far from that. I’m just a Linux beginner. But with general knowledge and logic thinking, you can get these answers also with AI.
So I will wait for your answer or your comments, and then I have to change my install script. You said something about that before, but look at this first and just wait if this is a better method, or, in general it’s always the best method for this kind of thing to do.
Your override fix works, but let me share what i found as the actual root cause, because it matters:
There were two separate boot races, not one.
- The stale binary. ZimaOS ships an ancient mergerfs v1.5.4 at /usr/bin/mergerfs. So checking for that path is useless — it’s there before the sysext merges, and the pool starts against v1.5.4, which rejects modern options and fails. We now gate on /usr/bin/snapraid instead, because only the sysext provides it → its presence truly means “merge done.”
- The empty-pool trap. This is the important one: mergerfs 2.42 returns exit 0 when a branch isn’t mounted yet — it mounts an empty pool and shadows the disk when it appears later. Since that’s a success, Restart=on-failure never triggers there. So the retry loop can stop at the worst moment and leave you with an empty pool. I fixed it by explicitly waiting for each branch to be mounted before starting (default 90 s), and refusing to mount over a missing branch.
So your StartLimitIntervalSec=0 loop is a fine extra safety net, but on its own it only cures the symptom of race #1 and is blind to race #2. The fixes above are baked into the install script (no manual systemctl edit needed), and both were verified on cold reboots.
Happy to share the exact unit/script changes if useful!
1 Like
Oh thank you for your correction. I tried it on my Zimaboard with a TerraMaster with 4discs and it really took a long time before all these were really mounted. I could wait for it and see the pool appear on my share on the PC. Maybe it was almost a minute after reboot. But tried twice and it’s okay now. I integrated start-pool.sh in my current file system.
1 Like
I have been removed eight thousand files in the safe directory with the Snapdraid Security.
In your script, you are setting a threshold to stop any action when the number of files is greater than the delete threshold. I understand you want to be safe, but this is not so practical. Can I do something about this? Of course I can set this delete threshold, but should I set it in the commands that I start the thing up. How is the delete threshold environment variable set is this in the system?
When you’re updating this situation can happen quite a lot of times and will be very annoying, and you have to check your logs very regularly. I think we need to have some message heads up what is going on and maybe also an override possibility for this script.
There’s another complication in this start snapraid script. I have been Migrating all my files for apps to an SSD storage connected to the SATA connection of the Zimaboard. So I have to adapt /DATA to where my files are located.