Misc docs updates (#1544)
Some checks failed
CodeQL / Analyze (push) Has been cancelled
mkdocs / deploy (push) Has been cancelled

This commit is contained in:
trapexit 2025-10-13 12:44:53 -04:00 • committed by GitHub
parent 0371f03def
commit 00e5467e99
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 76 additions and 49 deletions

View file

@ -9,9 +9,9 @@
* VM images: For the same reasons as databases. VM images are accessed * VM images: For the same reasons as databases. VM images are accessed
very aggressively and mergerfs will introduce a lot of extra latency. very aggressively and mergerfs will introduce a lot of extra latency.
* As replacement for RAID: mergerfs is just for pooling branches. If * As replacement for RAID: mergerfs is just for pooling branches. If
you need that kind of device performance aggregation or high you need device performance aggregation or high availability you
availability you should stick with RAID. However, it is fine to put should stick with RAID. However, it is fine to put a filesystem
a filesystem which is on a RAID setup in mergerfs. which is on a RAID setup in mergerfs.
**However, if using [passthrough](../config/passthrough.md) the above **However, if using [passthrough](../config/passthrough.md) the above
situations are less likely to be a concern. Best to do testing for situations are less likely to be a concern. Best to do testing for

View file

@ -230,13 +230,29 @@ the software's author and request proper handling of `EXDEV` errors.
* [Moving files and directories fails with Samba](../known_issues_bugs.md#moving-files-and-directories-fails-with-samba) * [Moving files and directories fails with Samba](../known_issues_bugs.md#moving-files-and-directories-fails-with-samba)
## Why is rtorrent failing with ENODEV (No such device)? ## Why is software needing mmap failing?
Be sure to set See [Known Issues and Bugs#3rd Party
[cache.files=partial|full|auto-full|per-process](../config/cache.md) Software](../known_issues_bugs.md#3rd-party-software) and
or use Linux kernel v6.6 or above. rtorrent and some other [QuickStart](../quickstart.md).
applications use [mmap](http://linux.die.net/man/2/mmap) to read and
write to files and offer no fallback to traditional methods.
## Why don't quick scans fail to pick up new media?
Media consumption software like Plex, Jellyfin, Emby, Airsonic,
Navidrome, etc. will use timestamps of directories to see if it should
be scanned. Be sure to set `func.getattr=newest` to catch that.
A full scan would still pick up all media and for those concerned
about device activity it is recommened to disable quick scans and
leave periodic full scans so the activity is managed. Or to configure
your software which manages downloads (such as *Arr family of
software) to trigger specific scans when files are added to the pool.
Additional reading:
* [Does inotify and fanotify
work?](compatibility_and_integration.md#does-inotify-and-fanotify-work)
## Why don't I see mergerfs options in mount command or /proc/mounts? ## Why don't I see mergerfs options in mount command or /proc/mounts?

View file

@ -5,7 +5,10 @@
[union filesystem](https://en.wikipedia.org/wiki/Union_mount) geared [union filesystem](https://en.wikipedia.org/wiki/Union_mount) geared
towards simplifying storage and management of files across numerous towards simplifying storage and management of files across numerous
commodity storage devices. It is similar to [**mhddfs**, **unionfs**, commodity storage devices. It is similar to [**mhddfs**, **unionfs**,
**aufs**, **DrivePool**, etc.](project_comparisons.md) **aufs**, **DrivePool**, etc.](project_comparisons.md) Allowing for
the aggregation of storage without the more rigid requirements and
failure conditions of [RAID and other
technologies](project_comparisons.md).
## Features ## Features
@ -35,7 +38,8 @@ commodity storage devices. It is similar to [**mhddfs**, **unionfs**,
* Read/write overlay on top of read-only filesystem like OverlayFS * Read/write overlay on top of read-only filesystem like OverlayFS
* File whiteout * File whiteout
* RAID like parity calculation (see [SnapRAID](https://www.snapraid.it)) * RAID like redundancy (see [SnapRAID](https://www.snapraid.it) and
[NonRAID](https://github.com/qvr/nonraid))
* Redundancy * Redundancy
* Splitting of files across branches * Splitting of files across branches

View file

@ -91,36 +91,41 @@ on [page caching](config/cache.md).
## 3rd Party Software ## 3rd Party Software
### SQLite3, Plex, Jellyfin do not work with mergerfs ### Software using mmap
It does. If you're trying to put the software's config / metadata / * software using sqlite3 w/ mmap
database on mergerfs you can't set [cache.files=off](config/cache.md) * Plex (for config)
(unless you use Linux v6.6 or above and * Jellyfin (for config)
[direct-io-allow-mmap](config/options.md) is enabled) because they are * Emby (for config)
using **sqlite3** with **mmap** enabled and have failed to properly * Radarr
handle the situation where **mmap** may not be available. * Sonarr
* Lidarr
* other
* rtorrent
* qbittorrent (with 'Disk IO type = Memory mapped files')
[mmap](https://en.wikipedia.org/wiki/Mmap) is a filesystem and
operating system feature allowing files to be interacted with as if it
was normal memory. Support for `mmap` is **required** by a number of
projects. FUSE (and therefore mergerfs), in order to support `mmap`,
requires [page caching](config/cache.md) to be
enabled. IE `cache.files` must not be set to `off` (if using Linux before
v6.6 or mergerfs before v2.41.0.)
In newer versions of mergerfs and Linux `off` will work as it can now
auto enable page caching (and therefore `mmap`) as needed.
That said it is recommended that config and runtime files be stored on That said it is recommended that config and runtime files be stored on
SSDs on a regular filesystem for performance reasons. See [What should SSDs on a regular filesystem for performance reasons. See [What should
mergerfs NOT be used mergerfs NOT be used
for?](faq/recommendations_and_warnings.md#what-should-mergerfs-not-be-used-for). for?](faq/recommendations_and_warnings.md#what-should-mergerfs-not-be-used-for).
Other software that leverages **sqlite3** which require **mmap** Technically **sqlite3** does not require `mmap`, and in fact the
includes Radarr, Sonarr, and Lidarr. However, many programs use default is not to use it, but many programs enable the feature and
**sqlite3** and do not require **mmap**. provide no error handling when not supported. Ideally the software
would catch the error and use traditional IO instead. Not only is it
It is recommended that you reach out to the developers of the software more compatible but could also be more performant in certain
you are having troubles with and ask them to add a fallback to regular situations.
file IO when **mmap** is unavailable. It is not only more compatible
but also can be more performant in certain situations.
If the issue is that quick scans do not seem to pick up media then be
sure to set `func.getattr=newest`. That said a full scan will pick up
all media and it will put less load on the host to use time based
library scans or to configure downloading software to trigger a scan
when files are added to the pool. See [Does inotify and fanotify
work?](faq/compatibility_and_integration.md#does-inotify-and-fanotify-work)
for more details.
### backup software ### backup software

View file

@ -1,5 +1,8 @@
# Project Comparisons # Project Comparisons
There are no solutions, only trade-offs.
## mhddfs ## mhddfs
* [https://romanrm.net/mhddfs](https://romanrm.net/mhddfs) * [https://romanrm.net/mhddfs](https://romanrm.net/mhddfs)

View file

@ -25,24 +25,22 @@ cases.
* func.getattr=newest * func.getattr=newest
* dropcacheonclose=false * dropcacheonclose=false
In previous versions of Linux it was unable to support `mmap` if [page See [Known Issues and Bugs#Software Using
caching](config/cache.md) was disabled (ie: mmap](known_issues_bugs.md#software-using-mmap) for more details why
`cache.files=off`). However, it now will enable page caching if needed the Linux and mergerfs version matter and its relation to `mmap`.
for a particular file if `mmap` is requested.
[mmap](https://en.wikipedia.org/wiki/Mmap) is needed by certain **NOTE:** This "auto mmap" feature is only supported in mergerfs
software to read and write to a file. However, many software could v2.41.0 and above. For older versions see below or the docs from that
work without it and fail to have proper error handling for when it is release.
unavailable. Many programs that use **sqlite3** will require `mmap`
despite [sqlite3 working perfectly
fine](known_issues_bugs.md#sqlite3-plex-jellyfin-do-not-work-with-mergerfs)
without it (and in some cases can be more performant with regular file
IO.)
### You use Linux v6.5 or below ### You use Linux v6.5 or below
#### You need `mmap` (used by rtorrent and many sqlite3 base software) #### You need `mmap`
To keep the details in a single location: see [Known Issues and
Bugs#Software Using mmap](known_issues_bugs.md#software-using-mmap)
for more details.
* cache.files=auto-full * cache.files=auto-full
* category.create=pfrd * category.create=pfrd

View file

@ -19,9 +19,10 @@
compliant filesystems. mergerfs doesn't generally make exceptions compliant filesystems. mergerfs doesn't generally make exceptions
for FAT, NTFS, or other non-POSIX filesystem. for FAT, NTFS, or other non-POSIX filesystem.
* Unless using Linux v6.6 or above do **not** use `cache.files=off` if * Unless using Linux v6.6 or above do **not** use `cache.files=off` if
you expect applications (such as rtorrent) to use you expect applications to use
[mmap](http://linux.die.net/man/2/mmap). Enabling `dropcacheonclose` [mmap](http://linux.die.net/man/2/mmap). Enabling `dropcacheonclose`
is recommended when `cache.files=auto-full`. is recommended when `cache.files=auto-full`. See
[quickstart](quickstart.md).
* [Kodi](http://kodi.tv), [Plex](http://plex.tv), * [Kodi](http://kodi.tv), [Plex](http://plex.tv),
[Subsonic](http://subsonic.org), etc. can use directory [Subsonic](http://subsonic.org), etc. can use directory
[mtime](http://linux.die.net/man/2/stat) to more efficiently [mtime](http://linux.die.net/man/2/stat) to more efficiently