mirror of
https://github.com/trapexit/mergerfs.git
synced 2026-11-19 22:46:34 -05:00
Misc doc updates (#1531)
This commit is contained in:
parent
c4126a0796
commit
1707dc27e3
6 changed files with 57 additions and 23 deletions
|
|
@ -25,6 +25,7 @@ etc.](https://trapexit.github.io/mergerfs/latest/project_comparisons/)
|
||||||
* Works with filesystems of [almost any
|
* Works with filesystems of [almost any
|
||||||
type](https://trapexit.github.io/mergerfs/latest/faq/compatibility_and_integration/#what-filesystems-can-be-used-as-branches)
|
type](https://trapexit.github.io/mergerfs/latest/faq/compatibility_and_integration/#what-filesystems-can-be-used-as-branches)
|
||||||
* Ignore read-only filesystems when creating files
|
* Ignore read-only filesystems when creating files
|
||||||
|
* [Hard links](https://trapexit.github.io/mergerfs/preview/faq/technical_behavior_and_limitations/#do-hard-links-work)
|
||||||
* Hard link [copy-on-write /
|
* Hard link [copy-on-write /
|
||||||
CoW](https://trapexit.github.io/mergerfs/latest/config/link_cow/)
|
CoW](https://trapexit.github.io/mergerfs/latest/config/link_cow/)
|
||||||
* [Runtime configurable](https://trapexit.github.io/mergerfs/latest/runtime_interface/)
|
* [Runtime configurable](https://trapexit.github.io/mergerfs/latest/runtime_interface/)
|
||||||
|
|
@ -59,8 +60,10 @@ which branch will be selected for the creation.
|
||||||
For functions which change attributes or remove the file the behavior
|
For functions which change attributes or remove the file the behavior
|
||||||
may be applied to all instances found.
|
may be applied to all instances found.
|
||||||
|
|
||||||
Read more about [policies
|
The way in which mergerfs behaves is controlled by the
|
||||||
here](https://trapexit.github.io/mergerfs/latest/config/functions_categories_policies/).
|
[config/options/settings](https://trapexit.github.io/mergerfs/latest/config/options). More
|
||||||
|
specifically by
|
||||||
|
[policies](https://trapexit.github.io/mergerfs/latest/config/functions_categories_policies/).
|
||||||
|
|
||||||
|
|
||||||
### Visualization
|
### Visualization
|
||||||
|
|
|
||||||
|
|
@ -1,10 +1,10 @@
|
||||||
# func.readdir
|
# func.readdir
|
||||||
|
|
||||||
Defaults to `seq`
|
* type: `STR`
|
||||||
|
* default: `seq`
|
||||||
|
* examples: `func.readdir=seq`, `func.readdir=cor:4`
|
||||||
|
|
||||||
Examples: `func.readdir=seq`, `func.readdir=cor:4`
|
`readdir` has policies to control how to read directory content.
|
||||||
|
|
||||||
`readdir` has policies to control how it reads directory content.
|
|
||||||
|
|
||||||
| Policy | Description |
|
| Policy | Description |
|
||||||
| ------ | ----------- |
|
| ------ | ----------- |
|
||||||
|
|
@ -12,7 +12,7 @@ Examples: `func.readdir=seq`, `func.readdir=cor:4`
|
||||||
| cosr:N:M | "concurrent open, sequential read" : Concurrently open branch directories using a thread pool and process them in the order defined in `branches`. This keeps memory and CPU usage low while also reducing the time spent waiting on branches to respond. `N` is the number of threads. If negative it will be the core count divided by `abs(N)`. `M` is the queue depth. If either value is `0` it will be decided based on system configuration. |
|
| cosr:N:M | "concurrent open, sequential read" : Concurrently open branch directories using a thread pool and process them in the order defined in `branches`. This keeps memory and CPU usage low while also reducing the time spent waiting on branches to respond. `N` is the number of threads. If negative it will be the core count divided by `abs(N)`. `M` is the queue depth. If either value is `0` it will be decided based on system configuration. |
|
||||||
| cosr:N | cosr:N:M with M = 0 |
|
| cosr:N | cosr:N:M with M = 0 |
|
||||||
| cosr | cosr:N:M with N = 0 and M = 0 |
|
| cosr | cosr:N:M with N = 0 and M = 0 |
|
||||||
| cor:N:M | "concurrent open and read" : Concurrently open branch directories and immediately start reading their contents using a thread pool. This will result in slightly higher memory and CPU usage but reduced latency. Particularly when using higher latency / slower speed network filesystem branches. Unlike `seq` and `cosr` the order of files could change due the async nature of the thread pool. This should not be a problem since the order of files listed in not guaranteed. `N` is the number of threads. If negative it will be the core count divided by `abs(N)`. `M` is the queue depth. If either value is `0` it will be decided based on system configuration. |
|
| cor:N:M | "concurrent open and read" : Concurrently open branch directories and immediately start reading their contents using a thread pool. This will result in slightly higher memory and CPU usage but reduced latency. Particularly when using higher latency / slower speed network filesystem branches. Unlike `seq` and `cosr` the order of files could change due the async nature of the thread pool. This should not be a problem since the order of files returned in not guaranteed. `N` is the number of threads. If negative it will be the core count divided by `abs(N)`. `M` is the queue depth. If either value is `0` it will be decided based on system configuration. |
|
||||||
| cor:N | cosr:N:M with M = 0 |
|
| cor:N | cosr:N:M with M = 0 |
|
||||||
| cor | cosr:N:M with N = 0 and M = 0 |
|
| cor | cosr:N:M with N = 0 and M = 0 |
|
||||||
|
|
||||||
|
|
@ -21,3 +21,11 @@ in a directory and possibly some basic metadata about said files. To
|
||||||
know details about the files, as one would see from commands like
|
know details about the files, as one would see from commands like
|
||||||
`find` or `ls`, it is required to call `stat` on the file which is
|
`find` or `ls`, it is required to call `stat` on the file which is
|
||||||
controlled by `fuse.getattr`.
|
controlled by `fuse.getattr`.
|
||||||
|
|
||||||
|
Until Linux v6.16, despite being able to change the size of FUSE
|
||||||
|
messages, `readdir` requests were limited to 1 page (4KiB) in size per
|
||||||
|
message. This limitation limited throughput and therefore performance
|
||||||
|
of the `readdir` call. In v6.16 that was changed to be able to grow to
|
||||||
|
the [fuse_msg_size](fuse_msg_size.md) which allows a lot more data to
|
||||||
|
be sent per request and therefore much better performance in certain
|
||||||
|
situations.
|
||||||
|
|
|
||||||
|
|
@ -1,13 +1,12 @@
|
||||||
# fuse_msg_size
|
# fuse_msg_size
|
||||||
|
|
||||||
* `fuse_msg_size=UINT|SIZE`
|
* type: `UINT|SIZE`
|
||||||
* Defaults to `1M`
|
* default: `1M`
|
||||||
* Performance improvements often peak at about `4M`
|
* example: `fuse_msg_size=1M`
|
||||||
* If the value is a `SIZE` in the form of `xB`, `xK`, `xM`, `xG`, or
|
* If the value is a `SIZE` in the form of `xB`, `xK`, `xM`, `xG`, or
|
||||||
`xT` then it will choose the closest multiple of the system page
|
`xT` then it will choose the closest multiple of the system page
|
||||||
size
|
size. If the value is just an integer without a size multipler suffix
|
||||||
* If the value is just an integer without a size multipler suffix then
|
then it is treated as a page count
|
||||||
it is treated as a page count
|
|
||||||
|
|
||||||
FUSE applications communicate with the kernel over a special character
|
FUSE applications communicate with the kernel over a special character
|
||||||
device: `/dev/fuse`. A large portion of the overhead associated with
|
device: `/dev/fuse`. A large portion of the overhead associated with
|
||||||
|
|
|
||||||
|
|
@ -36,15 +36,15 @@ and [FAQ](configuration_and_policies.md) for policy recommendations.
|
||||||
|
|
||||||
## 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?
|
## 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?
|
||||||
|
|
||||||
One or multiple of the below are likely causing branches
|
One or multiple of the below are likely causing branches to be
|
||||||
|
[filtered out](../config/functions_categories_policies.md#filtering).
|
||||||
|
|
||||||
* [minfreespace](../config/minfreespace.md) could be filtering out
|
* [minfreespace](../config/minfreespace.md) could be filtering out
|
||||||
branches
|
branches
|
||||||
* if using an `ep*`
|
* using an `ep*` [policy](../config/functions_categories_policies.md)
|
||||||
[policy](../config/functions_categories_policies.md) there may not
|
and there may not be an available branch
|
||||||
be an available branch
|
* [branch modes](../config/branches.md#branch-mode) set to `NC` or
|
||||||
* due to [branch modes](../config/branches.md#branch-mode) being set
|
`RO` branches will be excluded from consideration
|
||||||
to to `NC` or `RO` branches will be excluded from consideration
|
|
||||||
* if using `ext4` ensure you are not running into reserve limits (use
|
* if using `ext4` ensure you are not running into reserve limits (use
|
||||||
`tune2fs -m 0` to remove the reserve)
|
`tune2fs -m 0` to remove the reserve)
|
||||||
* it is possible that the filesystem selected by the policy has run
|
* it is possible that the filesystem selected by the policy has run
|
||||||
|
|
@ -56,7 +56,7 @@ within the pool (behavior modified by [statfs](../config/statfs.md)
|
||||||
and [statfs_ignore](../config/statfs.md#statfs_ignore)). It does not
|
and [statfs_ignore](../config/statfs.md#statfs_ignore)). It does not
|
||||||
represent a contiguous space. In the same way that read-only
|
represent a contiguous space. In the same way that read-only
|
||||||
filesystems, those with quotas, or reserved space report the full
|
filesystems, those with quotas, or reserved space report the full
|
||||||
theoretical space available. Not the practical usable space.
|
theoretical space available but not the practical usable space.
|
||||||
|
|
||||||
|
|
||||||
## Why isn't the create policy working?
|
## Why isn't the create policy working?
|
||||||
|
|
|
||||||
|
|
@ -57,8 +57,9 @@ which branch will be selected for the creation.
|
||||||
For functions which change attributes or remove the file the behavior
|
For functions which change attributes or remove the file the behavior
|
||||||
may be applied to all instances found.
|
may be applied to all instances found.
|
||||||
|
|
||||||
Read more about [policies
|
The way in which mergerfs behaves is controlled by the
|
||||||
here](config/functions_categories_policies.md).
|
[config/options/settings](config/options.md). More specifically by
|
||||||
|
[policies](config/functions_categories_policies.md).
|
||||||
|
|
||||||
|
|
||||||
### Visualization
|
### Visualization
|
||||||
|
|
@ -89,3 +90,16 @@ A + B = C
|
||||||
## Getting Started
|
## Getting Started
|
||||||
|
|
||||||
Head to the [quick start guide](quickstart.md).
|
Head to the [quick start guide](quickstart.md).
|
||||||
|
|
||||||
|
|
||||||
|
## About This Documentation
|
||||||
|
|
||||||
|
* Like the software the documentation changes over time. Ensure that
|
||||||
|
you are reading the documentation related to the version of the
|
||||||
|
software you are using.
|
||||||
|
* The documentation is explicit, literal, and reasonably thorough. If
|
||||||
|
a suspected feature is not mentioned it does not exist. Do not read
|
||||||
|
into the wording. What is described is how it functions. If you feel
|
||||||
|
like something is not explained sufficiently or missing please [ask
|
||||||
|
in one of the supported forums](support.md#contact-issue-submission)
|
||||||
|
and the docs will be updated.
|
||||||
|
|
|
||||||
|
|
@ -44,6 +44,16 @@ sudo dpkg -i mergerfs_<ver>.debian-<rel>_<arch>.deb
|
||||||
|
|
||||||
#### Ubuntu
|
#### Ubuntu
|
||||||
|
|
||||||
|
Given non-LTS releases are rarely used for servers and only have [9
|
||||||
|
months of support](https://ubuntu.com/about/release-cycle) we do not
|
||||||
|
build packages for them by default. It is recommended that you first
|
||||||
|
try the `deb` file for the LTS release most closely related to your
|
||||||
|
non-LTS release. If that does not work you can use the [static
|
||||||
|
build](#static-linux-binaries) or [file a
|
||||||
|
ticket](https://github.com/trapexit/mergerfs/issues) requesting a
|
||||||
|
package built.
|
||||||
|
|
||||||
|
|
||||||
```
|
```
|
||||||
wget https://github.com/trapexit/mergerfs/releases/download/<version>/mergerfs_<ver>.ubuntu-<rel>_<arch>.deb
|
wget https://github.com/trapexit/mergerfs/releases/download/<version>/mergerfs_<ver>.ubuntu-<rel>_<arch>.deb
|
||||||
sudo dpkg -i mergerfs_<ver>.ubuntu-<rel>_<arch>.deb
|
sudo dpkg -i mergerfs_<ver>.ubuntu-<rel>_<arch>.deb
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue