diff --git a/mkdocs/docs/config/options.md b/mkdocs/docs/config/options.md index ecb4f88f..e05ef5ac 100644 --- a/mkdocs/docs/config/options.md +++ b/mkdocs/docs/config/options.md @@ -13,9 +13,9 @@ These options are the same regardless of whether you use them with the which will be converted to pages) - STR = string (may refer to an enumerated value, see details of argument) -- FUNC = filesystem function -- CATEGORY = function category -- POLICY = mergerfs function policy +- FUNC = filesystem [function](functions_categories_policies.md) +- CATEGORY = function [category](functions_categories_policies.md) +- POLICY = mergerfs function [policy](functions_categories_policies.md) ### mount options diff --git a/mkdocs/docs/error_handling_and_logging.md b/mkdocs/docs/error_handling_and_logging.md index 84b94bbd..4c2c39c0 100644 --- a/mkdocs/docs/error_handling_and_logging.md +++ b/mkdocs/docs/error_handling_and_logging.md @@ -2,32 +2,53 @@ ## Error Handling -POSIX filesystem functions offer a single return code meaning that -there is some complication regarding the handling of multiple branches -as mergerfs does. It tries to handle errors in a way that would -generally return meaningful values for that particular function. +POSIX filesystem functions typically work on singular items and return +singular errors. This means that there is some complication when +dealing with multiple files or behaviors that are required in mergerfs. -### chmod, chown, removexattr, setxattr, truncate, utimens +mergerfs tries to handle errors in a way that would generally return +meaningful values for that particular function. -1. if no error: return 0 (success) +### Filesystem Functions + +#### chmod, chown, removexattr, setxattr, truncate, utimens + +1. if no errors: return 0 (success) 2. if no successes: return first error -3. if one of the files acted on was the same as the related search function: return its value +3. if one of the files acted on was the same as the related search + function: return its value 4. return 0 (success) While doing this increases the complexity and cost of error handling, particularly step 3, this provides probably the most reasonable return value. -### unlink, rmdir + +#### unlink, rmdir 1. if no errors: return 0 (success) 2. return first error -Older versions of mergerfs would return success if any success occurred -but for unlink and rmdir there are downstream assumptions that, while -not impossible to occur, can confuse some software. +Older versions of mergerfs would return success if any success +occurred but for unlink and rmdir there are downstream assumptions +that, while not impossible to occur in more traditional situation, can +confuse some software. + +#### open, create + +For `create` and `open` where a single file is targeted the return +value of the equivalent final call is returned. + +If the error returned is `EROFS`, indicating the filesystem is in fact +read-only, mergerfs will mark the branch `RO` and rerun the +policy. This typically will only happen with `ext4` when the +filesystem is found to have corruption and the OS remounts the +filesystem as read-only to protect it. In that situation the +filesystem does not otherwise indicate that it is read-only as it +would if mounted with `ro`. + -### others +#### others For search functions, there is always a single thing acted on and as such whatever return value that comes from the single function call is @@ -39,12 +60,38 @@ policies it will return success if any of the calls succeed and an error otherwise. +## Branches disappearing / reappearing + +This is not an error condition. mergerfs works on paths. Not +mounts. There is currently no assumption or active inspection of the +branch path provided at runtime. Nor does it keep its own open file +descriptors that would prevent an unused filesystem from being +unmounted. If a filesystem disappears for any reason mergerfs will +simply continue on behaving as it would normally. As if you never +mounted that filesystem into that location. If a branch path no longer +exists the branch is simply skipped by policies. + +If you wish to keep the branch path from being used when a branch +path's intended filesystem disappears then make the directory +difficult or impossible to use. + +``` +chown root:root /mnt/mountpoint/ +chmod 0000 /mnt/mountpoint/ +chattr +i /mnt/mountpoint/ +``` + +You can still mount to that directory but you will not be able to +write to it. Even as root. Note that `chattr` works on limited +filesystems. Mainly `ext4`. + + ## Logging Filesystems, and therefore mergerfs, are doing lots of small actions at high speed. It simply isn't reasonable to log all the actions of the system. That said: certain details are logged at startup and when -performing mainance tasks. These are logged via `syslog` and on +performing maintenance tasks. These are logged via `syslog` and on `systemd` based systems can be viewed by running ``` diff --git a/mkdocs/docs/faq/usage_and_functionality.md b/mkdocs/docs/faq/usage_and_functionality.md index e07b57a6..9f1f407a 100644 --- a/mkdocs/docs/faq/usage_and_functionality.md +++ b/mkdocs/docs/faq/usage_and_functionality.md @@ -9,25 +9,43 @@ other application does. It can not do anything that any other random piece of software can't do. mergerfs is **not** a traditional filesystem that takes control over -the underlying disk or block device. mergerfs is **not** RAID. It does -**not** manipulate the data that passes through it. It does **not** -shard data across filesystems. It only shards some **behavior** and -aggregates others. +the underlying drive, block device, or partition. mergerfs is **not** +RAID. It does **not** manipulate the data that passes through it. It +does **not** shard data across filesystems. It only shards some +**behavior** and aggregates others. + + +## Can mergerfs be removed without affecting the data? + +Yes. See the previous question's answer. ## Can filesystems be removed from the pool without affecting them? Yes. See previous question's answer. +This is true for planned removal by unmounting mergerfs and changing +the config, changes made to mergerfs at +[runtime](../runtime_interfaces.md), umounting of the branch's +filesystem on the fly (whether on purpose or due to error), etc. -## Can mergerfs be removed without affecting the data? -Yes. See the previous question's answer. +## What happens if a filesystem disappears at runtime? + +By "disappear" meaning explicitly unmounted or due to an error the OS +removes it. + +Nothing explicitly happens. mergerfs works on paths, not mounts. If +the branch path still exists mergerfs will treat it the same as it did +before. It just may not have any data there. If the branch no longer +exists it will be ignored. If the OS returns errors then mergerfs will +return those errors where appropriate. See [Error Handling and +Logging](../error_handling_and_logging.md). ## Can filesystems be moved to another pool? -Yes. See the previous question's answer. +Yes. ## Can filesystems be part of multiple pools? @@ -37,7 +55,9 @@ Yes. ## How do I migrate data into or out of the pool when adding/removing filesystems? -There is no need to do so. See the previous questions. +There is no need to do so. mergerfs is a union filesystem. It works +**on top** of existing filesystems. It does **not** replace them. See +the previous questions and answers. ## How do I remove a filesystem but keep the data in the pool? diff --git a/mkdocs/docs/index.md b/mkdocs/docs/index.md index 5d19d476..c5fab5d9 100644 --- a/mkdocs/docs/index.md +++ b/mkdocs/docs/index.md @@ -37,9 +37,10 @@ and **aufs**. ## How it works -mergerfs logically merges multiple filesystem paths together. It acts -as a proxy to the underlying filesystem paths. Combining the behaviors -of some functions and being a selector for others. +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 +functions and being a selector for others. When the contents of a directory are requested mergerfs combines the list of files from each directory, deduplicating entries, and returns @@ -77,3 +78,7 @@ A + B = C | +-- file6 ``` + +## Getting Started + +Head to the [quick start guide](quickstart.md).