Merge pull request #1425 from trapexit/docs-tips

Misc doc updates

mkdocs/docs/config/rename_and_link.md

@@ -9,9 +9,9 @@ handled.
 
 `rename` and `link` are arguably the most complicated functions to
 create in a union filesystem. `rename` only works within a single
-filesystem or device. If a rename can't be done due to the source and
-destination paths existing on different mount points it will return
-**-1** with **errno = EXDEV** (cross device / improper link). So if a
+filesystem or device. If a `rename` can not be done due to the source
+and destination paths existing on different mount points it will
+return an error (EXDEV, cross device / improper link). So if a
 `rename`'s source and target are on different filesystems within the
 pool it creates an issue.
 
@@ -24,31 +24,32 @@ v1.20.3 and prior, Finder / CIFS/SMB client in Apple OSX 10.9+,
 NZBGet, Samba's recycling bin feature.
 
 As a result a compromise was made in order to get most software to
-work while still obeying mergerfs' policies. Below is the basic logic.
+work while still obeying mergerfs' policies. The behavior is explained
+below.
 
 * If using a **create** policy which tries to preserve directory paths (epff,eplfs,eplus,epmfs)
-  * Using the **rename** policy get the list of files to rename
-  * For each file attempt rename:
-    * If failure with ENOENT (no such file or directory) run **create** policy
-    * If create policy returns the same branch as currently evaluating then clone the path
-    * Re-attempt rename
-  * If **any** of the renames succeed the higher level rename is considered a success
-  * If **no** renames succeed the first error encountered will be returned
-  * On success:
-    * Remove the target from all branches with no source file
-    * Remove the source from all branches which failed to rename
+    * Using the **rename** policy get the list of files to rename
+    * For each file attempt rename:
+        * If failure with ENOENT (no such file or directory) run **create** policy
+        * If create policy returns the same branch as currently evaluating then clone the path
+        * Re-attempt rename
+    * If **any** of the renames succeed the higher level rename is considered a success
+    * If **no** renames succeed the first error encountered will be returned
+    * On success:
+      * Remove the target from all branches with no source file
+      * Remove the source from all branches which failed to rename
 * If using a **create** policy which does **not** try to preserve directory paths
-  * Using the **rename** policy get the list of files to rename
-  * Using the **getattr** policy get the target path
-  * For each file attempt rename:
-    * If the source branch != target branch:
-      * Clone target path from target branch to source branch
-    * Rename
-  * If **any** of the renames succeed the higher level rename is considered a success
-  * If **no** renames succeed the first error encountered will be returned
-  * On success:
-    * Remove the target from all branches with no source file
-    * Remove the source from all branches which failed to rename
+    * Using the **rename** policy get the list of files to rename
+    * Using the **getattr** policy get the target path
+    * For each file attempt rename:
+      * If the source branch != target branch:
+        * Clone target path from target branch to source branch
+      * rename
+    * If **any** of the renames succeed the higher level rename is considered a success
+    * If **no** renames succeed the first error encountered will be returned
+    * On success:
+      * Remove the target from all branches with no source file
+      * Remove the source from all branches which failed to rename
 
 The removals are subject to normal entitlement checks. If the unlink
 fails it will fail silently.

mkdocs/docs/faq/compatibility_and_integration.md

@@ -1,5 +1,22 @@
 # Compatibility and Integration
 
+## What filesystems can be used as branches?
+
+ext4, btrfs, xfs, f2fs, zfs, nfs, etc.
+
+On the surface 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.
+
+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
+edgecases but it is possible some are not accounted for. If use with a
+filesystem results in issues please [file a
+ticket](https://github.com/trapexit/mergerfs/issues) with the details.
+
+
 ## Can I use mergerfs without SnapRAID? SnapRAID without mergerfs?
 
 Yes. They are completely unrelated pieces of software that just happen
@@ -52,7 +69,7 @@ given the complication it introduces.
 ## Can mergerfs be used with NFS root squash?
 
 If mergerfs is pooling a NFS mount then root squash should be disabled
-as mergerfs needs to be able to have elevated privilages to do what it
+as mergerfs needs to be able to have elevated privileges to do what it
 does.
 
 If you are exporting mergerfs over NFS then it is not really necessary.

mkdocs/docs/performance.md

@@ -21,20 +21,24 @@ NOTE: Be sure to [read about these features](config/options.md) before
 changing them to understand how functionality will change.
 
 * test theoretical performance using `nullrw` or mounting a ram disk
-* increase readahead: `readahead=1024`
+* change read or process [thread pools](config/threads.md)
+* change [func.readdir](config/func_readdir.md)
+* increase [readahead](config/readahead.md): `readahead=1024`
 * disable `security_capability` and/or `xattr`
-* increase cache timeouts `cache.attr`, `cache.entry`, `cache.negative_entry`
-* enable (or disable) page caching (`cache.files`)
+* increase cache timeouts [cache.attr](config/cache.md#cacheattr),
+  [cache.entry](config/cache.md#cacheentry),
+  [cache.negative_entry](config/cache.md#cachenegative_entry)
+* enable (or disable) page caching ([cache.files](config/cache.md#cachefiles))
 * enable `parallel-direct-writes`
-* enable `cache.writeback`
-* enable `cache.statfs`
-* enable `cache.symlinks`
-* enable `cache.readdir`
-* change the number of threads available
+* enable [cache.writeback](config/cache.md#cachewriteback)
+* enable [cache.statfs](config/cache.md#cachestatfs)
+* enable [cache.symlinks](config/cache.md#cachesymlinks)
+* enable [cache.readdir](config/cache.md#cachereaddir)
 * disable `posix_acl`
 * disable `async_read`
-* use `symlinkify` if your data is largely static and read-only
-* use tiered cache devices
+* use [symlinkify](config/symlinkify.md) if your data is largely
+  static and read-only
+* use [tiered cache](usage_patterns.md) devices
 * use LVM and LVM cache to place a SSD in front of your HDDs
 
 If you come across a setting that significantly impacts performance

mkdocs/docs/project_comparisons.md

@@ -101,6 +101,22 @@ used those other technologies. Meaning you can't create a file greater
 than 1TB on a pool of 2 1TB filesystems.
 
 
+## RAID5, RAID6
+
+* [RAID5](https://en.wikipedia.org/wiki/Standard_RAID_levels#RAID_5)
+* [RAID6](https://en.wikipedia.org/wiki/Standard_RAID_levels#RAID_6)
+
+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.
+
+See [https://www.snapraid.it/compare](https://www.snapraid.it/compare)
+for more details and comparisons.
+
+
 ## UnRAID
 
 * [https://unraid.net](https://unraid.net)
@@ -112,7 +128,7 @@ mergerfs offers more features and due to the lack of real-time parity
 calculation can have higher peak performance. Some users also prefer
 an open source solution.
 
-For semi-static data mergerfs + [SnapRaid](http://www.snapraid.it)
+For semi-static data mergerfs + [SnapRAID](http://www.snapraid.it)
 provides a similar, but not real-time, solution.
 
 
@@ -168,3 +184,23 @@ 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.
+
+
+## SnapRAID pooling
+
+[SnapRAID](https://www.snapraid.it/manual) has a pooling feature which
+creates "a read-only virtual view of all the files in your array using
+symbolic links."
+
+As mentioned in the description this "view" is just the creation of
+the same directory layout with symlinks to all files. This means that
+reads (and writes) to files are at native speeds but limited in that
+it can not practically be used as a target for writing new files and
+is only updated when `snapraid pool` is run. Note that some software
+treat symlinks differently than regular files. For instance some
+backup software will skip symlinks by default.
+
+mergerfs has the feature [symlinkify](config/symlinkify.md) which
+provides a similar behavior but is more flexible in that it is not
+read-only. That said there can still be some software that won't like
+that kind of setup.

mkdocs/docs/tips_notes.md

@@ -1,8 +1,12 @@
 # Tips and Notes
 
-* This document is literal and reasonably thorough. If a suspected
-  feature isn't mentioned it doesn't exist. If certain `libfuse`
-  arguments aren't listed they probably shouldn't be used.
+* 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 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.
 * Ensure you're using the latest version. Especially before submitting
   bug reports.
 * Run mergerfs as `root`. mergerfs is designed and intended to be run