diff --git a/mkdocs/docs/config/rename_and_link.md b/mkdocs/docs/config/rename_and_link.md index c55bf554..c2e26d79 100644 --- a/mkdocs/docs/config/rename_and_link.md +++ b/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. diff --git a/mkdocs/docs/faq/compatibility_and_integration.md b/mkdocs/docs/faq/compatibility_and_integration.md index ff1a2080..cdc3407f 100644 --- a/mkdocs/docs/faq/compatibility_and_integration.md +++ b/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. diff --git a/mkdocs/docs/performance.md b/mkdocs/docs/performance.md index 7663ebe6..79c013bb 100644 --- a/mkdocs/docs/performance.md +++ b/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 diff --git a/mkdocs/docs/project_comparisons.md b/mkdocs/docs/project_comparisons.md index dc7a1620..f4a99c73 100644 --- a/mkdocs/docs/project_comparisons.md +++ b/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. diff --git a/mkdocs/docs/tips_notes.md b/mkdocs/docs/tips_notes.md index 138a8547..3a1ed380 100644 --- a/mkdocs/docs/tips_notes.md +++ b/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