From e6a6ab967be831f13ecacaa5cdbe1661590a0454 Mon Sep 17 00:00:00 2001 From: Antonio SJ Musumeci Date: Tue, 20 Aug 2019 20:13:25 -0400 Subject: [PATCH] update how it works --- README.md | 4 ++-- man/mergerfs.1 | 21 ++++++++++++--------- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index c9e5c42f..273d09cd 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ A + B = C +-- file6 ``` -mergerfs does **not** support the copy-on-write (CoW) behavior found in **aufs** and **overlayfs**. You can **not** mount a read-only filesystem and write to it. However, mergerfs will ignore read-only drives when creating new files so you can mix read-write and read-only drives. +mergerfs does **not** support the copy-on-write (CoW) behavior found in **aufs** and **overlayfs**. You can **not** mount a read-only filesystem and write to it. However, mergerfs will ignore read-only drives when creating new files so you can mix read-write and read-only drives. It also does **not** split data across drives. It is not RAID0 / striping. It is simply a union. # OPTIONS @@ -86,7 +86,7 @@ mergerfs does **not** support the copy-on-write (CoW) behavior found in **aufs** * **threads=INT**: Number of threads to use in multithreaded mode. When set to zero it will attempt to discover and use the number of logical cores. If the lookup fails it will fall back to using 4. If the thread count is set negative it will look up the number of cores then divide by the absolute value. ie. threads=-2 on an 8 core machine will result in 8 / 2 = 4 threads. There will always be at least 1 thread. NOTE: higher number of threads increases parallelism but usually decreases throughput. (default: 0) * **fsname=STR**: Sets the name of the filesystem as seen in **mount**, **df**, etc. Defaults to a list of the source paths concatenated together with the longest common prefix removed. * **func.FUNC=POLICY**: Sets the specific FUSE function's policy. See below for the list of value types. Example: **func.getattr=newest** -* **category.CATEGORY=POLICY**: Sets policy of all FUSE functions in the provided category. Example: **category.create=mfs** +* **category.CATEGORY=POLICY**: Sets policy of all FUSE functions in the provided category. See POLICIES section for defaults. Example: **category.create=mfs** * **cache.open=INT**: 'open' policy cache timeout in seconds. (default: 0) * **cache.statfs=INT**: 'statfs' cache timeout in seconds. (default: 0) * **cache.attr=INT**: File attribute cache timeout in seconds. (default: 1) diff --git a/man/mergerfs.1 b/man/mergerfs.1 index 2ad43df6..48c98c3d 100644 --- a/man/mergerfs.1 +++ b/man/mergerfs.1 @@ -79,6 +79,9 @@ found in \f[B]aufs\f[] and \f[B]overlayfs\f[]. You can \f[B]not\f[] mount a read\-only filesystem and write to it. However, mergerfs will ignore read\-only drives when creating new files so you can mix read\-write and read\-only drives. +It also does \f[B]not\f[] split data across drives. +It is not RAID0 / striping. +It is simply a union. .SH OPTIONS .SS mount options .IP \[bu] 2 @@ -207,6 +210,7 @@ Example: \f[B]func.getattr=newest\f[] .IP \[bu] 2 \f[B]category.CATEGORY=POLICY\f[]: Sets policy of all FUSE functions in the provided category. +See POLICIES section for defaults. Example: \f[B]category.create=mfs\f[] .IP \[bu] 2 \f[B]cache.open=INT\f[]: \[aq]open\[aq] policy cache timeout in seconds. @@ -831,8 +835,8 @@ returned but it will still be possible. .PP readdir (http://linux.die.net/man/3/readdir) is different from all other filesystem functions. -While it could have it\[aq]s own set of policies to tweak its behavior -at this time it provides a simple union of files and directories found. +While it could have its own set of policies to tweak its behavior at +this time it provides a simple union of files and directories found. Remember that any action or information queried about these files and directories come from the respective function. For instance: an \f[B]ls\f[] is a \f[B]readdir\f[] and for each @@ -848,7 +852,7 @@ and inodes. This means you will see the combined space of all sources. Total, used, and free. The sources however are dedupped based on the drive so multiple sources -on the same drive will not result in double counting it\[aq]s space. +on the same drive will not result in double counting its space. Filesystems mounted further down the tree of the branch will not be included when checking the mount\[aq]s stats. .PP @@ -1104,7 +1108,7 @@ Underlying files cached, mergerfs files cached across opens. Underlying files cached, mergerfs files cached across opens if mtime and size are unchanged since previous open. * cache.files=libfuse: follow traditional libfuse \f[C]direct_io\f[], -\[aq]kernel_cache\f[C],\ and\f[]auto_cache` arguments. +\f[C]kernel_cache\f[], and \f[C]auto_cache\f[] arguments. .PP FUSE, which mergerfs uses, offers a number of page caching modes. mergerfs tries to simplify their use via the \f[C]cache.files\f[] @@ -1535,7 +1539,7 @@ Particularly \f[B]STATUS_NOT_SAME_DEVICE\f[] which comes from the \f[B]EXDEV\f[] which is returned by \f[B]rename\f[] when the call is crossing mount points. When a program gets an \f[B]EXDEV\f[] it needs to explicitly take an -alternate action to accomplish it\[aq]s goal. +alternate action to accomplish its goal. In the case of \f[B]mv\f[] or similar it tries \f[B]rename\f[] and on \f[B]EXDEV\f[] falls back to a manual copying of data between the two locations and unlinking the source. @@ -1717,8 +1721,8 @@ Users have reported running mergerfs on everything from a Raspberry Pi to dual socket Xeon systems with >20 cores. I\[aq]m aware of at least a few companies which use mergerfs in production. -Open Media Vault (https://www.openmediavault.org) includes mergerfs is -it\[aq]s sole solution for pooling drives. +Open Media Vault (https://www.openmediavault.org) includes mergerfs as +its sole solution for pooling drives. .SS Can mergerfs be used with drives which already have data / are in use? .PP @@ -1755,8 +1759,7 @@ file. .PP It\[aq]s almost always a permissions issue. Unlike mhddfs, which runs as root and attempts to access content as -such, mergerfs always changes it\[aq]s credentials to that of the -caller. +such, mergerfs always changes its credentials to that of the caller. This means that if the user does not have access to a file or directory than neither will mergerfs. However, because mergerfs is creating a union of paths it may be able to