mirror of
https://github.com/trapexit/mergerfs.git
synced 2026-11-22 07:56:32 -05:00
Misc docs updates (#1544)
This commit is contained in:
parent
0371f03def
commit
00e5467e99
7 changed files with 76 additions and 49 deletions
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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?
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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)
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue