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

Update README to remove unnecessary references to export-support for NFS

Browse Source
This commit is contained in:
Antonio SJ Musumeci 2024-02-25 17:27:08 -06:00
parent 951eb9540d
commit a234e9446c
2 changed files with 31 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
README.md
View File

@ -682,21 +682,13 @@ is empty is opened for writing.
In theory this flag should not be exposed to the end user. It is a In theory this flag should not be exposed to the end user. It is a
low-level FUSE flag which indicates whether or not the kernel can send low-level FUSE flag which indicates whether or not the kernel can send
certain kinds of messages to it for the purposes of using with certain kinds of messages to it for the purposes of using with
NFS. mergerfs does support these messages but due to a possible bug in NFS. mergerfs does support these messages but due bugs and quirks
the Linux kernel this option needs to be configurable. As it turns out found in the kernel and mergerfs this option is provided just in case
at least certain versions of NFS can still work when disabled and no it is needed for debugging.
longer triggers the bug.
While it may be safe to default this setting to `false` in an
abundance of caution it is being left enabled by default.
Given that this flag is set when the FUSE connection is first Given that this flag is set when the FUSE connection is first
initiated it is not possible to change during run time. initiated it is not possible to change during run time.
See [Kernel Issues &
Bugs](https://github.com/trapexit/mergerfs/wiki/Kernel-Issues-&-Bugs)
for more details.
# FUNCTIONS, CATEGORIES and POLICIES # FUNCTIONS, CATEGORIES and POLICIES
@ -2047,17 +2039,19 @@ remote filesystem on Unix/POSIX systems. Due to how NFS works there
are some settings which need to be set in order for mergerfs to work are some settings which need to be set in order for mergerfs to work
with it. with it.
It should be noted that NFS and FUSE (the technology mergerfs uses) It should be noted that NFS and FUSE (the technology mergerfs uses) do
do not work perfectly with one another due to certain design not work perfectly with one another due to certain design choices in
choices in FUSE (and mergerfs.) Due to these issues it is FUSE (and mergerfs.) Due to these issues it is generally recommended
generally recommended to use SMB when possible till situations to use SMB when possible till situations change. That said mergerfs
change. That said issues should still be reported. NFS is not really should generally work as an export of NFS and issues discovered should
recommended but it isn't unsupported. still be reported.
To ensure compatibility between mergerfs and NFS use the following
settings.
mergerfs settings: mergerfs settings:
* noforget * noforget
* inodecalc=path-hash * inodecalc=path-hash
* export-support=false (only available in v2.40.0 and above)
NFS export settings: NFS export settings:
* fsid=UUID * fsid=UUID
@ -2080,32 +2074,17 @@ calculation algorithm then it is possible that if you changed a file
or updated a directory the file mergerfs will use will be on a or updated a directory the file mergerfs will use will be on a
different branch and therefore the inode would change. This isn't an different branch and therefore the inode would change. This isn't an
ideal solution and others are being considered but it works for most ideal solution and others are being considered but it works for most
situations. It might be possible to leave the default value of situations.
`hybrid-hash` if `export-support=false` but it hasn't been fully
tested yet.
`export-support=false` is a low-level FUSE option that is needed as a
workaround to a Linux kernel bug. Technically this option should be
set to `true` when expecting to use mergerfs with NFS but it turns out
that at least some versions of NFS work when not enabled. At the
moment it is unclear if this has any negative side effects but when
disabled NFS appears to work alright and the kernel no longer sends
invalid requests. When the issue is resolved in the kernel these docs
will be updated with appropriate details.
Also see [Kernel Issues &
Bugs](https://github.com/trapexit/mergerfs/wiki/Kernel-Issues-&-Bugs)
for more details.
`fsid=UUID` is needed because FUSE filesystems don't have different `fsid=UUID` is needed because FUSE filesystems don't have different
`st_dev` values which can cause issues when exporting. The easiest `st_dev` values which can cause issues when exporting. The easiest
thing to do is set each mergerfs export `fsid` to some random thing to do is set each mergerfs export `fsid` to some random
value. An easy way to generate a random value is to use the command value. An easy way to generate a random value is to use the command
line tool `uuidgen` or through a website such as line tool `uuid` or `uuidgen` or through a website such as
[uuidgenerator.net](https://www.uuidgenerator.net/). [uuidgenerator.net](https://www.uuidgenerator.net/).
`no_root_squash` is not strictly necessary but can lead to confusing `no_root_squash` is not strictly necessary but can lead to confusing
permission and ownership issues. permission and ownership issues if root squashing is enabled.
## SMB / CIFS ## SMB / CIFS

54
man/mergerfs.1
View File

@ -115,7 +115,7 @@ start with one of the following option sets.
\f[C]mergerfs -o cache.files=partial,dropcacheonclose=true,category.create=mfs /mnt/hdd0:/mnt/hdd1 /media\f[R] \f[C]mergerfs -o cache.files=partial,dropcacheonclose=true,category.create=mfs /mnt/hdd0:/mnt/hdd1 /media\f[R]
.SS /etc/fstab .SS /etc/fstab
.PP .PP
\f[C]/mnt/hdd0:/mnt/hdd1 /media fuse.mergerfs cache.files=partial,dropcacheonclose=true,category.create=mfs 0 0\f[R] \f[C]/mnt/hdd0:/mnt/hdd1 /media mergerfs cache.files=partial,dropcacheonclose=true,category.create=mfs 0 0\f[R]
.SS systemd mount .SS systemd mount
.PP .PP
https://github.com/trapexit/mergerfs/wiki/systemd https://github.com/trapexit/mergerfs/wiki/systemd
@ -517,7 +517,7 @@ tools use \f[B]/etc/fstab\f[R].
.nf .nf
\f[C] \f[C]
# <file system> <mount point> <type> <options> <dump> <pass> # <file system> <mount point> <type> <options> <dump> <pass>
/mnt/hdd*:/mnt/ssd /media fuse.mergerfs minfreespace=16G 0 0 /mnt/hdd*:/mnt/ssd /media mergerfs minfreespace=16G 0 0
\f[R] \f[R]
.fi .fi
.PP .PP
@ -847,20 +847,12 @@ In theory this flag should not be exposed to the end user.
It is a low-level FUSE flag which indicates whether or not the kernel It is a low-level FUSE flag which indicates whether or not the kernel
can send certain kinds of messages to it for the purposes of using with can send certain kinds of messages to it for the purposes of using with
NFS. NFS.
mergerfs does support these messages but due to a possible bug in the mergerfs does support these messages but due bugs and quirks found in
Linux kernel this option needs to be configurable. the kernel and mergerfs this option is provided just in case it is
As it turns out at least certain versions of NFS can still work when needed for debugging.
disabled and no longer triggers the bug.
.PP
While it may be safe to default this setting to \f[C]false\f[R] in an
abundance of caution it is being left enabled by default.
.PP .PP
Given that this flag is set when the FUSE connection is first initiated Given that this flag is set when the FUSE connection is first initiated
it is not possible to change during run time. it is not possible to change during run time.
.PP
See Kernel Issues &
Bugs (https://github.com/trapexit/mergerfs/wiki/Kernel-Issues-&-Bugs)
for more details.
.SH FUNCTIONS, CATEGORIES and POLICIES .SH FUNCTIONS, CATEGORIES and POLICIES
.PP .PP
The POSIX filesystem API is made up of a number of functions. The POSIX filesystem API is made up of a number of functions.
@ -1577,8 +1569,8 @@ apply those before mounting the new version.
\f[C] \f[C]
$ sudo mount /mnt/mergerfs $ sudo mount /mnt/mergerfs
$ mount | grep mergerfs $ mount | grep mergerfs
media on /mnt/mergerfs type fuse.mergerfs (rw,relatime,user_id=0,group_id=0,default_permissions,allow_other) media on /mnt/mergerfs type mergerfs (rw,relatime,user_id=0,group_id=0,default_permissions,allow_other)
media on /mnt/mergerfs type fuse.mergerfs (rw,relatime,user_id=0,group_id=0,default_permissions,allow_other) media on /mnt/mergerfs type mergerfs (rw,relatime,user_id=0,group_id=0,default_permissions,allow_other)
\f[R] \f[R]
.fi .fi
.PP .PP
@ -2588,11 +2580,13 @@ It should be noted that NFS and FUSE (the technology mergerfs uses) do
not work perfectly with one another due to certain design choices in not work perfectly with one another due to certain design choices in
FUSE (and mergerfs.) Due to these issues it is generally recommended to FUSE (and mergerfs.) Due to these issues it is generally recommended to
use SMB when possible till situations change. use SMB when possible till situations change.
That said issues should still be reported. That said mergerfs should generally work as an export of NFS and issues
NFS is not really recommended but it isn\[cq]t unsupported. discovered should still be reported.
.PP .PP
mergerfs settings: * noforget * inodecalc=path-hash * To ensure compatibility between mergerfs and NFS use the following
export-support=false (only available in v2.40.0 and above) settings.
.PP
mergerfs settings: * noforget * inodecalc=path-hash
.PP .PP
NFS export settings: * fsid=UUID * no_root_squash NFS export settings: * fsid=UUID * no_root_squash
.PP .PP
@ -2618,35 +2612,17 @@ mergerfs will use will be on a different branch and therefore the inode
would change. would change.
This isn\[cq]t an ideal solution and others are being considered but it This isn\[cq]t an ideal solution and others are being considered but it
works for most situations. works for most situations.
It might be possible to leave the default value of \f[C]hybrid-hash\f[R]
if \f[C]export-support=false\f[R] but it hasn\[cq]t been fully tested
yet.
.PP
\f[C]export-support=false\f[R] is a low-level FUSE option that is needed
as a workaround to a Linux kernel bug.
Technically this option should be set to \f[C]true\f[R] when expecting
to use mergerfs with NFS but it turns out that at least some versions of
NFS work when not enabled.
At the moment it is unclear if this has any negative side effects but
when disabled NFS appears to work alright and the kernel no longer sends
invalid requests.
When the issue is resolved in the kernel these docs will be updated with
appropriate details.
.PP
Also see Kernel Issues &
Bugs (https://github.com/trapexit/mergerfs/wiki/Kernel-Issues-&-Bugs)
for more details.
.PP .PP
\f[C]fsid=UUID\f[R] is needed because FUSE filesystems don\[cq]t have \f[C]fsid=UUID\f[R] is needed because FUSE filesystems don\[cq]t have
different \f[C]st_dev\f[R] values which can cause issues when exporting. different \f[C]st_dev\f[R] values which can cause issues when exporting.
The easiest thing to do is set each mergerfs export \f[C]fsid\f[R] to The easiest thing to do is set each mergerfs export \f[C]fsid\f[R] to
some random value. some random value.
An easy way to generate a random value is to use the command line tool An easy way to generate a random value is to use the command line tool
\f[C]uuidgen\f[R] or through a website such as \f[C]uuid\f[R] or \f[C]uuidgen\f[R] or through a website such as
uuidgenerator.net (https://www.uuidgenerator.net/). uuidgenerator.net (https://www.uuidgenerator.net/).
.PP .PP
\f[C]no_root_squash\f[R] is not strictly necessary but can lead to \f[C]no_root_squash\f[R] is not strictly necessary but can lead to
confusing permission and ownership issues. confusing permission and ownership issues if root squashing is enabled.
.SS SMB / CIFS .SS SMB / CIFS
.PP .PP
SMB (https://en.wikipedia.org/wiki/Server_Message_Block) is a protocol SMB (https://en.wikipedia.org/wiki/Server_Message_Block) is a protocol