github-mirror/mergerfs
2
0
Fork 0
mirror of https://github.com/trapexit/mergerfs.git synced 2024-11-22 11:39:52 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

explicitly define path preservation, better explain move issues

Browse Source
This commit is contained in:
Antonio SJ Musumeci 2017-04-03 14:35:08 -04:00
parent af9a71f84c
commit 215f129a2a
2 changed files with 84 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
README.md
View File

@ -4,7 +4,7 @@
# NAME
mergerfs - another (FUSE based) union filesystem
mergerfs - a featureful union filesystem
# SYNOPSIS
@ -72,7 +72,7 @@ The POSIX filesystem API has a number of functions. **creat**, **stat**, **chown
Policies, when called to create, will ignore drives which are readonly. This allows for readonly and read/write drives to be mixed together. Note that the drive must be explicitly mounted with the **ro** mount option for this to work.
#### Function / Category classifications ####
#### Function / Category classifications
| Category | FUSE Functions |
|----------|----------------|
@ -83,7 +83,17 @@ Policies, when called to create, will ignore drives which are readonly. This all
Due to FUSE limitations **ioctl** behaves differently if its acting on a directory. It'll use the **getattr** policy to find and open the directory before issuing the **ioctl**. In other cases where something may be searched (to confirm a directory exists across all source mounts) **getattr** will also be used.
#### Policy descriptions ####
#### Path Preservation
Policies, as described below, are of two core types. `path preserving` and `non-path preserving`.
All policies which start with `ep` (**epff**, **eplfs**, **eplus**, **epmfs**, **eprand**) are `path preserving'. `ep` stands for 'existing path`.
As the descriptions explain a path preserving policy will only consider drives where the relative path being accessed already exists.
When using non-path preserving policies where something is created paths will be copied to target drives as necessary.
#### Policy descriptions
| Policy | Description |
|--------------|-------------|
@ -102,8 +112,6 @@ Due to FUSE limitations **ioctl** behaves differently if its acting on a directo
| newest | Pick the file / directory with the largest mtime. For **create** category functions it will exclude readonly drives and those with free space less than **minfreespace** (unless there is no other option). |
| rand (random) | Calls **all** and then randomizes. |
**epff**, **eplfs**, **eplus**, **epmf**, **eprand** are `path preserving` policies. As the descriptions above explain they will only consider drives where the relative path being accessed already exists. Non-path preserving policies will result in paths being copied to drives as necessary.
#### Defaults ####
| Category | Policy |
@ -114,6 +122,8 @@ Due to FUSE limitations **ioctl** behaves differently if its acting on a directo
#### rename & link ####
**NOTE:** If you're receiving errors from software when files are moved / renamed then you should consider changing the create policy to one which is **not** path preserving or contacting the author of the offending software and requesting that `EXDEV` be properly handled.
[rename](http://man7.org/linux/man-pages/man2/rename.2.html) is a tricky function in a merged system. Under normal situations rename only works within a single filesystem or device. If a rename can't be done atomically due to the source and destination paths existing on different mount points it will return **-1** with **errno = EXDEV** (cross device).
Originally mergerfs would return EXDEV whenever a rename was requested which was cross directory in any way. This made the code simple and was technically complient with POSIX requirements. However, many applications fail to handle EXDEV at all and treat it as a normal error or otherwise handle it poorly. Such apps include: gvfsd-fuse v1.20.3 and prior, Finder / CIFS/SMB client in Apple OSX 10.9+, NZBGet, Samba's recycling bin feature.
@ -150,8 +160,6 @@ The above behavior will help minimize the likelihood of EXDEV being returned but
**link** uses the same basic strategy.
If you're receiving errors from software when files are moved / renamed then you should consider changing the create policy to one which is **not** path preserving.
#### readdir ####
[readdir](http://linux.die.net/man/3/readdir) is different from all other filesystem functions. While it could have it's 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 **ls** is a **readdir** and for each file/directory returned **getattr** is called. Meaning the policy of **getattr** is responsible for choosing the file/directory which is the source of the metadata you see in an **ls**.
@ -357,11 +365,13 @@ Be sure to turn off `direct_io`. rtorrent and some other applications use [mmap]
There [is a bug](https://lkml.org/lkml/2016/3/16/260) in caching which affects overall performance of mmap through FUSE in Linux 4.x kernels. It is fixed in [4.4.10 and 4.5.4](https://lkml.org/lkml/2016/5/11/59).
#### Trashing files occasionally fails
#### When a program tries to move or rename a file it fails
This is the same issue as with Samba. `rename` returns `EXDEV` (in our case that will really only happen with path preserving policies like `epmfs`) and the software doesn't handle the situtation well. This is unfortunately a common failure of software which moves files around. The standard indicates that an implementation `MAY` choose to support non-user home directory trashing of files (which is a `MUST`). The implementation `MAY` also support "top directory trashes" which many probably do.
Please read the section above regarding [rename & link](#rename--link).
To create a `$topdir/.Trash` directory as defined in the standard use the [mergerfs-tools](https://github.com/trapexit/mergerfs-tools) tool `mergerfs.mktrash`.
The problem is that many applications do not properly handle `EXDEV` errors which `rename` and `link` may return even though they are perfectly valid situations which do not indicate actual drive or OS errors. The error will only be returned by mergerfs if using a path preserving policy as described in the policy section above. If you do not care about path preservation simply change the mergerfs policy to the non-path preserving version. For example: `-o category.create=mfs`
Ideally the offending software would be fixed and it is recommended that if you run into this problem you contact the software's author and request proper handling of `EXDEV` errors.
#### Samba: Moving files / directories fails
@ -373,6 +383,12 @@ This isn't an issue with Samba but some SMB clients. GVFS-fuse v1.20.3 and prior
In Apple's MacOSX 10.9 they replaced Samba (client and server) with their own product. It appears their new client does not handle **EXDEV** either and responds similar to older release of gvfs on Linux.
#### Trashing files occasionally fails
This is the same issue as with Samba. `rename` returns `EXDEV` (in our case that will really only happen with path preserving policies like `epmfs`) and the software doesn't handle the situtation well. This is unfortunately a common failure of software which moves files around. The standard indicates that an implementation `MAY` choose to support non-user home directory trashing of files (which is a `MUST`). The implementation `MAY` also support "top directory trashes" which many probably do.
To create a `$topdir/.Trash` directory as defined in the standard use the [mergerfs-tools](https://github.com/trapexit/mergerfs-tools) tool `mergerfs.mktrash`.
#### Supplemental user groups
Due to the overhead of [getgroups/setgroups](http://linux.die.net/man/2/setgroups) mergerfs utilizes a cache. This cache is opportunistic and per thread. Each thread will query the supplemental groups for a user when that particular thread needs to change credentials and will keep that data for the lifetime of the thread. This means that if a user is added to a group it may not be picked up without the restart of mergerfs. However, since the high level FUSE API's (at least the standard version) thread pool dynamically grows and shrinks it's possible that over time a thread will be killed and later a new thread with no cache will start and query the new data.
@ -437,6 +453,8 @@ There is a bug in the kernel. A work around appears to be turning off `splice`.
mhddfs is no longer maintained and has some known stability and security issues (see below). MergerFS provides a superset of mhddfs' features and should offer the same or maybe better performance.
If you wish to get similar behavior to mhddfs from mergerfs then set `category.create=ff`.
#### Why use mergerfs over aufs?
While aufs can offer better peak performance mergerfs provides more configurability and is generally easier to use. mergerfs however does not offer the overlay / copy-on-write (COW) features which aufs and overlayfs have.

83
man/mergerfs.1
View File

@ -5,7 +5,7 @@
.hy
.SH NAME
.PP
mergerfs \- another (FUSE based) union filesystem
mergerfs \- a featureful union filesystem
.SH SYNOPSIS
.PP
mergerfs \-o<options> <srcmounts> <mountpoint>
@ -198,6 +198,20 @@ It\[aq]ll use the \f[B]getattr\f[] policy to find and open the directory
before issuing the \f[B]ioctl\f[].
In other cases where something may be searched (to confirm a directory
exists across all source mounts) \f[B]getattr\f[] will also be used.
.SS Path Preservation
.PP
Policies, as described below, are of two core types.
\f[C]path\ preserving\f[] and \f[C]non\-path\ preserving\f[].
.PP
All policies which start with \f[C]ep\f[] (\f[B]epff\f[],
\f[B]eplfs\f[], \f[B]eplus\f[], \f[B]epmfs\f[], \f[B]eprand\f[]) are
\f[C]path\ preserving\[aq].\f[]ep\f[C]stands\ for\ \[aq]existing\ path\f[].
.PP
As the descriptions explain a path preserving policy will only consider
drives where the relative path being accessed already exists.
.PP
When using non\-path preserving policies where something is created
paths will be copied to target drives as necessary.
.SS Policy descriptions
.PP
.TS
@ -329,13 +343,6 @@ T}@T{
Calls \f[B]all\f[] and then randomizes.
T}
.TE
.PP
\f[B]epff\f[], \f[B]eplfs\f[], \f[B]eplus\f[], \f[B]epmf\f[],
\f[B]eprand\f[] are \f[C]path\ preserving\f[] policies.
As the descriptions above explain they will only consider drives where
the relative path being accessed already exists.
Non\-path preserving policies will result in paths being copied to
drives as necessary.
.SS Defaults
.PP
.TS
@ -365,6 +372,12 @@ T}
.TE
.SS rename & link
.PP
\f[B]NOTE:\f[] If you\[aq]re receiving errors from software when files
are moved / renamed then you should consider changing the create policy
to one which is \f[B]not\f[] path preserving or contacting the author of
the offending software and requesting that \f[C]EXDEV\f[] be properly
handled.
.PP
rename (http://man7.org/linux/man-pages/man2/rename.2.html) is a tricky
function in a merged system.
Under normal situations rename only works within a single filesystem or
@ -453,10 +466,6 @@ The above behavior will help minimize the likelihood of EXDEV being
returned but it will still be possible.
.PP
\f[B]link\f[] uses the same basic strategy.
.PP
If you\[aq]re receiving errors from software when files are moved /
renamed then you should consider changing the create policy to one which
is \f[B]not\f[] path preserving.
.SS readdir
.PP
readdir (http://linux.die.net/man/3/readdir) is different from all other
@ -822,23 +831,23 @@ Once with \f[C]direct_io\f[] enabled and one without it.
There is a bug (https://lkml.org/lkml/2016/3/16/260) in caching which
affects overall performance of mmap through FUSE in Linux 4.x kernels.
It is fixed in 4.4.10 and 4.5.4 (https://lkml.org/lkml/2016/5/11/59).
.SS Trashing files occasionally fails
.SS When a program tries to move or rename a file it fails
.PP
This is the same issue as with Samba.
\f[C]rename\f[] returns \f[C]EXDEV\f[] (in our case that will really
only happen with path preserving policies like \f[C]epmfs\f[]) and the
software doesn\[aq]t handle the situtation well.
This is unfortunately a common failure of software which moves files
around.
The standard indicates that an implementation \f[C]MAY\f[] choose to
support non\-user home directory trashing of files (which is a
\f[C]MUST\f[]).
The implementation \f[C]MAY\f[] also support "top directory trashes"
which many probably do.
Please read the section above regarding rename & link (#rename--link).
.PP
To create a \f[C]$topdir/.Trash\f[] directory as defined in the standard
use the mergerfs\-tools (https://github.com/trapexit/mergerfs-tools)
tool \f[C]mergerfs.mktrash\f[].
The problem is that many applications do not properly handle
\f[C]EXDEV\f[] errors which \f[C]rename\f[] and \f[C]link\f[] may return
even though they are perfectly valid situations which do not indicate
actual drive or OS errors.
The error will only be returned by mergerfs if using a path preserving
policy as described in the policy section above.
If you do not care about path preservation simply change the mergerfs
policy to the non\-path preserving version.
For example: \f[C]\-o\ category.create=mfs\f[]
.PP
Ideally the offending software would be fixed and it is recommended that
if you run into this problem you contact the software\[aq]s author and
request proper handling of \f[C]EXDEV\f[] errors.
.SS Samba: Moving files / directories fails
.PP
Workaround: Copy the file/directory and then remove the original rather
@ -873,6 +882,23 @@ In Apple\[aq]s MacOSX 10.9 they replaced Samba (client and server) with
their own product.
It appears their new client does not handle \f[B]EXDEV\f[] either and
responds similar to older release of gvfs on Linux.
.SS Trashing files occasionally fails
.PP
This is the same issue as with Samba.
\f[C]rename\f[] returns \f[C]EXDEV\f[] (in our case that will really
only happen with path preserving policies like \f[C]epmfs\f[]) and the
software doesn\[aq]t handle the situtation well.
This is unfortunately a common failure of software which moves files
around.
The standard indicates that an implementation \f[C]MAY\f[] choose to
support non\-user home directory trashing of files (which is a
\f[C]MUST\f[]).
The implementation \f[C]MAY\f[] also support "top directory trashes"
which many probably do.
.PP
To create a \f[C]$topdir/.Trash\f[] directory as defined in the standard
use the mergerfs\-tools (https://github.com/trapexit/mergerfs-tools)
tool \f[C]mergerfs.mktrash\f[].
.SS Supplemental user groups
.PP
Due to the overhead of
@ -987,6 +1013,9 @@ mhddfs is no longer maintained and has some known stability and security
issues (see below).
MergerFS provides a superset of mhddfs\[aq] features and should offer
the same or maybe better performance.
.PP
If you wish to get similar behavior to mhddfs from mergerfs then set
\f[C]category.create=ff\f[].
.SS Why use mergerfs over aufs?
.PP
While aufs can offer better peak performance mergerfs provides more