mergerfs/mkdocs/docs/faq/compatibility_and_integration.md

# Compatibility and Integration

## What operating systems does mergerfs support?

[Primarily Linux.](../setup/installation.md) FreeBSD is casually
supported but not well tested.

With FreeBSD certain Linux functions and FUSE features [are not
supported.](../known_issues_bugs.md#freebsd-version) In many cases the
absence will not be noticed however more advanced features will not be
available.


### Why not support MacOS?

* Last checked the support for FUSE on MacOS was in flux.
* MacOS is not an OS commonly used for NASs and other use cases
  for which mergerfs is used.
* trapexit does not own a MacOS based system.


### Why not support Windows?

[WinFSP](https://winfsp.dev/) does implement a libfuse compatible API
for Windows however mergerfs does not use libfuse (perhaps
[ironically](https://github.com/libfuse/libfuse/blob/master/AUTHORS).)
Even if mergerfs was ported to use libfuse it would require the use of
the low level API. WinFSP does not appear to support libfuse's low
level API.

Windows, while used for NAS systems more often than MacOS, is still
relatively uncommon when compared to Linux. [Drive
Pool](../project_comparisons.md#stablebits-drivepool) is a good
alternative. It may also be possible to use mergerfs with WSL.


## What filesystems can be used as branches?

ext4, btrfs, xfs, f2fs, zfs, nfs, etc.

Most any filesystem should work but there could be issues with
non-POSIX compliant filesystems such as nfs (w/ root squashing), vfat,
ntfs, cifs, exfat, etc. When directories need to be created or files
moved by mergerfs if the filesystem returns errors due to not
supporting certain POSIX filesystem features it could result in the
core functions failing.

Since mergerfs is not generally used with non-POSIX filesystems this
has not been a problem for users and there are some checks for known
edge cases but it is possible some are not accounted for. If use with a
filesystem results in issues please [file a
ticket](https://github.com/trapexit/mergerfs/issues) with the details.


## What types of storage devices does mergerfs work with?

Since mergerfs works at the filesystem level rather than device level
there is no compatibility concerns based on the physical storage
devices involved.


## Can I use mergerfs without SnapRAID? SnapRAID without mergerfs?

[https://www.snapraid.it](https://www.snapraid.it)

Yes. They are completely unrelated pieces of software that just happen
to work well together.


## How does mergerfs interact with SnapRAID recovery behavior?

SnapRAID does not choose parity layout based on directory structure or
relative path. As each file is discovered, SnapRAID fills parity space
for that file based on its size using the next available parity area.
This makes the logical parity layout depend on discovery order, file
size, and how much data already exists on each filesystem at that
time.  Filesystems with similar used space, regardless of total
capacity, are more likely to place newly added files into similar
parity positions.

Because of that, if files are changed or removed across multiple
branches and those files happen to overlap in parity space, recovery
of those deleted files may be less reliable. This is not a general
concern, is not unique to mergerfs usage, and it does not affect
filesystem failure recovery. It is specifically a concern when trying
to recover from accidental deletion of files spread across multiple
filesystems.

In practice this mostly matters when the filesystems have very similar
used space, the files are created across those filesystems around the
same time, and you later want SnapRAID to recover an accidental
deletion spanning multiple filesystems. Otherwise this is usually not
something to worry about.

If, however, this is a concern it can be beneficial to keep files on
as few filesystems as possible or otherwise keep related files
together. See the [collocation
section.](configuration_and_policies.md#how-can-i-ensure-files-are-collocated-on-the-same-branch)


## Can I use mergerfs without NonRAID? NonRAID without mergerfs?

[https://github.com/qvr/nonraid](https://github.com/qvr/nonraid)

Yes. They are completely unrelated pieces of software that just happen
to work well together.


### How does mergerfs interact with NonRAID?

There are no known special interactions or concerns between mergerfs
and NonRAID. They are separate tools and mergerfs has no known
behavior which requires any special configuration or caveats when used
with NonRAID.


## Does mergerfs support CoW / copy-on-write / writes to read-only filesystems?

Not in the sense of a filesystem like BTRFS or ZFS nor in the
overlayfs or aufs sense. It does offer a
[cow-shell](http://manpages.ubuntu.com/manpages/bionic/man1/cow-shell.1.html)
like hard link breaking (copy to temp file then rename over original)
which can be useful when wanting to save space by hardlinking
duplicate files but wish to treat each name as if it were a unique and
separate file.

If you want to write to a read-only filesystem you should look at
overlayfs. You can always include the overlayfs mount into a mergerfs
pool.


## Can mergerfs run via Docker, Podman, Kubernetes, etc.

Yes. [See installation
page.](../setup/installation.md#podman-docker-oci-containers)


## How does mergerfs interact with user namespaces?

FUSE does not have any special integration with Linux user namespaces
used by container runtime platforms like Docker, Podman, etc. The
uid/gid values passed to mergerfs will be the host level values rather
than that seen inside the container. Meaning `root` in a container
with user namespaces configured will not be `root` to mergerfs. Same
with any other uid/gid. Meaning your permissions on your branches must
work with the translated values from the id mapping.

It is generally recommended to not use user namespacing / id mapping
given the complication it introduces.


## Can mergerfs be used with NFS root squash?

If mergerfs is pooling a NFS mount then root squash must be disabled
as mergerfs needs to be able to have elevated privileges to do what it
does (set permissions, ownership, etc.)

If you are exporting mergerfs over NFS it is not strictly necessary to
disable root squashing but 3rd party software running as root may
fail.

See the [section on remote filesystems.](../remote_filesystems.md)


## Does inotify and fanotify work?

Yes. You can test by using
[inotifywait](https://man7.org/linux/man-pages/man1/inotifywait.1.html) or
[inotifywatch](https://man7.org/linux/man-pages/man1/inotifywatch.1.html).

However, you can not get notifications for events that occur outside
of the mergerfs mount. For instance if you are doing
[out-of-band](usage_and_functionality.md#can-filesystems-be-removed-from-the-pool-without-affecting-them)
changes it is not possible to get those events forwarded through
mergerfs. FUSE offers no mechanism to publish events and even if it
did it would require somewhat expensive
[inotify](https://man7.org/linux/man-pages/man7/inotify.7.html) or
[fanotify](https://man7.org/linux/man-pages/man7/fanotify.7.html)
watches on all branches.

Most software which has the ability to actively monitor a filesystem
(such as Plex, Emby, Jellyfin, Airsonic, etc.) are using `inotify` or
`fanotify`.

If you must add content out-of-band the only way to get real-time
updates (via inotify or fanotify) is to add the underlying branches to
the software rather than using the mergerfs mount. An alternative is
to enable regular library scanning. Plex, for instance, has "Scan my
library periodically". Additionally, if you are using software such as
Radarr, Sonarr, or Lidarr you can configure it to trigger library
updates in a number of services. This can be found under `Settings >
Connect`.