From 77f098614fd1f2b82949c4afa38be5af6fc2f14c Mon Sep 17 00:00:00 2001 From: Antonio SJ Musumeci Date: Mon, 23 May 2022 11:26:32 -0400 Subject: [PATCH] Add details about usage of FUSE to docs --- README.md | 28 +++++++++++++++++++++++++++- man/mergerfs.1 | 38 +++++++++++++++++++++++++++++++++++++- 2 files changed, 64 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 07df4586..18206fff 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ % mergerfs(1) mergerfs user manual % Antonio SJ Musumeci -% 2022-04-25 +% 2022-05-23 # NAME @@ -1111,6 +1111,32 @@ Whenever you run into a split permission issue (seeing some but not all files) t If using a network filesystem such as NFS, SMB, CIFS (Samba) be sure to pay close attention to anything regarding permissioning and users. Root squashing and user translation for instance has bitten a few mergerfs users. Some of these also affect the use of mergerfs from container platforms such as Docker. +#### Why use FUSE? Why not a kernel based solution? + +As with any two solutions to a problem there are advantages and disadvantages to each one. + +A FUSE based solution has all the downsides of FUSE: + +* Higher IO latency due to the trips in and out of kernel space +* Higher general overhead due to trips in and out of kernel space +* Double caching when using page caching +* Misc limitations due to FUSE's design + +But FUSE also has a lot of upsides: + +* Easier to offer a cross platform solution +* Easier forward and backward compatibility +* Easier updates for users +* Easier and faster release cadence +* Allows more flexibility in design and features +* Overall easier to write, secure, and maintain +* Ability to run without root access or need to change the kernel +* Much lower barrier to entry (getting code into the kernel takes a lot of time and effort initially) + + +FUSE was chosen because of all the advantages listed above. The negatives of FUSE do not outweight the positives. + + #### Is my OS's libfuse needed for mergerfs to work? No. Normally `mount.fuse` is needed to get mergerfs (or any FUSE filesystem to mount using the `mount` command but in vendoring the libfuse library the `mount.fuse` app has been renamed to `mount.mergerfs` meaning the filesystem type in `fstab` can simply be `mergerfs`. That said there should be no harm in having it installed and continuing to using `fuse.mergerfs` as the type in `/etc/fstab`. diff --git a/man/mergerfs.1 b/man/mergerfs.1 index d34859cf..46976bcc 100644 --- a/man/mergerfs.1 +++ b/man/mergerfs.1 @@ -1,7 +1,7 @@ .\"t .\" Automatically generated by Pandoc 2.5 .\" -.TH "mergerfs" "1" "2022\-04\-25" "mergerfs user manual" "" +.TH "mergerfs" "1" "2022\-05\-23" "mergerfs user manual" "" .hy .SH NAME .PP @@ -2433,6 +2433,42 @@ Root squashing and user translation for instance has bitten a few mergerfs users. Some of these also affect the use of mergerfs from container platforms such as Docker. +.SS Why use FUSE? Why not a kernel based solution? +.PP +As with any two solutions to a problem there are advantages and +disadvantages to each one. +.PP +A FUSE based solution has all the downsides of FUSE: +.IP \[bu] 2 +Higher IO latency due to the trips in and out of kernel space +.IP \[bu] 2 +Higher general overhead due to trips in and out of kernel space +.IP \[bu] 2 +Double caching when using page caching +.IP \[bu] 2 +Misc limitations due to FUSE\[cq]s design +.PP +But FUSE also has a lot of upsides: +.IP \[bu] 2 +Easier to offer a cross platform solution +.IP \[bu] 2 +Easier forward and backward compatibility +.IP \[bu] 2 +Easier updates for users +.IP \[bu] 2 +Easier and faster release cadence +.IP \[bu] 2 +Allows more flexibility in design and features +.IP \[bu] 2 +Overall easier to write, secure, and maintain +.IP \[bu] 2 +Ability to run without root access or need to change the kernel +.IP \[bu] 2 +Much lower barrier to entry (getting code into the kernel takes a lot of +time and effort initially) +.PP +FUSE was chosen because of all the advantages listed above. +The negatives of FUSE do not outweight the positives. .SS Is my OS\[cq]s libfuse needed for mergerfs to work? .PP No.\ Normally \f[C]mount.fuse\f[R] is needed to get mergerfs (or any