From 1707dc27e3fc73b6cdd155cad1ab64ad60b2f000 Mon Sep 17 00:00:00 2001 From: trapexit Date: Sun, 21 Sep 2025 15:25:24 -0400 Subject: [PATCH] Misc doc updates (#1531) --- README.md | 7 +++++-- mkdocs/docs/config/func_readdir.md | 18 +++++++++++++----- mkdocs/docs/config/fuse_msg_size.md | 13 ++++++------- mkdocs/docs/faq/why_isnt_it_working.md | 14 +++++++------- mkdocs/docs/index.md | 18 ++++++++++++++++-- mkdocs/docs/setup/installation.md | 10 ++++++++++ 6 files changed, 57 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index e59b89d8..68a75a4d 100644 --- a/README.md +++ b/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 diff --git a/mkdocs/docs/config/func_readdir.md b/mkdocs/docs/config/func_readdir.md index d218fd7b..6ea16b49 100644 --- a/mkdocs/docs/config/func_readdir.md +++ b/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. diff --git a/mkdocs/docs/config/fuse_msg_size.md b/mkdocs/docs/config/fuse_msg_size.md index 11c007d7..18967b83 100644 --- a/mkdocs/docs/config/fuse_msg_size.md +++ b/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 +`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 FUSE applications communicate with the kernel over a special character device: `/dev/fuse`. A large portion of the overhead associated with diff --git a/mkdocs/docs/faq/why_isnt_it_working.md b/mkdocs/docs/faq/why_isnt_it_working.md index 586dca9d..d17788ca 100644 --- a/mkdocs/docs/faq/why_isnt_it_working.md +++ b/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? diff --git a/mkdocs/docs/index.md b/mkdocs/docs/index.md index f9940188..10ef60c5 100644 --- a/mkdocs/docs/index.md +++ b/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. diff --git a/mkdocs/docs/setup/installation.md b/mkdocs/docs/setup/installation.md index 8c14ce55..bc9b8f44 100644 --- a/mkdocs/docs/setup/installation.md +++ b/mkdocs/docs/setup/installation.md @@ -44,6 +44,16 @@ sudo dpkg -i mergerfs_.debian-_.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//mergerfs_.ubuntu-_.deb sudo dpkg -i mergerfs_.ubuntu-_.deb