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

tweak docs, add FAQ regarding vendoring of libfuse

Browse Source
This commit is contained in:
Antonio SJ Musumeci 2018-08-20 13:37:36 -04:00
parent a894360402
commit 587ab62583
2 changed files with 27 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
README.md
View File

@ -1,6 +1,6 @@
% mergerfs(1) mergerfs user manual
% Antonio SJ Musumeci <trapexit@spawn.link>
% 2018-07-25
% 2018-08-20
# NAME
@ -289,7 +289,7 @@ $ sudo make install
#### Generically with system libfuse
**NOTE:** Multithreading and thus `-o threads=num` option will be unavailable when built with system libfuse.
**NOTE:** Configurable threading and thus `-o threads=num` option will be unavailable when built with system libfuse.
Have git, g++, make, python, libattr1, pkg-config installed.
Also, install libfuse >= 2.9.7 (but not libfuse-3.x) and matching libfuse-dev (or libfuse-devel).
@ -631,7 +631,7 @@ Users have reported running mergerfs on everything from a Raspberry Pi to dual s
Yes. MergerFS is a proxy and does **NOT** interfere with the normal form or function of the drives / mounts / paths it manages.
MergerFS is **not** an actual filesystem. MergerFS is **not** RAID. It does **not** manipulate the data that passes through it. It does **not** shard data across drives. It merely shards some **behavior** and aggregates others.
MergerFS is **not** a traditional filesystem. MergerFS is **not** RAID. It does **not** manipulate the data that passes through it. It does **not** shard data across drives. It merely shards some **behavior** and aggregates others.
#### Can mergerfs be removed without affecting the data?
@ -643,7 +643,7 @@ Yes. You need to use `use_ino` to support proper reporting of inodes. Read the s
#### Why can't I see my files / directories?
It's almost always a permissions issue. Unlike mhddfs, which runs as root and attempts to access content as such, mergerfs always changes it's credentials to that of the caller. This means that if the user doesn't 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 read some files and directories on one drive but not another resulting in an incomplete set.
It's almost always a permissions issue. Unlike mhddfs, which runs as root and attempts to access content as such, mergerfs always changes it's 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 read some files and directories on one drive but not another resulting in an incomplete set.
Whenever you run into a split permission issue (seeing some but not all files) try using [mergerfs.fsck](https://github.com/trapexit/mergerfs-tools) tool to check for and fix the mismatch. If you aren't seeing anything at all be sure that the basic permissions are correct. The user and group values are correct and that directories have their executable bit set. A common mistake by users new to Linux is to `chmod -R 644` when they should have `chmod -R u=rwX,go=rX`.
@ -655,6 +655,10 @@ Are you using a path preserving policy? The default policy for file creation is
This can be especially apparent when filling an empty pool from an external source. If you do want path preservation you'll need to perform the manual act of creating paths on the drives you want the data to land on before transfering your data.
#### Why was libfuse embedded into mergerfs?
A significant number of users use mergerfs on distros with very old versions of libfuse which have serious bugs. Requiring updated versions of libfuse on those distros isn't pratical (no package offered, user inexperience, etc.). The only practical way to provide a stable runtime on those systems was to "vendor" the library into the project.
#### Why use mergerfs over mhddfs?
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.
@ -667,6 +671,8 @@ Below is an example of mhddfs and mergerfs setup to work similarly.
#### Why use mergerfs over aufs?
aufs is mostly abandoned and no longer available in many distros.
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.
#### Why use mergerfs over unionfs?

24
man/mergerfs.1
View File

@ -1,7 +1,7 @@
.\"t
.\" Automatically generated by Pandoc 1.19.2.1
.\" Automatically generated by Pandoc 1.19.2.4
.\"
.TH "mergerfs" "1" "2018\-07\-25" "mergerfs user manual" ""
.TH "mergerfs" "1" "2018\-08\-20" "mergerfs user manual" ""
.hy
.SH NAME
.PP
@ -702,8 +702,8 @@ $\ sudo\ make\ install
.fi
.SS Generically with system libfuse
.PP
\f[B]NOTE:\f[] Multithreading and thus \f[C]\-o\ threads=num\f[] option
will be unavailable when built with system libfuse.
\f[B]NOTE:\f[] Configurable threading and thus \f[C]\-o\ threads=num\f[]
option will be unavailable when built with system libfuse.
.PP
Have git, g++, make, python, libattr1, pkg\-config installed.
Also, install libfuse >= 2.9.7 (but not libfuse\-3.x) and matching
@ -1341,7 +1341,7 @@ Yes.
MergerFS is a proxy and does \f[B]NOT\f[] interfere with the normal form
or function of the drives / mounts / paths it manages.
.PP
MergerFS is \f[B]not\f[] an actual filesystem.
MergerFS is \f[B]not\f[] a traditional filesystem.
MergerFS is \f[B]not\f[] RAID.
It does \f[B]not\f[] manipulate the data that passes through it.
It does \f[B]not\f[] shard data across drives.
@ -1360,8 +1360,8 @@ 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.
This means that if the user doesn\[aq]t have access to a file or
directory than neither will mergerfs.
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
read some files and directories on one drive but not another resulting
in an incomplete set.
@ -1398,6 +1398,14 @@ external source.
If you do want path preservation you\[aq]ll need to perform the manual
act of creating paths on the drives you want the data to land on before
transfering your data.
.SS Why was libfuse embedded into mergerfs?
.PP
A significant number of users use mergerfs on distros with very old
versions of libfuse which have serious bugs.
Requiring updated versions of libfuse on those distros isn\[aq]t
pratical (no package offered, user inexperience, etc.).
The only practical way to provide a stable runtime on those systems was
to "vendor" the library into the project.
.SS Why use mergerfs over mhddfs?
.PP
mhddfs is no longer maintained and has some known stability and security
@ -1412,6 +1420,8 @@ Below is an example of mhddfs and mergerfs setup to work similarly.
\f[C]mergerfs\ \-o\ minfreespace=4G,defaults,allow_other,category.create=ff\ /mnt/drive1:/mnt/drive2\ /mnt/pool\f[]
.SS Why use mergerfs over aufs?
.PP
aufs is mostly abandoned and no longer available in many distros.
.PP
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)