Mirror
/
mergerfs
mirror of https://github.com/trapexit/mergerfs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Merge pull request #657 from trapexit/docs 

update how it works
pull/659/head
trapexit 5 years ago
committed by GitHub
parent
52e4d60e7c e6a6ab967b
commit
4204c807bc
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 14 additions and 11 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 4
      README.md
  2. 21
      man/mergerfs.1

4
README.md
View File

@ -59,7 +59,7 @@ A + B = C
+-- file6 +-- 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 # 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) * **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. * **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** * **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.open=INT**: 'open' policy cache timeout in seconds. (default: 0)
* **cache.statfs=INT**: 'statfs' 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) * **cache.attr=INT**: File attribute cache timeout in seconds. (default: 1)

21
man/mergerfs.1
View File

@ -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. 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 However, mergerfs will ignore read\-only drives when creating new files
so you can mix read\-write and read\-only drives. 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 .SH OPTIONS
.SS mount options .SS mount options
.IP \[bu] 2 .IP \[bu] 2
@ -207,6 +210,7 @@ Example: \f[B]func.getattr=newest\f[]
.IP \[bu] 2 .IP \[bu] 2
\f[B]category.CATEGORY=POLICY\f[]: Sets policy of all FUSE functions in \f[B]category.CATEGORY=POLICY\f[]: Sets policy of all FUSE functions in
the provided category. the provided category.
See POLICIES section for defaults.
Example: \f[B]category.create=mfs\f[] Example: \f[B]category.create=mfs\f[]
.IP \[bu] 2 .IP \[bu] 2
\f[B]cache.open=INT\f[]: \[aq]open\[aq] policy cache timeout in seconds. \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 .PP
readdir (http://linux.die.net/man/3/readdir) is different from all other readdir (http://linux.die.net/man/3/readdir) is different from all other
filesystem functions. 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 Remember that any action or information queried about these files and
directories come from the respective function. directories come from the respective function.
For instance: an \f[B]ls\f[] is a \f[B]readdir\f[] and for each 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. This means you will see the combined space of all sources.
Total, used, and free. Total, used, and free.
The sources however are dedupped based on the drive so multiple sources 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 Filesystems mounted further down the tree of the branch will not be
included when checking the mount\[aq]s stats. included when checking the mount\[aq]s stats.
.PP .PP
@ -1104,7 +1108,7 @@ Underlying files cached, mergerfs files cached across opens.
Underlying files cached, mergerfs files cached across opens if mtime and Underlying files cached, mergerfs files cached across opens if mtime and
size are unchanged since previous open. size are unchanged since previous open.
* cache.files=libfuse: follow traditional libfuse \f[C]direct_io\f[], * 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 .PP
FUSE, which mergerfs uses, offers a number of page caching modes. FUSE, which mergerfs uses, offers a number of page caching modes.
mergerfs tries to simplify their use via the \f[C]cache.files\f[] 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 \f[B]EXDEV\f[] which is returned by \f[B]rename\f[] when the call is
crossing mount points. crossing mount points.
When a program gets an \f[B]EXDEV\f[] it needs to explicitly take an 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 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 \f[B]EXDEV\f[] falls back to a manual copying of data between the two
locations and unlinking the source. 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. to dual socket Xeon systems with >20 cores.
I\[aq]m aware of at least a few companies which use mergerfs in I\[aq]m aware of at least a few companies which use mergerfs in
production. 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 .SS Can mergerfs be used with drives which already have data / are in
use? use?
.PP .PP
@ -1755,8 +1759,7 @@ file.
.PP .PP
It\[aq]s almost always a permissions issue. It\[aq]s almost always a permissions issue.
Unlike mhddfs, which runs as root and attempts to access content as 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 This means that if the user does not have access to a file or directory
than neither will mergerfs. than neither will mergerfs.
However, because mergerfs is creating a union of paths it may be able to However, because mergerfs is creating a union of paths it may be able to

Write Preview
Loading…
Cancel
Save