Misc documentation updates (#1605)

mkdocs/docs/faq/compatibility_and_integration.md

@@ -31,7 +31,7 @@ level API.
 Windows, while used for NAS systems more often than MacOS, is still
 relatively uncommon when compared to Linux. [Drive
 Pool](../project_comparisons.md#stablebits-drivepool) is a good
-alternative.
+alternative. It may also be possible to use mergerfs with WSL.
 
 
 ## What filesystems can be used as branches?
@@ -39,10 +39,11 @@ alternative.
 ext4, btrfs, xfs, f2fs, zfs, nfs, etc.
 
 Most any filesystem should work but there could be issues with
-non-POSIX compliant filesystems such as vfat, ntfs, cifs, exfat,
-etc. When directories need to be created or files moved by mergerfs if
-the filesystem returns errors due to not supporting certain POSIX
-filesystem features it could result in the core functions failing.
+non-POSIX compliant filesystems such as nfs (w/ root squashing), vfat,
+ntfs, cifs, exfat, etc. When directories need to be created or files
+moved by mergerfs if the filesystem returns errors due to not
+supporting certain POSIX filesystem features it could result in the
+core functions failing.
 
 Since mergerfs is not generally used with non-POSIX filesystems this
 has not been a problem for users and there are some checks for known
@@ -51,6 +52,13 @@ filesystem results in issues please [file a
 ticket](https://github.com/trapexit/mergerfs/issues) with the details.
 
 
+## What types of storage devices does mergerfs work with?
+
+Since mergerfs works at the filesystem level rather than device level
+there is no compatibility concerns based on the physical storage
+devices involved.
+
+
 ## Can I use mergerfs without SnapRAID? SnapRAID without mergerfs?
 
 [https://www.snapraid.it](https://www.snapraid.it)
@@ -85,7 +93,7 @@ pool.
 ## Can mergerfs run via Docker, Podman, Kubernetes, etc.
 
 Yes. [See installation
-page.](../setup/installation.md##podman-docker-oci-containers)
+page.](../setup/installation.md#podman-docker-oci-containers)
 
 
 ## How does mergerfs interact with user namespaces?

mkdocs/docs/faq/technical_behavior_and_limitations.md

@@ -68,6 +68,11 @@ underlying data. For more details as to why that is see the docs on
 [inodecalc](../config/inodecalc.md).
 
 
+## Are there any size limitations to files, directories, etc.?
+
+Whatever the limits are of the underlying filesystems.
+
+
 ## Do reflink, FICLONE, or FICLONERANGE work?
 
 Unfortunately not. FUSE, the technology mergerfs is based on, does not

mkdocs/docs/index.md

@@ -2,40 +2,43 @@
 
 **mergerfs** is a [union
 filesystem](https://en.wikipedia.org/wiki/Union_mount) that makes
-multiple storage devices or filesystems appear as a single unified
-directory. Built on [FUSE (Filesystem in
-Userspace)](https://en.wikipedia.org/wiki/Filesystem_in_Userspace), it
-is designed to simplify how you manage files across several
-independent filesystems without the complexity, fragility, or cost of
-RAID or similar storage aggregation technologies.
-
-Think of mergerfs as a smart pooling layer: you can combine any number
-of [existing
-filesystems](faq/usage_and_functionality.md#can-mergerfs-be-used-with-filesystems-which-already-have-data)
-— whether they are on hard drives, SSDs, network shares, or other
-mounted storage — into what looks like one large filesystem, while
+multiple filesystems and/or directories appear as a single unified
+directory. mergerfs is designed to simplify how you manage files
+across multiple independent filesystems without the complexity,
+fragility, or cost of RAID or similar storage aggregation
+technologies.
+
+mergerfs as a smart pooling layer allows you to combine any number of
+[existing
+filesystems](faq/usage_and_functionality.md#can-mergerfs-be-used-with-filesystems-which-already-have-data);
+whether they are on hard drives, SSDs, network shares, or other
+mounted storage; into what looks like one large filesystem, while
 still maintaining direct access to each individual filesystem. Unlike
-RAID, there's no rebuild process if a device fails. You only lose the
-files that were on that specific filesystem. You can also add or
-remove filesystems at any time without restructuring your entire pool.
+RAID, there's no rebuild process if a device fails. You only lose
+those files that were on that specific filesystem. You can also add or
+remove filesystems at any time without restructuring the pool.
 
 mergerfs excels at cost-effective storage expansion, making it ideal
 for media libraries, backups, archival data, and other write-sometimes,
 read-often workloads where you need lots of space but don't want
-the overhead of traditional storage technologies.
+the overhead of traditional storage aggregation technologies.
 
 **Key advantages:**
 
-* Mix and match filesystems of any size, type, or underlying device
+* Mix and match filesystems of any size,
+  [type](faq/compatibility_and_integration.md#what-filesystems-can-be-used-as-branches),
+  or [underlying
+  device](faq/compatibility_and_integration.md#what-types-of-storage-devices-does-mergerfs-work-with)
 * No parity calculations or rebuild times
+* Does not require hard drives to be spinning if not in use
 * Add or remove filesystems on the fly
-* Direct access to files on individual filesystems when needed
-* Flexible policies for controlling where new files are created
+* [Direct access to files](faq/usage_and_functionality.md#can-filesystems-still-be-used-directly-outside-of-mergerfs-while-pooled) on individual filesystems when needed
+* Flexible [policies](config/functions_categories_policies.md) for controlling where new files are created
 
 For users seeking alternatives to mhddfs, unionfs, aufs, or DrivePool,
 mergerfs offers a mature, actively maintained solution with extensive
 configuration options and documentation. See the [project comparisons
-for more comparisons.](project_comparisons.md)
+for more details.](project_comparisons.md)
 
 
 ## Features
@@ -71,13 +74,14 @@ for more comparisons.](project_comparisons.md)
 * File whiteout
 * Splitting of files across branches
 * Active rebalancing of content
+* [Actively attempt to keep hard drives spun down](faq/limit_drive_spinup.md)
 
 
 ## How it works
 
 mergerfs logically merges multiple filesystem paths together. Not
 block devices, not filesystem mounts, just paths. It acts as a proxy
-to the underlying filesystem paths. Combining the behaviors of some
+to the underlying filesystem. Combining the behaviors of some
 functions and being a selector for others.
 
 When the contents of a directory are requested mergerfs combines the
@@ -138,3 +142,6 @@ Head to the [quick start guide](quickstart.md).
 * The search feature of MkDocs is not great. Searching for "literal
   strings" will generally not work. Alernative solutions are being
   investigated.
+* While not intended for end users nor completely accurate some might
+  find the AI generated docs at https://deepwiki.com/trapexit/mergerfs
+  interesting or useful.

mkdocs/docs/performance.md

@@ -1,15 +1,17 @@
 # Tweaking Performance
 
-`mergerfs` is effectively a filesystem proxy and therefore its
+**mergerfs** is effectively a filesystem proxy and therefore its
 theoretical max performance is that of the underlying devices
 (ignoring caching performed by the kernel.) However, given it is a
-FUSE based filesystem working from userspace there is an increase in
-overhead relative to kernel based solutions. That said the performance
-can match the theoretical max but it depends greatly on the system's
+FUSE based filesystem working from userspace and it must combine the
+behavior and information from multiple underlying branches there can
+be an increase in overhead relative to other solutions. That said the
+performance of certain functions, such as IO, can match the
+theoretical max but it depends greatly on the system's
 configuration. There are many things which can impact
 performance. Device speeds and latency, network speeds and latency,
-concurrency and parallel limits of the hardware, read/write sizes,
-etc.
+concurrency and parallel limits of the hardware, read/write sizes, the
+number of branches, etc.
 
 While some settings can impact performance they are all **functional**
 in nature. Meaning they change mergerfs' behavior in some way. As a
@@ -27,7 +29,7 @@ before changing them to understand how functionality will change.
 * enable [passthrough.io](config/passthrough.md) (likely to have the
   biggest impact)
 * change read or process [thread pools](config/threads.md)
-* toggle [func.readdir](config/func_readdir.md)
+* change [func.readdir](config/func_readdir.md)
 * increase [readahead](config/readahead.md): `readahead=1024`
 * disable `security-capability` and/or [xattr](config/xattr.md)
 * increase cache timeouts [cache.attr](config/cache.md#cacheattr),

mkdocs/docs/project_comparisons.md

@@ -7,11 +7,13 @@ There are no solutions, only trade-offs.
 
 * [https://romanrm.net/mhddfs](https://romanrm.net/mhddfs)
 
+mhddfs is, like mergerfs, a FUSE based filesystem which can pool
+multiple filesystems together.
+
 mhddfs had not been updated in over a decade and has known stability
 and security issues. mergerfs provides a super set of mhddfs' features
-and offers better performance. In fact, as of 2020, the author of
-mhddfs has [moved to using
-mergerfs.](https://romanrm.net/mhddfs#update)
+and offers better performance. As of 2020 the author of mhddfs has
+[moved to using mergerfs.](https://romanrm.net/mhddfs#update)
 
 Below is an example of mhddfs and mergerfs setup to work similarly.
 
@@ -25,14 +27,18 @@ Below is an example of mhddfs and mergerfs setup to work similarly.
 * [https://aufs.sourceforge.net](https://aufs.sourceforge.net)
 * [https://en.wikipedia.org/wiki/Aufs](https://en.wikipedia.org/wiki/Aufs)
 
+aufs, another union filesystem, is a kernel based overlay filesystem
+with basic file creation placement policies.
+
 While aufs still is maintained it failed to be included in the
 mainline kernel and is no longer available in most Linux distros
 making it harder to get installed for the average user.
 
 While aufs can often offer better peak performance due to being
-primarily kernel based, mergerfs provides more configurability and is
-generally easier to use. mergerfs however does not offer the overlay /
-copy-on-write (CoW) features which aufs has.
+primarily kernel based (at least when `passthrough.io` is disabled),
+mergerfs provides more configurability and is generally easier to
+use. mergerfs however does not offer the overlay / copy-on-write (CoW)
+features which aufs has.
 
 
 ## unionfs
@@ -40,7 +46,7 @@ copy-on-write (CoW) features which aufs has.
 * [https://unionfs.filesystems.org](https://unionfs.filesystems.org)
 
 unionfs for Linux is a "stackable unification file system" which
-functions like many other union filesystems. unionfs has not been
+functions like many other union filesystems. unionfs is no longer
 maintained and was last released for Linux v3.14 back in 2014.
 
 Documentation is sparse so a comparison of features is not possible
@@ -101,7 +107,7 @@ aggregate their storage. The failure of any one device will have no
 impact on the other devices. The downside to mergerfs' technique is
 the fact you don't actually have contiguous space as large as if you
 used those other technologies. Meaning you can't create a file greater
-than 1TB on a pool of 2 1TB filesystems.
+than 1TB on a pool of two 1TB filesystems.
 
 
 ## BTRFS Single Data Profile
@@ -118,15 +124,20 @@ some abilities to recover data but this is not guaranteed.
 * [RAID5](https://en.wikipedia.org/wiki/Standard_RAID_levels#RAID_5)
 * [RAID6](https://en.wikipedia.org/wiki/Standard_RAID_levels#RAID_6)
 
+RAID5, RAID6, and similar technologies aggregate multiple devices at
+the block level and offer 1 or more live parity calculations that can
+allow the pool to continue to run should 1 device fail and rebuild the
+data once the device is replaced.
+
 mergerfs offers no parity or redundancy features so in that regard the
 technologies are not comparable. [SnapRAID](https://www.snapraid.it)
-can be used in combination with mergerfs to provide redundancy. Unlike
-traditional RAID5 or RAID6 SnapRAID works with drives of different
-sizes and can have more than 2 parity drives. However, parity
-calculations are not done in real-time.
+or [nonraid](https://github.com/qvr/nonraid) can be used in
+combination with mergerfs to provide redundancy. Unlike traditional
+RAID5 or RAID6 SnapRAID works with drives of different sizes and can
+have more than 2 parity drives. However, parity calculations are not
+done in real-time. However, nonraid is realtime.
 
-See [https://www.snapraid.it/compare](https://www.snapraid.it/compare)
-for more details and comparisons.
+For more details and comparison of SnapRAID to related technologies see [https://www.snapraid.it/compare](https://www.snapraid.it/compare).
 
 
 ## UnRAID
@@ -141,7 +152,9 @@ calculation can have higher peak performance. Some users also prefer
 an open source solution.
 
 For semi-static data mergerfs + [SnapRAID](http://www.snapraid.it)
-provides a similar, but not real-time, solution.
+provides a similar, but not real-time, solution. NonRAID (see below)
+is a fork of UnRAID's parity calculation solution and can also be used
+with mergerfs.
 
 
 ## NonRAID
@@ -163,6 +176,9 @@ be used with mergerfs for those looking for a unified view.
 
 * [https://en.wikipedia.org/wiki/ZFS](https://en.wikipedia.org/wiki/ZFS)
 
+ZFS is an advanced filesystem with many features including RAID5/6
+like redundency.
+
 mergerfs is very different from ZFS. mergerfs is intended to provide
 flexible pooling of arbitrary filesystems (local or remote), of
 arbitrary sizes, and arbitrary filesystems. Particularly in `write
@@ -173,6 +189,10 @@ can introduce a number of costs and limitations as described
 [here](https://markmcb.com/2020/01/07/five-years-of-btrfs/), and
 [here](https://utcc.utoronto.ca/~cks/space/blog/solaris/ZFSWhyNoRealReshaping).
 
+That said given mergerfs' flexibility it is common to see it used in
+combination with ZFS where critical data is written to a RAIDZ pool
+and bulk media stored on traditional filesystems pooled via mergerfs.
+
 
 ## ZFS AnyRAID
 
@@ -191,9 +211,9 @@ and there are no timelines or estimates for when it may be released.
 
 * [https://stablebit.com](https://stablebit.com)
 
-DrivePool works only on Windows so not as common an alternative as
-other Linux solutions. If you want to use Windows then DrivePool is a
-good option. Functionally the two projects work a bit
+DrivePool is a commercial filesystem pooling technology for
+Windows. If you are looking to use Windows then DrivePool is a good
+option. Functionally the two projects work a bit
 differently. DrivePool always writes to the filesystem with the most
 free space and later rebalances. mergerfs does not currently offer
 rebalance but chooses a branch at file/directory create
@@ -202,15 +222,12 @@ and has file pattern matching to further customize the
 behavior. mergerfs, not having rebalancing does not have these
 features, but similar features are planned for mergerfs v3. DrivePool
 has builtin file duplication which mergerfs does not natively support
-(but can be done via an external script.)
+(but can be done via an external program.)
 
 There are a lot of misc differences between the two projects but most
 features in DrivePool can be replicated with external tools in
 combination with mergerfs.
 
-Additionally, DrivePool is a closed source commercial product vs
-mergerfs a ISC licensed open source project.
-
 
 ## Plan9 binds
 
@@ -218,10 +235,10 @@ mergerfs a ISC licensed open source project.
 
 Plan9 has the native ability to bind multiple paths/filesystems
 together to create a setup similar to simplified union
-filesystem. Such bind mounts choose files in a "first found" in the
-order they are listed similar to mergerfs' `ff` policy. Similar, when
-creating a file it will be created on the first directory in the
-union.
+filesystem. Such bind mounts choose files in a "first found" manner
+based on the order they are configured similar to mergerfs' `ff`
+policy. Similarly, when creating a file it will be created on the
+first directory in the union.
 
 Plan 9 isn't a widely used OS so this comparison is mostly academic.
 

mkdocs/docs/tips_notes.md

@@ -6,7 +6,7 @@
   like something is not explained sufficiently please [file a
   ticket.](https://github.com/trapexit/mergerfs/issues)
 * If a `libfuse` argument is not listed it probably shouldn't be used
-  and are unsupported.
+  and is unsupported.
 * Ensure you're using the latest version. Especially before submitting
   bug reports.
 * Run mergerfs as `root`. mergerfs is designed and intended to be run
@@ -15,7 +15,7 @@
   seem to skip branches, you get strange permission errors, etc. be
   sure the underlying filesystems' permissions are all the same. Use
   `mergerfs.fsck` to audit the filesystem for out of sync permissions.
-* If you still have permission issues be sure you are using POSIX ACL
+* If you still have permission issues be sure you are using POSIX
   compliant filesystems. mergerfs doesn't generally make exceptions
   for FAT, NTFS, or other non-POSIX filesystem.
 * Unless using Linux v6.6 or above do **not** use `cache.files=off` if