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

update / tweak readme

Browse Source
This commit is contained in:
Antonio SJ Musumeci 2016-02-21 18:30:25 -05:00
parent 5b06bb24fb
commit a698a8a545
2 changed files with 229 additions and 198 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
README.md
View File

@ -1,6 +1,6 @@
% mergerfs(1) mergerfs user manual
% Antonio SJ Musumeci <trapexit@spawn.link>
% 2016-01-21
% 2016-02-21
# NAME
@ -25,6 +25,7 @@ mergerfs -o&lt;options&gt; &lt;srcmounts&gt; &lt;mountpoint&gt;
* Opportunistic credential caching
* Works with heterogeneous filesystem types
* Handling of writes to full drives
* Handles pool of readonly and read/write drives
# OPTIONS
@ -58,11 +59,13 @@ In /etc/fstab it'd look like the following:
**NOTE:** the globbing is done at mount or xattr update time. If a new directory is added matching the glob after the fact it will not be included.
# POLICIES
# FUNCTIONS / POLICIES / CATEGORIES
Filesystem calls are broken up into 3 categories: **action**, **create**, **search**. There are also some calls which have no policy attached due to state being kept between calls. These categories can be assigned a policy which dictates how **mergerfs** behaves. Any policy can be assigned to a category though some aren't terribly practical. For instance: **rand** (Random) may be useful for **create** but could lead to very odd behavior if used for **search**.
The filesystem has a number of functions. Those functions are grouped into 3 categories: **action**, **create**, **search**. These functions and categories can be assigned a policy which dictates how **mergerfs** behaves. Any policy can be assigned to a function or category though some are not very practical. For instance: **rand** (Random) may be useful for file creation (create) but could lead to very odd behavior if used for `chmod`.
#### Functional classifications ####
All policies when used to create will ignore drives which are mounted readonly. This allows for read/write and readonly drives to be mixed together.
#### Function / Category classifications ####
| Category | FUSE Functions |
|----------|----------------|
@ -77,17 +80,16 @@ Filesystem calls are broken up into 3 categories: **action**, **create**, **sear
| Policy | Description |
|--------------|-------------|
| ff (first found) | Given the order of the drives act on the first one found (regardless if stat would return EACCES). |
| ffwp (first found w/ permissions) | Given the order of the drives act on the first one found which you have access (stat does not error with EACCES). |
| newest (newest file) | If multiple files exist return the one with the most recent mtime. |
| mfs (most free space) | Use the drive with the most free space available. |
| epmfs (existing path, most free space) | If the path exists on multiple drives use the one with the most free space and is greater than **minfreespace**. If no drive has at least **minfreespace** then fallback to **mfs**. |
| fwfs (first with free space) | Pick the first drive which has at least **minfreespace**. |
| lfs (least free space) | Pick the drive with least available space but more than **minfreespace**. If all drives fail it will fallback to **mfs**. |
| eplfs (existing path, least free space) | If the path exists on multiple drives use the one with the least free space and greater than **minfreespace**. If no drive has at least **minfreespace** then it falls back to **lfs**. |
| rand (random) | Pick an existing drive at random. |
| all | Applies action to all found. For searches it will behave like first found **ff**. |
| enosys, einval, enotsup, exdev, erofs | Exclusively return `-1` with `errno` set to the respective value. Useful for debugging other applications' behavior to errors. |
| all | Applies action to all found. For searches it will behave like first found **ff**. For `create` functions it will only apply to `mkdir`, `mkdnod`, and `symlink`. |
| eplfs (existing path, least free space) | If the path exists on multiple drives use the one with the least free space and is greater than **minfreespace**. Falls back to **lfs**. |
| epmfs (existing path, most free space) | If the path exists on multiple drives use the one with the most free space and is greater than **minfreespace**. Falls back to **mfs**. |
| erofs | Exclusively return `-1` with `errno` set to EROFS. By setting `create` functions to this you can in effect turn the filesystem readonly. |
| ff (first found) | Given the order of the drives, as defined at mount time or when configured via xattr interface, act on the first one found. |
| fwfs (first with free space) | Pick the first drive which has at least **minfreespace**. Falls back to **mfs**. |
| lfs (least free space) | Pick the drive with the least available free space but more than **minfreespace**. Falls back to **mfs**. |
| mfs (most free space) | Use the drive with the most available free space. Falls back to **ff**. |
| newest (newest file) | Pick the file / directory with the largest mtime. |
| rand (random) | Calls **all** and then randomizes. |
#### Defaults ####
@ -141,7 +143,7 @@ It could be extended to offer the ability to see all files found. Perhaps concat
#### statvfs ####
[statvfs](http://linux.die.net/man/2/statvfs) normalizes the source drives based on the fragment size and sums the number of adjusted blocks 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 mount points on the same drive will not result in double counting it's space. It is possible due to a race condition that the same drive could be double counted but it's rather unlikely.
[statvfs](http://linux.die.net/man/2/statvfs) normalizes the source drives based on the fragment size and sums the number of adjusted blocks 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's space.
# BUILDING
@ -198,35 +200,6 @@ Even if xattrs are disabled the [{list,get,set}xattrs](http://linux.die.net/man/
Use `xattr -l /mount/point/.mergerfs` to see all supported keys.
##### Example #####
```
[trapexit:/tmp/mount] $ xattr -l .mergerfs
user.mergerfs.srcmounts: /tmp/a:/tmp/b
user.mergerfs.minfreespace: 4294967295
user.mergerfs.moveonenospc: false
...
[trapexit:/tmp/mount] $ xattr -p user.mergerfs.category.search .mergerfs
ff
[trapexit:/tmp/mount] $ xattr -w user.mergerfs.category.search ffwp .mergerfs
[trapexit:/tmp/mount] $ xattr -p user.mergerfs.category.search .mergerfs
ffwp
[trapexit:/tmp/mount] $ xattr -w user.mergerfs.srcmounts +/tmp/c .mergerfs
[trapexit:/tmp/mount] $ xattr -p user.mergerfs.srcmounts .mergerfs
/tmp/a:/tmp/b:/tmp/c
[trapexit:/tmp/mount] $ xattr -w user.mergerfs.srcmounts =/tmp/c .mergerfs
[trapexit:/tmp/mount] $ xattr -p user.mergerfs.srcmounts .mergerfs
/tmp/c
[trapexit:/tmp/mount] $ xattr -w user.mergerfs.srcmounts '+</tmp/a:/tmp/b' .mergerfs
[trapexit:/tmp/mount] $ xattr -p user.mergerfs.srcmounts .mergerfs
/tmp/a:/tmp/b:/tmp/c
```
##### user.mergerfs.srcmounts #####
For **user.mergerfs.srcmounts** there are several instructions available for manipulating the list. The value provided is just as the value used at mount time. A colon (':') delimited list of full path globs.
@ -256,7 +229,36 @@ Ouput: **true** or **false**
Input: short policy string as described elsewhere in this document
Output: the policy string except for categories where its funcs have multiple types. In that case it will be a comma separated list.
Output: the policy string except for categories where its funcs have multiple types. In that case it will be a comma separated list
##### Example #####
```
[trapexit:/tmp/mount] $ xattr -l .mergerfs
user.mergerfs.srcmounts: /tmp/a:/tmp/b
user.mergerfs.minfreespace: 4294967295
user.mergerfs.moveonenospc: false
...
[trapexit:/tmp/mount] $ xattr -p user.mergerfs.category.search .mergerfs
ff
[trapexit:/tmp/mount] $ xattr -w user.mergerfs.category.search fwfs .mergerfs
[trapexit:/tmp/mount] $ xattr -p user.mergerfs.category.search .mergerfs
fwfs
[trapexit:/tmp/mount] $ xattr -w user.mergerfs.srcmounts +/tmp/c .mergerfs
[trapexit:/tmp/mount] $ xattr -p user.mergerfs.srcmounts .mergerfs
/tmp/a:/tmp/b:/tmp/c
[trapexit:/tmp/mount] $ xattr -w user.mergerfs.srcmounts =/tmp/c .mergerfs
[trapexit:/tmp/mount] $ xattr -p user.mergerfs.srcmounts .mergerfs
/tmp/c
[trapexit:/tmp/mount] $ xattr -w user.mergerfs.srcmounts '+</tmp/a:/tmp/b' .mergerfs
[trapexit:/tmp/mount] $ xattr -p user.mergerfs.srcmounts .mergerfs
/tmp/a:/tmp/b:/tmp/c
```
#### mergerfs file xattrs ####
@ -283,9 +285,10 @@ A B C
# TOOLING
Find extra tooling to help with managing `mergerfs` at: https://github.com/trapexit/mergerfs-tools
Find tooling to help with managing `mergerfs` at: https://github.com/trapexit/mergerfs-tools
* fsck.mergerfs: Provides permissions and ownership auditing and the ability to fix them
* mergerfs.mktrash: Creates FreeDesktop.org Trash specification compatible directories on a mergerfs mount
# TIPS / NOTES
@ -297,7 +300,7 @@ Find extra tooling to help with managing `mergerfs` at: https://github.com/trape
* An example: [Kodi](http://kodi.tv) and [Plex](http://plex.tv) can use directory [mtime](http://linux.die.net/man/2/stat) to more efficiently determine whether to scan for new content rather than simply performing a full scan. If using the current default **getattr** policy of **ff** its possible **Kodi** will miss an update on account of it returning the first directory found's **stat** info and its a later directory on another mount which had the **mtime** recently updated. To fix this you will want to set **func.getattr=newest**. Remember though that this is just **stat**. If the file is later **open**'ed or **unlink**'ed and the policy is different for those then a completely different file or directory could be acted on.
* Due to previously mentioned issues its generally best to set **category** wide policies rather than individual **func**'s. This will help limit the confusion of tools such as [rsync](http://linux.die.net/man/1/rsync).
# Known Issues / Bugs
# KNOWN ISSUES / BUGS
#### Trashing files occasionally fails
@ -305,23 +308,23 @@ This is the same issue as with Samba. `rename` returns `EXDEV` (in our case that
To create a `$topdir/.Trash` directory as defined in the standard use the [mergerfs-tools](https://github.com/trapexit/mergerfs-tools) tool `mergerfs.mktrash`.
#### Samba
* Moving files or directories between some directories on a SMB share fail with IO errors.
Workaround: Copy the file/directory and then remove the original rather than move.
This isn't an issue with Samba but some SMB clients. GVFS-fuse v1.20.3 and prior (found in Ubuntu 14.04 among others) failed to handle certain error codes correctly. Particularly **STATUS_NOT_SAME_DEVICE** which comes from the **EXDEV** which is returned by **rename** when the call is crossing mount points. When a program gets an **EXDEV** it needs to explicitly take an alternate action to accomplish it's goal. In the case of **mv** or similar it tries **rename** and on **EXDEV** falls back to a manual copying of data between the two locations and unlinking the source. In these older versions of GVFS-fuse if it received **EXDEV** it would translate that into **EIO**. This would cause **mv** or most any application attempting to move files around on that SMB share to fail with a IO error.
[GVFS-fuse v1.22.0](https://bugzilla.gnome.org/show_bug.cgi?id=734568) and above fixed this issue but a large number of systems use the older release. On Ubuntu the version can be checked by issuing `apt-cache showpkg gvfs-fuse`. Most distros released in 2015 seem to have the updated release and will work fine but older systems may not. Upgrading gvfs-fuse or the distro in general will address the problem.
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.
#### Samba: Moving files / directories fails
#### Supplemental 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 mount or 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.
The gid cache uses fixed storage to simplify the design and be compatible with older systems which may not have C++11 compilers (as the original design required). There is enough storage for 256 users' supplemental groups. Each user is allowed upto 32 supplemental groups. Linux >= 2.6.3 allows upto 65535 groups per user but most other *nixs allow far less. NFS allowing only 16. The system does handle overflow gracefully. If the user has more than 32 supplemental groups only the first 32 will be used. If more than 256 users are using the system when an uncached user is found it will evict an existing user's cache at random. So long as there aren't more than 256 active users this should be fine. If either value is too low for your needs you will have to modify `gidcache.hpp` to increase the values. Note that doing so will increase the memory needed by each thread.
Workaround: Copy the file/directory and then remove the original rather than move.
#### mergerfs / libfuse crashes
This isn't an issue with Samba but some SMB clients. GVFS-fuse v1.20.3 and prior (found in Ubuntu 14.04 among others) failed to handle certain error codes correctly. Particularly **STATUS_NOT_SAME_DEVICE** which comes from the **EXDEV** which is returned by **rename** when the call is crossing mount points. When a program gets an **EXDEV** it needs to explicitly take an alternate action to accomplish it's goal. In the case of **mv** or similar it tries **rename** and on **EXDEV** falls back to a manual copying of data between the two locations and unlinking the source. In these older versions of GVFS-fuse if it received **EXDEV** it would translate that into **EIO**. This would cause **mv** or most any application attempting to move files around on that SMB share to fail with a IO error.
[GVFS-fuse v1.22.0](https://bugzilla.gnome.org/show_bug.cgi?id=734568) and above fixed this issue but a large number of systems use the older release. On Ubuntu the version can be checked by issuing `apt-cache showpkg gvfs-fuse`. Most distros released in 2015 seem to have the updated release and will work fine but older systems may not. Upgrading gvfs-fuse or the distro in general will address the problem.
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.
#### 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.
The gid cache uses fixed storage to simplify the design and be compatible with older systems which may not have C++11 compilers. There is enough storage for 256 users' supplemental groups. Each user is allowed upto 32 supplemental groups. Linux >= 2.6.3 allows upto 65535 groups per user but most other *nixs allow far less. NFS allowing only 16. The system does handle overflow gracefully. If the user has more than 32 supplemental groups only the first 32 will be used. If more than 256 users are using the system when an uncached user is found it will evict an existing user's cache at random. So long as there aren't more than 256 active users this should be fine. If either value is too low for your needs you will have to modify `gidcache.hpp` to increase the values. Note that doing so will increase the memory needed by each thread.
#### mergerfs or libfuse crashing
If suddenly the mergerfs mount point disappears and `Transport endpoint is not connected` is returned when attempting to perform actions within the mount directory **and** the version of libfuse (use `mergerfs -v` to find the version) is older than `2.9.4` its likely due to a bug in libfuse. Affected versions of libfuse can be found in Debian Wheezy, Ubuntu Precise and others.
@ -335,27 +338,27 @@ mhddfs is no longer maintained and has some known stability and security issues
#### Why use mergerfs over aufs?
While aufs can offer better peak performance mergerfs offers more configurability and is generally easier to use. mergerfs also doesn't offer the overlay features which tends to result in whiteout files being left around the underlying filesystems.
While aufs can offer better peak performance mergerfs offers more configurability and is generally easier to use. mergerfs however doesn't offer the overlay features which tends to result in whiteout files being left around the underlying filesystems.
#### Why use mergerfs over LVM/ZFS/BTRFS/RAID0 drive concatenation / striping?
A single drive failure will lead to full pool failure without additional redundency. mergerfs performance a similar behavior without the catastrophic failure and lack of recovery. Drives can fail and all other data will continue to be accessable.
A single drive failure will lead to full pool failure without additional redundancy. mergerfs performs a similar behavior without the catastrophic failure and lack of recovery. Drives can fail and all other data will continue to be accessable.
#### It's mentioned that there are some security issues with mhddfs. What are they? How does mergerfs address them?
[mhddfs](https://github.com/trapexit/mhddfs) tries to handle being run as **root** by calling [getuid()](https://github.com/trapexit/mhddfs/blob/cae96e6251dd91e2bdc24800b4a18a74044f6672/src/main.c#L319) and if it returns **0** then it will [chown](http://linux.die.net/man/1/chown) the file. Not only is that a race condition but it doesn't handle many other situations. Rather than attempting to simulate POSIX ACL behaviors the proper behavior is to use [seteuid](http://linux.die.net/man/2/seteuid) and [setegid](http://linux.die.net/man/2/setegid), become the user making the original call and perform the action as them. This is how [mergerfs](https://github.com/trapexit/mergerfs) handles things.
[mhddfs](https://github.com/trapexit/mhddfs) tries to handle being run as **root** by calling [getuid()](https://github.com/trapexit/mhddfs/blob/cae96e6251dd91e2bdc24800b4a18a74044f6672/src/main.c#L319) and if it returns **0** then it will [chown](http://linux.die.net/man/1/chown) the file. Not only is that a race condition but it doesn't handle many other situations. Rather than attempting to simulate POSIX ACL behaviors the proper behavior is to use [seteuid](http://linux.die.net/man/2/seteuid) and [setegid](http://linux.die.net/man/2/setegid), become the user making the original call and perform the action as them. This is how [mergerfs](https://github.com/trapexit/mergerfs) handles things.
If you are familiar with POSIX standards you'll know that this behavior poses a problem. **seteuid** and **setegid** affect the whole process and **libfuse** is multithreaded by default. We'd need to lock access to **seteuid** and **setegid** with a mutex so that the several threads aren't stepping on one another and files end up with weird permissions and ownership. This however wouldn't scale well. With lots of calls the contention on that mutex would be extremely high. Thankfully on Linux and OSX we have a better solution.
If you are familiar with POSIX standards you'll know that this behavior poses a problem. **seteuid** and **setegid** affect the whole process and **libfuse** is multithreaded by default. We'd need to lock access to **seteuid** and **setegid** with a mutex so that the several threads aren't stepping on one another and files end up with weird permissions and ownership. This however wouldn't scale well. With lots of calls the contention on that mutex would be extremely high. Thankfully on Linux and OSX we have a better solution.
OSX has a [non-portable pthread extension](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man2/pthread_setugid_np.2.html) for per-thread user and group impersonation.
OSX has a [non-portable pthread extension](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man2/pthread_setugid_np.2.html) for per-thread user and group impersonation.
Linux does not support [pthread_setugid_np](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man2/pthread_setugid_np.2.html) but user and group IDs are a per-thread attribute though documentation on that fact or how to manipulate them is not well distributed. From the **4.00** release of the Linux man-pages project for [setuid](http://man7.org/linux/man-pages/man2/setuid.2.html)
Linux does not support [pthread_setugid_np](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man2/pthread_setugid_np.2.html) but user and group IDs are a per-thread attribute though documentation on that fact or how to manipulate them is not well distributed. From the **4.00** release of the Linux man-pages project for [setuid](http://man7.org/linux/man-pages/man2/setuid.2.html).
> At the kernel level, user IDs and group IDs are a per-thread attribute. However, POSIX requires that all threads in a process share the same credentials. The NPTL threading implementation handles the POSIX requirements by providing wrapper functions for the various system calls that change process UIDs and GIDs. These wrapper functions (including the one for setuid()) employ a signal-based technique to ensure that when one thread changes credentials, all of the other threads in the process also change their credentials. For details, see nptl(7).
> At the kernel level, user IDs and group IDs are a per-thread attribute. However, POSIX requires that all threads in a process share the same credentials. The NPTL threading implementation handles the POSIX requirements by providing wrapper functions for the various system calls that change process UIDs and GIDs. These wrapper functions (including the one for setuid()) employ a signal-based technique to ensure that when one thread changes credentials, all of the other threads in the process also change their credentials. For details, see nptl(7).
Turns out the setreuid syscalls apply only to the thread. GLIBC hides this away using RT signals to inform all threads to change credentials. Taking after **Samba** mergerfs uses **syscall(SYS_setreuid,...)** to set the callers credentials for that thread only. Jumping back to **root** as necessary should escalated privileges be needed (for instance: to clone paths).
Turns out the setreuid syscalls apply only to the thread. GLIBC hides this away using RT signals to inform all threads to change credentials. Taking after **Samba** mergerfs uses **syscall(SYS_setreuid,...)** to set the callers credentials for that thread only. Jumping back to **root** as necessary should escalated privileges be needed (for instance: to clone paths).
For non-Linux systems mergerfs uses a read-write lock and changes credentials only when necessary. If multiple threads are to be user X then only the first one will need to change the processes credentials. So long as the other threads need to be user X they will take a readlock allow multiple threads to share the credentials. Once a request comes in to run as user Y that thread will attempt a write lock and change to Y's credentials when it can. If the ability to give writers priority is supported then that flag will be used so threads trying to change credentials don't starve. This isn't the best solution but should work reasonably well. As new platforms are supported if they offer per thread credentials those APIs will be adopted.
For non-Linux systems mergerfs uses a read-write lock and changes credentials only when necessary. If multiple threads are to be user X then only the first one will need to change the processes credentials. So long as the other threads need to be user X they will take a readlock allow multiple threads to share the credentials. Once a request comes in to run as user Y that thread will attempt a write lock and change to Y's credentials when it can. If the ability to give writers priority is supported then that flag will be used so threads trying to change credentials don't starve. This isn't the best solution but should work reasonably well. As new platforms are supported if they offer per thread credentials those APIs will be adopted.
# SUPPORT

280
man/mergerfs.1
View File

@ -1,5 +1,5 @@
.\"t
.TH "mergerfs" "1" "2016\-01\-21" "mergerfs user manual" ""
.TH "mergerfs" "1" "2016\-02\-21" "mergerfs user manual" ""
.SH NAME
.PP
mergerfs \- another (FUSE based) union filesystem
@ -31,6 +31,8 @@ Opportunistic credential caching
Works with heterogeneous filesystem types
.IP \[bu] 2
Handling of writes to full drives
.IP \[bu] 2
Handles pool of readonly and read/write drives
.SH OPTIONS
.SS options
.IP \[bu] 2
@ -43,7 +45,7 @@ These options seem to provide the best performance.
can increase write speeds at the detriment of read speed.
.IP \[bu] 2
\f[B]minfreespace\f[]: the minimum space value used for the
\f[B]lfs\f[], \f[B]fwfs\f[], and \f[B]epmfs\f[] policies.
\f[B]lfs\f[], \f[B]fwfs\f[], \f[B]eplfs\f[], & \f[B]epmfs\f[] policies.
Understands \[aq]K\[aq], \[aq]M\[aq], and \[aq]G\[aq] to represent
kilobyte, megabyte, and gigabyte respectively.
(default: 4G)
@ -101,19 +103,22 @@ In /etc/fstab it\[aq]d look like the following:
\f[B]NOTE:\f[] the globbing is done at mount or xattr update time.
If a new directory is added matching the glob after the fact it will not
be included.
.SH POLICIES
.SH FUNCTIONS / POLICIES / CATEGORIES
.PP
Filesystem calls are broken up into 3 categories: \f[B]action\f[],
The filesystem has a number of functions.
Those functions are grouped into 3 categories: \f[B]action\f[],
\f[B]create\f[], \f[B]search\f[].
There are also some calls which have no policy attached due to state
being kept between calls.
These categories can be assigned a policy which dictates how
\f[B]mergerfs\f[] behaves.
Any policy can be assigned to a category though some aren\[aq]t terribly
practical.
For instance: \f[B]rand\f[] (Random) may be useful for \f[B]create\f[]
but could lead to very odd behavior if used for \f[B]search\f[].
.SS Functional classifications
These functions and categories can be assigned a policy which dictates
how \f[B]mergerfs\f[] behaves.
Any policy can be assigned to a function or category though some are not
very practical.
For instance: \f[B]rand\f[] (Random) may be useful for file creation
(create) but could lead to very odd behavior if used for \f[C]chmod\f[].
.PP
All policies when used to create will ignore drives which are mounted
readonly.
This allows for read/write and readonly drives to be mixed together.
.SS Function / Category classifications
.PP
.TS
tab(@);
@ -165,63 +170,68 @@ Description
T}
_
T{
ff (first found)
all
T}@T{
Given the order of the drives act on the first one found (regardless if
stat would return EACCES).
Applies action to all found.
For searches it will behave like first found \f[B]ff\f[].
For \f[C]create\f[] functions it will only apply to \f[C]mkdir\f[],
\f[C]mkdnod\f[], and \f[C]symlink\f[].
T}
T{
ffwp (first found w/ permissions)
eplfs (existing path, least free space)
T}@T{
Given the order of the drives act on the first one found which you have
access (stat does not error with EACCES).
T}
T{
newest (newest file)
T}@T{
If multiple files exist return the one with the most recent mtime.
T}
T{
mfs (most free space)
T}@T{
Use the drive with the most free space available.
If the path exists on multiple drives use the one with the least free
space and is greater than \f[B]minfreespace\f[].
Falls back to \f[B]lfs\f[].
T}
T{
epmfs (existing path, most free space)
T}@T{
If the path exists on multiple drives use the one with the most free
space and is greater than \f[B]minfreespace\f[].
If no drive has at least \f[B]minfreespace\f[] then fallback to
\f[B]mfs\f[].
Falls back to \f[B]mfs\f[].
T}
T{
erofs
T}@T{
Exclusively return \f[C]\-1\f[] with \f[C]errno\f[] set to EROFS.
By setting \f[C]create\f[] functions to this you can in effect turn the
filesystem readonly.
T}
T{
ff (first found)
T}@T{
Given the order of the drives, as defined at mount time or when
configured via xattr interface, act on the first one found.
T}
T{
fwfs (first with free space)
T}@T{
Pick the first drive which has at least \f[B]minfreespace\f[].
Falls back to \f[B]mfs\f[].
T}
T{
lfs (least free space)
T}@T{
Pick the drive with least available space but more than
Pick the drive with the least available free space but more than
\f[B]minfreespace\f[].
Falls back to \f[B]mfs\f[].
T}
T{
mfs (most free space)
T}@T{
Use the drive with the most available free space.
Falls back to \f[B]ff\f[].
T}
T{
newest (newest file)
T}@T{
Pick the file / directory with the largest mtime.
T}
T{
rand (random)
T}@T{
Pick an existing drive at random.
T}
T{
all
T}@T{
Applies action to all found.
For searches it will behave like first found \f[B]ff\f[].
T}
T{
enosys, einval, enotsup, exdev, erofs
T}@T{
Exclusively return \f[C]\-1\f[] with \f[C]errno\f[] set to the
respective value.
Useful for debugging other applications\[aq] behavior to errors.
Calls \f[B]all\f[] and then randomizes.
T}
.TE
.SS Defaults
@ -276,7 +286,7 @@ same as \f[C]mv\f[] would).
Such apps include: gvfsd\-fuse v1.20.3 and prior, Finder / CIFS/SMB
client in Apple OSX 10.9+, NZBGet, Samba\[aq]s recycling bin feature.
.IP \[bu] 2
If using a policy which tries to preserve directories (epmfs)
If using a policy which tries to preserve directories (epmfs,eplfs)
.IP \[bu] 2
Using the \f[C]rename\f[] policy get the list of files to rename
.IP \[bu] 2
@ -367,11 +377,8 @@ drives based on the fragment size and sums the number of adjusted blocks
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 mount
points on the same drive will not result in double counting it\[aq]s
space.
It is possible due to a race condition that the same drive could be
double counted but it\[aq]s rather unlikely.
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.
.SH BUILDING
.PP
\f[B]NOTE:\f[] Prebuilt packages can be found at:
@ -441,60 +448,6 @@ still work.
.PP
Use \f[C]xattr\ \-l\ /mount/point/.mergerfs\f[] to see all supported
keys.
.SS Example
.IP
.nf
\f[C]
[trapexit:/tmp/mount]\ $\ xattr\ \-l\ .mergerfs
user.mergerfs.srcmounts:\ /tmp/a:/tmp/b
user.mergerfs.minfreespace:\ 4294967295
user.mergerfs.moveonenospc:\ false
user.mergerfs.policies:\ all,einval,enosys,enotsup,epmfs,erofs,exdev,ff,ffwp,fwfs,lfs,mfs,newest,rand
user.mergerfs.version:\ x.y.z
user.mergerfs.category.action:\ all
user.mergerfs.category.create:\ epmfs
user.mergerfs.category.search:\ ff
user.mergerfs.func.access:\ ff
user.mergerfs.func.chmod:\ all
user.mergerfs.func.chown:\ all
user.mergerfs.func.create:\ epmfs
user.mergerfs.func.getattr:\ ff
user.mergerfs.func.getxattr:\ ff
user.mergerfs.func.link:\ all
user.mergerfs.func.listxattr:\ ff
user.mergerfs.func.mkdir:\ epmfs
user.mergerfs.func.mknod:\ epmfs
user.mergerfs.func.open:\ ff
user.mergerfs.func.readlink:\ ff
user.mergerfs.func.removexattr:\ all
user.mergerfs.func.rename:\ all
user.mergerfs.func.rmdir:\ all
user.mergerfs.func.setxattr:\ all
user.mergerfs.func.symlink:\ epmfs
user.mergerfs.func.truncate:\ all
user.mergerfs.func.unlink:\ all
user.mergerfs.func.utimens:\ all
[trapexit:/tmp/mount]\ $\ xattr\ \-p\ user.mergerfs.category.search\ .mergerfs
ff
[trapexit:/tmp/mount]\ $\ xattr\ \-w\ user.mergerfs.category.search\ ffwp\ .mergerfs
[trapexit:/tmp/mount]\ $\ xattr\ \-p\ user.mergerfs.category.search\ .mergerfs
ffwp
[trapexit:/tmp/mount]\ $\ xattr\ \-w\ user.mergerfs.srcmounts\ +/tmp/c\ .mergerfs
[trapexit:/tmp/mount]\ $\ xattr\ \-p\ user.mergerfs.srcmounts\ .mergerfs
/tmp/a:/tmp/b:/tmp/c
[trapexit:/tmp/mount]\ $\ xattr\ \-w\ user.mergerfs.srcmounts\ =/tmp/c\ .mergerfs
[trapexit:/tmp/mount]\ $\ xattr\ \-p\ user.mergerfs.srcmounts\ .mergerfs
/tmp/c
[trapexit:/tmp/mount]\ $\ xattr\ \-w\ user.mergerfs.srcmounts\ \[aq]+</tmp/a:/tmp/b\[aq]\ .mergerfs
[trapexit:/tmp/mount]\ $\ xattr\ \-p\ user.mergerfs.srcmounts\ .mergerfs
/tmp/a:/tmp/b:/tmp/c
\f[]
.fi
.SS user.mergerfs.srcmounts
.PP
For \f[B]user.mergerfs.srcmounts\f[] there are several instructions
@ -559,7 +512,37 @@ Input: short policy string as described elsewhere in this document
.PP
Output: the policy string except for categories where its funcs have
multiple types.
In that case it will be a comma separated list.
In that case it will be a comma separated list
.SS Example
.IP
.nf
\f[C]
[trapexit:/tmp/mount]\ $\ xattr\ \-l\ .mergerfs
user.mergerfs.srcmounts:\ /tmp/a:/tmp/b
user.mergerfs.minfreespace:\ 4294967295
user.mergerfs.moveonenospc:\ false
\&...
[trapexit:/tmp/mount]\ $\ xattr\ \-p\ user.mergerfs.category.search\ .mergerfs
ff
[trapexit:/tmp/mount]\ $\ xattr\ \-w\ user.mergerfs.category.search\ fwfs\ .mergerfs
[trapexit:/tmp/mount]\ $\ xattr\ \-p\ user.mergerfs.category.search\ .mergerfs
fwfs
[trapexit:/tmp/mount]\ $\ xattr\ \-w\ user.mergerfs.srcmounts\ +/tmp/c\ .mergerfs
[trapexit:/tmp/mount]\ $\ xattr\ \-p\ user.mergerfs.srcmounts\ .mergerfs
/tmp/a:/tmp/b:/tmp/c
[trapexit:/tmp/mount]\ $\ xattr\ \-w\ user.mergerfs.srcmounts\ =/tmp/c\ .mergerfs
[trapexit:/tmp/mount]\ $\ xattr\ \-p\ user.mergerfs.srcmounts\ .mergerfs
/tmp/c
[trapexit:/tmp/mount]\ $\ xattr\ \-w\ user.mergerfs.srcmounts\ \[aq]+</tmp/a:/tmp/b\[aq]\ .mergerfs
[trapexit:/tmp/mount]\ $\ xattr\ \-p\ user.mergerfs.srcmounts\ .mergerfs
/tmp/a:/tmp/b:/tmp/c
\f[]
.fi
.SS mergerfs file xattrs
.PP
While they won\[aq]t show up when using
@ -598,11 +581,14 @@ A\ B\ C
.fi
.SH TOOLING
.PP
Find extra tooling to help with managing \f[C]mergerfs\f[] at:
Find tooling to help with managing \f[C]mergerfs\f[] at:
https://github.com/trapexit/mergerfs\-tools
.IP \[bu] 2
fsck.mergerfs: Provides permissions and ownership auditing and the
ability to fix them
.IP \[bu] 2
mergerfs.mktrash: Creates FreeDesktop.org Trash specification compatible
directories on a mergerfs mount
.SH TIPS / NOTES
.IP \[bu] 2
If you don\[aq]t see some directories / files you expect in a merged
@ -660,12 +646,25 @@ Due to previously mentioned issues its generally best to set
\f[B]func\f[]\[aq]s.
This will help limit the confusion of tools such as
rsync (http://linux.die.net/man/1/rsync).
.SH Known Issues / Bugs
.SS Samba
.IP \[bu] 2
Moving files or directories between some directories on a SMB share fail
with IO errors.
.RS 2
.SH KNOWN ISSUES / BUGS
.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 Samba: Moving files / directories fails
.PP
Workaround: Copy the file/directory and then remove the original rather
than move.
@ -699,27 +698,24 @@ 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.
.RE
.SS Supplemental groups
.IP \[bu] 2
.SS Supplemental user groups
.PP
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 mount or thread.
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\[aq]s (at least the standard
version) thread pool dynamically grows and shrinks it\[aq]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.
.RS 2
.PP
The gid cache uses fixed storage to simplify the design and be
compatible with older systems which may not have C++11 compilers (as the
original design required).
compatible with older systems which may not have C++11 compilers.
There is enough storage for 256 users\[aq] supplemental groups.
Each user is allowed upto 32 supplemental groups.
Linux >= 2.6.3 allows upto 65535 groups per user but most other *nixs
@ -735,11 +731,43 @@ fine.
If either value is too low for your needs you will have to modify
\f[C]gidcache.hpp\f[] to increase the values.
Note that doing so will increase the memory needed by each thread.
.RE
.SH FAQ
.SS mergerfs or libfuse crashing
.PP
\f[I]It\[aq]s mentioned that there are some security issues with mhddfs.
What are they? How does mergerfs address them?\f[]
If suddenly the mergerfs mount point disappears and
\f[C]Transport\ endpoint\ is\ not\ connected\f[] is returned when
attempting to perform actions within the mount directory \f[B]and\f[]
the version of libfuse (use \f[C]mergerfs\ \-v\f[] to find the version)
is older than \f[C]2.9.4\f[] its likely due to a bug in libfuse.
Affected versions of libfuse can be found in Debian Wheezy, Ubuntu
Precise and others.
.PP
In order to fix this please install newer versions of libfuse.
If using a Debian based distro (Debian,Ubuntu,Mint) you can likely just
install newer versions of
libfuse (https://packages.debian.org/unstable/libfuse2) and
fuse (https://packages.debian.org/unstable/fuse) from the repo of a
newer release.
.SH FAQ
.SS Why use mergerfs over mhddfs?
.PP
mhddfs is no longer maintained and has some known stability and security
issues (see below).
.SS Why use mergerfs over aufs?
.PP
While aufs can offer better peak performance mergerfs offers more
configurability and is generally easier to use.
mergerfs however doesn\[aq]t offer the overlay features which tends to
result in whiteout files being left around the underlying filesystems.
.SS Why use mergerfs over LVM/ZFS/BTRFS/RAID0 drive concatenation /
striping?
.PP
A single drive failure will lead to full pool failure without additional
redundancy.
mergerfs performs a similar behavior without the catastrophic failure
and lack of recovery.
Drives can fail and all other data will continue to be accessable.
.SS It\[aq]s mentioned that there are some security issues with mhddfs.
What are they? How does mergerfs address them?
.PP
mhddfs (https://github.com/trapexit/mhddfs) tries to handle being run as
\f[B]root\f[] by calling
@ -775,7 +803,7 @@ pthread_setugid_np (https://developer.apple.com/library/mac/documentation/Darwin
but user and group IDs are a per\-thread attribute though documentation
on that fact or how to manipulate them is not well distributed.
From the \f[B]4.00\f[] release of the Linux man\-pages project for
setuid (http://man7.org/linux/man-pages/man2/setuid.2.html)
setuid (http://man7.org/linux/man-pages/man2/setuid.2.html).
.RS
.PP
At the kernel level, user IDs and group IDs are a per\-thread attribute.