Browse Source

Misc doc updates (#1531)

pull/1532/head
trapexit 2 weeks ago
committed by GitHub
parent
commit
1707dc27e3
No known key found for this signature in database GPG Key ID: B5690EEEBB952194
  1. 7
      README.md
  2. 18
      mkdocs/docs/config/func_readdir.md
  3. 11
      mkdocs/docs/config/fuse_msg_size.md
  4. 14
      mkdocs/docs/faq/why_isnt_it_working.md
  5. 18
      mkdocs/docs/index.md
  6. 10
      mkdocs/docs/setup/installation.md

7
README.md

@ -25,6 +25,7 @@ etc.](https://trapexit.github.io/mergerfs/latest/project_comparisons/)
* Works with filesystems of [almost any
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
* [Hard links](https://trapexit.github.io/mergerfs/preview/faq/technical_behavior_and_limitations/#do-hard-links-work)
* Hard link [copy-on-write /
CoW](https://trapexit.github.io/mergerfs/latest/config/link_cow/)
* [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
may be applied to all instances found.
Read more about [policies
here](https://trapexit.github.io/mergerfs/latest/config/functions_categories_policies/).
The way in which mergerfs behaves is controlled by the
[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

18
mkdocs/docs/config/func_readdir.md

@ -1,10 +1,10 @@
# 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 it reads directory content.
`readdir` has policies to control how to read directory content.
| 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 | cosr:N:M with 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 | 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
`find` or `ls`, it is required to call `stat` on the file which is
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.

11
mkdocs/docs/config/fuse_msg_size.md

@ -1,13 +1,12 @@
# fuse_msg_size
* `fuse_msg_size=UINT|SIZE`
* Defaults to `1M`
* Performance improvements often peak at about `4M`
* type: `UINT|SIZE`
* default: `1M`
* example: `fuse_msg_size=1M`
* 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
size
* If the value is just an integer without a size multipler suffix then
it is treated as a page count
size. If the value is just an integer without a size multipler suffix
then it is treated as a page count
FUSE applications communicate with the kernel over a special character
device: `/dev/fuse`. A large portion of the overhead associated with

14
mkdocs/docs/faq/why_isnt_it_working.md

@ -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?
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
branches
* if using an `ep*`
[policy](../config/functions_categories_policies.md) there may not
be an available branch
* due to [branch modes](../config/branches.md#branch-mode) being set
to to `NC` or `RO` branches will be excluded from consideration
* using an `ep*` [policy](../config/functions_categories_policies.md)
and there may not be an available branch
* [branch modes](../config/branches.md#branch-mode) set to `NC` or
`RO` branches will be excluded from consideration
* if using `ext4` ensure you are not running into reserve limits (use
`tune2fs -m 0` to remove the reserve)
* 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
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.
theoretical space available but not the practical usable space.
## Why isn't the create policy working?

18
mkdocs/docs/index.md

@ -57,8 +57,9 @@ which branch will be selected for the creation.
For functions which change attributes or remove the file the behavior
may be applied to all instances found.
Read more about [policies
here](config/functions_categories_policies.md).
The way in which mergerfs behaves is controlled by the
[config/options/settings](config/options.md). More specifically by
[policies](config/functions_categories_policies.md).
### Visualization
@ -89,3 +90,16 @@ A + B = C
## Getting Started
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.

10
mkdocs/docs/setup/installation.md

@ -44,6 +44,16 @@ sudo dpkg -i mergerfs_<ver>.debian-<rel>_<arch>.deb
#### 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
sudo dpkg -i mergerfs_<ver>.ubuntu-<rel>_<arch>.deb

Loading…
Cancel
Save