rt/mergerfs
1
0
Fork 0
mirror of https://github.com/trapexit/mergerfs.git synced 2026-10-25 18:40:18 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #1441 from trapexit/docs

Browse source 
Add doc pages for minfreespace and moveonenospc + other misc updates
This commit is contained in:
trapexit 2025-04-10 23:00:43 -05:00 • committed by GitHub
commit ad54c8be19
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 170 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

7
mkdocs/docs/config/branches.md
View file

@ -14,6 +14,7 @@ and a individual minfreespace value. The values are set by prepending
an `=` at the end of a branch designation and using commas as
delimiters. Example: `/mnt/drive=RW,1234`
### branch mode
- RW: (read/write) - Default behavior. Will be eligible in all policy
@ -24,10 +25,12 @@ delimiters. Example: `/mnt/drive=RW,1234`
- NC: (no-create) - Will be excluded from `create` policies. You can't
create on that branch but you can change or delete.
### minfreespace
Same purpose and syntax as the global option but specific to the
branch. If not set the global value is used.
Same purpose and syntax as the [global option](minfreespace.md) but
specific to the branch. If not set the global value is used.
### globbing

36
mkdocs/docs/config/functions_categories_policies.md
View file

@ -23,6 +23,7 @@ some may not be very useful in practice. For instance: **rand**
very odd behavior if used for `chmod` if there were more than one copy
of the file.
## Functions and their Category classifications
| Category | Functions |
@ -35,15 +36,17 @@ of the file.
In cases where something may be searched for (such as a path to clone)
**getattr** will usually be used.
## Policies
A policy is the algorithm used to choose a branch or branches for a
function to work on or generally how the function behaves.
A policy is an algorithm designed to select one or more branches for a
function to operate on.
Any function in the `create` category will clone the relative path if
needed. Some other functions (`rename`,`link`,`ioctl`) have special
requirements or behaviors which you can read more about below.
## Filtering
Most policies basically search branches and create a list of files / paths
@ -73,6 +76,7 @@ to be read-only as such (IE will set the mode `RO`) and will rerun the
policy and try again. This is mostly for `ext4` filesystems that can
suddenly become read-only when it encounters an error.
## Path Preservation
Policies, as described below, are of two basic classifications. `path
@ -93,6 +97,7 @@ With the `msp` or `most shared path` policies they are defined as
behaviors since `ignorepponrename` is available to disable that
behavior.
## Policy descriptions
A policy's behavior differs, as mentioned above, based on the function
@ -102,25 +107,25 @@ but it makes things a bit more uniform.
| Policy | Description |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all | Search: For **mkdir**, **mknod**, and **symlink** it will apply to all branches. **create** works like **ff**. |
| epall (existing path, all) | For **mkdir**, **mknod**, and **symlink** it will apply to all found. **create** works like **epff** (but more expensive because it doesn't stop after finding a valid branch). |
| epff (existing path, first found) | Given the order of the branches, as defined at mount time or configured at runtime, act on the first one found where the relative path exists. |
| eplfs (existing path, least free space) | Of all the branches on which the relative path exists choose the branch with the least free space. |
| eplus (existing path, least used space) | Of all the branches on which the relative path exists choose the branch with the least used space. |
| epmfs (existing path, most free space) | Of all the branches on which the relative path exists choose the branch with the most free space. |
| eppfrd (existing path, percentage free random distribution) | Like **pfrd** but limited to existing paths. |
| eprand (existing path, random) | Calls **epall** and then randomizes. Returns 1. |
| pfrd (percentage free random distribution) | Selects a branch randomly, with the probability of selection proportional to its available space relative to the total available space across all branches. For instance, if Branch A has 100 GB free and Branch B has 50 GB free, Branch A is twice as likely to be chosen. |
| rand (random) | Calls **all** and then randomizes. Returns 1 branch. |
| mfs (most free space) | Pick the branch with the most available free space. |
| ff (first found) | Given the order of the branches, as defined at mount time or configured at runtime, act on the first one found. |
| lfs (least free space) | Pick the branch with the least available free space. |
| lus (least used space) | Pick the branch with the least used space. |
| mfs (most free space) | Pick the branch with the most available free space. |
| all | Search: For **mkdir**, **mknod**, and **symlink** it will apply to all branches. **create** works like **ff**. |
| msppfrd (most shared path, percentage free random distribution) | Like **eppfrd** but if it fails to find a branch it will try again with the parent directory. Continues this pattern till finding one. |
| mspmfs (most shared path, most free space) | Like **epmfs** but if it fails to find a branch it will try again with the parent directory. Continues this pattern till finding one. |
| msplfs (most shared path, least free space) | Like **eplfs** but if it fails to find a branch it will try again with the parent directory. Continues this pattern till finding one. |
| msplus (most shared path, least used space) | Like **eplus** but if it fails to find a branch it will try again with the parent directory. Continues this pattern till finding one. |
| mspmfs (most shared path, most free space) | Like **epmfs** but if it fails to find a branch it will try again with the parent directory. Continues this pattern till finding one. |
| msppfrd (most shared path, percentage free random distribution) | Like **eppfrd** but if it fails to find a branch it will try again with the parent directory. Continues this pattern till finding one. |
| eppfrd (existing path, percentage free random distribution) | Like **pfrd** but limited to existing paths. |
| epmfs (existing path, most free space) | Of all the branches on which the relative path exists choose the branch with the most free space. |
| eprand (existing path, random) | Calls **epall** and then randomizes. Returns 1. |
| epff (existing path, first found) | Given the order of the branches, as defined at mount time or configured at runtime, act on the first one found where the relative path exists. |
| eplfs (existing path, least free space) | Of all the branches on which the relative path exists choose the branch with the least free space. |
| eplus (existing path, least used space) | Of all the branches on which the relative path exists choose the branch with the least used space. |
| epall (existing path, all) | For **mkdir**, **mknod**, and **symlink** it will apply to all found. **create** works like **epff** (but more expensive because it doesn't stop after finding a valid branch). |
| newest | Pick the file / directory with the largest mtime. |
| pfrd (percentage free random distribution) | Chooses a branch at random with the likelihood of selection based on a branch's available space relative to the total. |
| rand (random) | Calls **all** and then randomizes. Returns 1 branch. |
**NOTE:** If you are using an underlying filesystem that reserves
blocks such as ext2, ext3, or ext4 be aware that mergerfs respects the
@ -130,6 +135,7 @@ policy calculations. **df** does NOT use `f_bavail`, it uses
`f_bfree`, so direct comparisons between **df** output and mergerfs'
policies is not appropriate.
## Defaults
| Category | Policy |

20
mkdocs/docs/config/minfreespace.md Normal file
View file

@ -0,0 +1,20 @@
# minfreespace
default: `4G`
`minfreespace` is used to set a minimum free space threshold when
running create [policies](functions_categories_policies.md). Any
branch with free space less than the `minfreespace` value will be
skipped. This is the global default but individual branches can [have
their own value.](branches.md#minfreespace).
This is useful for a couple reasons.
* Since mergerfs does not split files across branches it is best to
leave space to write a newly created file on a branch to minimize
the risk of running out of space and needing
[moveonenospc](moveonenospc.md).
* Some filesystems' performance degrades when filled. `minfreespace`
provides a buffer so they are less likely to be filled.
* Similar to `ext4`'s reserved space option it minimizes the problems
that come from running out of space.

46
mkdocs/docs/config/moveonenospc.md Normal file
View file

@ -0,0 +1,46 @@
# moveonenospc
When writing to a file a [number of
errors](https://man7.org/linux/man-pages/man2/write.2.html#ERRORS) are
possible. The `ENOSPC` error indicates their is no room for the
data. That could be true due to the filesystem having actually no
available space for data, or because a secondary resource (such as
inodes) has been used up, or the filesystem might have a quota feature
that is limiting how much storage a particular user may use, or (as on
`ext4` there might be a feature which reserves space for privileged
processes.
Since mergerfs [does not offer](../index.md#non-features) splitting of
files across filesystems there are situations where a file is opened
or created on a filesystem which is nearly full and eventually
receives a `ENOSPC` error despite the pool having capacity. The
`moveonenospc` feature allows the user to have some control over this
situation.
When enabled and a `write` fails with `ENOSPC` or `EDQUOT` mergerfs
will:
1. Run the policy defined by `moveonenospc` to find a target branch.
2. ["Move"](../faq/technical_behavior_and_limitations.md#how-does-mergerfs-handle-moving-and-copying-of-files)
the file from the source branch to the target branch.
3. Retry the `write` and continue on as normal.
If at any point something fails the progress so far will be cleaned up
as appropriate and the original error returned.
If `moveonenospc` is disabled the underlying error will be returned.
NOTE: This feature has NO affect on policies. It ONLY applies to the
literal write function. If the create function returns `ENOSPC` or the
[policy returns `ENOSPC`](functions_categories_policies.md#filtering)
that error will be returned back to the application making the
`create` request.
## Additional Reading
* [Functions, Categories, Policies](functions_categories_policies.md)
* [Why do I get an "out of space" / "no space left on device" / ENOSPC
error even though there appears to be lots of space
available?](../faq/why_isnt_it_working.md#why-do-i-get-an-out-of-space-no-space-left-on-device-enospc-error-even-though-there-appears-to-be-lots-of-space-available)

17
mkdocs/docs/config/options.md
View file

@ -24,18 +24,19 @@ These options are the same regardless of whether you use them with the
key=val / ini style format.
- **[branches](branches.md)**: Colon delimited list of branches. Used
primarily in config file.
- **minfreespace=SIZE**: The minimum available space of a branch
necessary to be considered for a create
- **[minfreespace](minfreespace.md)=SIZE**: The minimum available
space of a branch necessary to be considered for a create
[policy](functions_categories_policies.md). This is a default value
applied to all branches and can be overwritten when configuring
[branches](branches.md). Understands 'K', 'M', and 'G' to represent
kilobyte, megabyte, and gigabyte respectively. (default: 4G)
- **moveonenospc=BOOL|POLICY**: When enabled if a **write** fails with
**ENOSPC** (no space left on device) or **EDQUOT** (disk quota
exceeded) the policy selected will run to find a new location for
the file. An attempt to move the file to that branch will occur
(keeping all metadata possible) and if successful the original is
unlinked and the write retried. (default: pfrd)
- **[moveonenospc](moveonenospc.md)=BOOL|POLICY**: When enabled if a
**write** fails with **ENOSPC** (no space left on device) or
**EDQUOT** (disk quota exceeded) the policy selected will run to
find a new location for the file. An attempt to move the file to
that branch will occur (keeping all metadata possible) and if
successful the original is unlinked and the write retried. (default:
pfrd)
- **[inodecalc](inodecalc.md)=passthrough|path-hash|devino-hash|hybrid-hash**:
Selects the inode calculation algorithm. (default: hybrid-hash)
- **dropcacheonclose=BOOL**: When a file is requested to be closed

22
mkdocs/docs/faq/have_you_considered.md Normal file
View file

@ -0,0 +1,22 @@
# "Have You Considered?"
## Have you considered limiting drive spinup?
Yes. See [Limiting Drive Spinup](limit_drive_spinup.md).
## Have you considered porting to MacOS?
Yes, but the FUSE implementation on MacOS has gotten a bit complicated
and fragmented. I'm not opposed to supporting it but given the low
demand, lack of the author having a modern MacOS system, the fact
mergerfs does not use standard
[libfuse](https://github.com/libfuse/libfuse) API, and MacOS FUSE
situation it is unlikely.
## Have you considered porting mergerfs to Windows (WinFsp)?
Similar to MacOS the demand is very low and mergerfs does not use the
[libfuse](https://github.com/libfuse/libfuse) library so porting to
WinFsp would first mean porting it to `libfuse`.

33
mkdocs/docs/faq/technical_behavior_and_limitations.md
View file

@ -84,39 +84,6 @@ an error back to the application making the request.
Should FUSE gain the ability mergerfs will be updated to support it.
## Why do I get an "out of space" / "no space left on device" / ENOSPC error even though there appears to be lots of space available?
First make sure you've read the sections above about policies, path
preservation, branch filtering, and the options `minfreespace`,
`moveonenospc`, `statfs`, and `statfs_ignore`.
mergerfs is simply presenting a union of the content within multiple
branches. The reported free space is an aggregate of space available
within the pool (behavior modified by `statfs` and
`statfs_ignore`). It does not represent a contiguous space. In the
same way that read-only filesystems, those with quotas, or reserved
space report the full theoretical space available.
Due to path preservation, branch tagging, read-only status, and
`minfreespace` settings it is perfectly valid that `ENOSPC` / "out of
space" / "no space left on device" be returned. It is doing what was
asked of it: filtering possible branches due to those settings. Only
one error can be returned and if one of the reasons for filtering a
branch was `minfreespace` then it will be returned as
such. `moveonenospc` is only relevant to writing a file which is too
large for the filesystem it's currently on.
It is also possible that the filesystem selected has run out of
inodes. Use `df -i` to list the total and available inodes per
filesystem.
If you don't care about path preservation then simply change the
`create` policy to one which isn't. `mfs` is probably what most are
looking for. The reason it's not default is because it was originally
set to `epmfs` and changing it now would change people's setup. Such a
setting change will likely occur in mergerfs 3.
## Why does the total available space in mergerfs not equal outside?
Are you using ext2/3/4? With reserve for root? mergerfs uses available

56
mkdocs/docs/faq/why_isnt_it_working.md
View file

@ -2,23 +2,22 @@
## I modified mergerfs' config but it still behaves the same.
mergerfs, like most filesystems, are given their options/arguments
at mount time. Unlike most filesystems, mergerfs also has the ability
to modify certain options at [runtime](../runtime_interfaces.md).
mergerfs, like other filesystems, are given their options/arguments at
mount time. You can not simply modify the [source of the
configuration](../quickstart.md#usage) and have those settings applied
any more than you would for other filesystems. It is the user's
responsibility to [restart](../setup/upgrade.md) mergerfs to pick up
the changes or use the [runtime interface](../runtime_interfaces.md).
That said: mergerfs does not actively try to monitor typical methods
of configuration (nor should it.) As such if changes are made to
`/etc/fstab`, a systemd unit file, etc. it will have no knowledge of
those changes. It is the user's responsibility to
[restart](../setup/upgrade.md) mergerfs to pick up the changes or use
the [runtime interface](../runtime_interfaces.md).
NOTE: the [runtime interface](../runtime_interfaces.md) is **just**
for runtime changes. It does **NOT** save those changed values
anywhere.
## Why are all my files ending up on 1 filesystem?!
Did you start with empty filesystems? Did you explicitly configure a
`category.create` policy? Are you using an `existing path` / `path
preserving` policy?
Did you start with empty filesystems? Are you using an `existing path`
policy?
The default create policy is `epmfs`. That is a path preserving
algorithm. With such a policy for `mkdir` and `create` with a set of
@ -37,6 +36,39 @@ and wish your files to be spread across all your filesystems change
restrictive [policy](../config/functions_categories_policies.md).
## Why do I get an "out of space" / "no space left on device" / ENOSPC error even though there appears to be lots of space available?
First make sure you've read the sections above about [policies, path
preservation, branch
filtering,](../config/functions_categories_policies.md) and the
options `minfreespace`, [moveonenospc](../config/moveonenospc.md),
[statfs](../config/statfs.md), and
[statfs_ignore](../config/statfs.md#statfs_ignore).
mergerfs is simply presenting a union of the content within multiple
branches. The reported free space is an aggregate of space available
within the pool (behavior modified by `statfs` and
`statfs_ignore`). It does not represent a contiguous space. In the
same way that read-only filesystems, those with quotas, or reserved
space report the full theoretical space available. Not the practical
usable space.
Due to using an `existing path` based policy, setting a [branch's
mode](../config/branches.md#branch-mode) to `NC` or `RO`, a
filesystems read-only status, and/or `minfreespace` setting it is
[perfectly
valid](../config/functions_categories_policies.md#filtering) that
`ENOSPC` / "out of space" / "no space left on device" be returned when
attempting to create a file despite there being actual space available
somewhere in the pool. It is doing what was asked of it: filtering
possible branches due to those settings. If that is not the behavior
you want you need to modify the settings accordingly.
It is also possible that the filesystem selected has run out of
inodes. Use `df -i` to list the total and available inodes per
filesystem.
## Why isn't the create policy working?
It probably is. The policies rather straight forward and well tested.

3
mkdocs/mkdocs.yml
View file

@ -63,8 +63,10 @@ nav:
- config/deprecated_options.md
- config/branches.md
- config/functions_categories_policies.md
- config/minfreespace.md
- config/func_readdir.md
- config/rename_and_link.md
- config/moveonenospc.md
- config/cache.md
- config/readahead.md
- config/inodecalc.md
@ -100,6 +102,7 @@ nav:
- faq/compatibility_and_integration.md
- faq/recommendations_and_warnings.md
- faq/technical_behavior_and_limitations.md
- faq/have_you_considered.md
- faq/limit_drive_spinup.md
- related_projects.md
- media_and_publicity.md