From 7d761777a49f333dafb7951832a801735ee77984 Mon Sep 17 00:00:00 2001 From: Antonio SJ Musumeci Date: Wed, 1 Jan 2025 23:01:38 -0600 Subject: [PATCH] Deployed 04186919 with MkDocs version: 1.6.1 --- 404.html | 23 +- benchmarking/index.html | 23 +- config/branches/index.html | 23 +- config/cache/index.html | 23 +- config/deprecated_options/index.html | 23 +- config/export-support.md~ | 11 - config/export-support/index.html | 26 +- config/flush-on-close/index.html | 33 +- config/follow-symlinks.md~ | 16 - config/follow-symlinks/index.html | 24 +- config/func_readdir/index.html | 23 +- .../index.html | 248 +-- config/fuse_msg_size.md~ | 6 - config/fuse_msg_size/index.html | 27 +- config/inodecalc.md~ | 47 - config/inodecalc/index.html | 23 +- config/ioctl/index.html | 1590 ----------------- config/link-exdev.md~ | 11 - config/link-exdev/index.html | 24 +- config/link_cow.md~ | 2 + config/link_cow/index.html | 34 +- config/nfsopenhack.md~ | 20 - config/nfsopenhack/index.html | 30 +- config/nullrw.md~ | 16 - config/nullrw/index.html | 27 +- config/options/index.html | 23 +- config/pin-threads.md~ | 15 - config/pin-threads/index.html | 23 +- config/readahead.md~ | 2 + config/readahead/index.html | 54 +- config/rename-exdev.md~ | 19 - config/rename-exdev/index.html | 24 +- config/rename_and_link/index.html | 23 +- config/statfs/index.html | 104 +- config/symlinkify.md~ | 20 + config/symlinkify/index.html | 27 +- config/terminology/index.html | 23 +- config/threads.md~ | 9 + config/threads/index.html | 63 +- config/xattr.md~ | 7 - config/xattr/index.html | 24 +- error_handling/index.html | 23 +- faq/compatibility_and_integration/index.html | 23 +- faq/configuration_and_policies/index.html | 23 +- faq/limit_drive_spinup/index.html | 87 +- faq/recommendations_and_warnings/index.html | 23 +- faq/reliability_and_scalability/index.html | 23 +- .../index.html | 27 +- faq/usage_and_functionality/index.html | 23 +- index.html | 23 +- known_issues_bugs/index.html | 23 +- media_and_publicity/index.html | 23 +- performance/index.html | 23 +- project_comparisons/index.html | 23 +- quickstart/index.html | 23 +- related_projects/index.html | 27 +- remote_filesystems/index.html | 23 +- runtime_interfaces/index.html | 23 +- search/search_index.json | 2 +- setup/build/index.html | 23 +- setup/installation/index.html | 23 +- setup/upgrade/index.html | 23 +- sitemap.xml | 102 +- sitemap.xml.gz | Bin 689 -> 687 bytes sponsorship_and_donations/index.html | 27 +- support/index.html | 66 +- tips_notes/index.html | 23 +- tooling/index.html | 23 +- 68 files changed, 374 insertions(+), 3214 deletions(-) delete mode 100644 config/export-support.md~ delete mode 100644 config/follow-symlinks.md~ delete mode 100644 config/fuse_msg_size.md~ delete mode 100644 config/inodecalc.md~ delete mode 100644 config/ioctl/index.html delete mode 100644 config/link-exdev.md~ create mode 100644 config/link_cow.md~ delete mode 100644 config/nfsopenhack.md~ delete mode 100644 config/nullrw.md~ delete mode 100644 config/pin-threads.md~ create mode 100644 config/readahead.md~ delete mode 100644 config/rename-exdev.md~ create mode 100644 config/symlinkify.md~ create mode 100644 config/threads.md~ delete mode 100644 config/xattr.md~ diff --git a/404.html b/404.html index a85b4ff9..1edd8770 100644 --- a/404.html +++ b/404.html @@ -877,27 +877,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1314,7 +1293,7 @@ - Limit drive spinup + Limiting drive spinup diff --git a/benchmarking/index.html b/benchmarking/index.html index dd3d7c1f..654d6862 100644 --- a/benchmarking/index.html +++ b/benchmarking/index.html @@ -888,27 +888,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1392,7 +1371,7 @@ - Limit drive spinup + Limiting drive spinup diff --git a/config/branches/index.html b/config/branches/index.html index 3ba3f0cd..e84fdfc6 100644 --- a/config/branches/index.html +++ b/config/branches/index.html @@ -957,27 +957,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1394,7 +1373,7 @@ - Limit drive spinup + Limiting drive spinup diff --git a/config/cache/index.html b/config/cache/index.html index cdfcbef6..5c201ebe 100644 --- a/config/cache/index.html +++ b/config/cache/index.html @@ -1002,27 +1002,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1439,7 +1418,7 @@ - Limit drive spinup + Limiting drive spinup diff --git a/config/deprecated_options/index.html b/config/deprecated_options/index.html index d9a26005..5572b9a2 100644 --- a/config/deprecated_options/index.html +++ b/config/deprecated_options/index.html @@ -900,27 +900,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup diff --git a/config/export-support.md~ b/config/export-support.md~ deleted file mode 100644 index 91c0e3e0..00000000 --- a/config/export-support.md~ +++ /dev/null @@ -1,11 +0,0 @@ -# export-support - -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 -certain kinds of messages to it for the purposes of using it with -NFS. mergerfs does support these messages but due to bugs and quirks -found in the kernel and mergerfs this option is provided just in case -it is needed for debugging. - -Given that this flag is set when the FUSE connection is first -initiated it is not possible to change during run time. diff --git a/config/export-support/index.html b/config/export-support/index.html index 30efb637..0f7bd507 100644 --- a/config/export-support/index.html +++ b/config/export-support/index.html @@ -890,27 +890,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1485,7 +1464,8 @@

    export-support

      -
    • export-support=true|false: Defaults to true.
      • +
    • export-support=true|false
      • +
    • Defaults to true.

    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 diff --git a/config/flush-on-close/index.html b/config/flush-on-close/index.html index 22b916f0..6beed048 100644 --- a/config/flush-on-close/index.html +++ b/config/flush-on-close/index.html @@ -890,27 +890,6 @@ -

  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1376,7 +1355,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1543,13 +1522,13 @@

    By default, FUSE would issue a flush before the release of a file descriptor. This was considered a bit aggressive and a feature added to give the FUSE server the ability to choose when that happens.

    -

    Options:

      -
    • always
      • -
    • never
      • -
    • opened-for-write
      • +
    • flush-on-close=always
      • +
    • flush-on-close=never
      • +
    • flush-on-close=opened-for-write
      • +
    • Defaults to opened-for-write.
    -

    For now it defaults to "opened-for-write" which is less aggressive +

    For now it defaults to opened-for-write which is less aggressive than the behavior before this feature was added. It should not be a problem because the flush is really only relevant when a file is written to. Given flush is irrelevant for many filesystems in the diff --git a/config/follow-symlinks.md~ b/config/follow-symlinks.md~ deleted file mode 100644 index 37090958..00000000 --- a/config/follow-symlinks.md~ +++ /dev/null @@ -1,16 +0,0 @@ -# follow-symlinks - -This feature, when enabled, will cause symlinks to be interpreted by mergerfs as their target (depending on the mode). - -When there is a getattr/stat request for a file mergerfs will check if the file is a symlink and depending on the follow-symlinks setting will replace the information about the symlink with that of that which it points to. - -When unlink'ing or rmdir'ing the followed symlink it will remove the symlink itself and not that which it points to. - -never: Behave as normal. Symlinks are treated as such. -directory: Resolve symlinks only which point to directories. -regular: Resolve symlinks only which point to regular files. -all: Resolve all symlinks to that which they point to. -Symlinks which do not point to anything are left as is. - -WARNING: This feature works but there might be edge cases yet found. If you find any odd behaviors please file a ticket on github. - diff --git a/config/follow-symlinks/index.html b/config/follow-symlinks/index.html index e088582b..355d08de 100644 --- a/config/follow-symlinks/index.html +++ b/config/follow-symlinks/index.html @@ -900,27 +900,6 @@ -

  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1498,6 +1477,7 @@ symlink itself and not that which it points to.

  • follow-symlinks=regular: Resolve symlinks only which point to regular files.
  • follow-symlinks=all: Resolve all symlinks to that which they point to. Symlinks which do not point to anything are left as is.
    • +
  • Defaults to never.

    • WARNING: This feature should be considered experimental. There might be edge cases yet found. If you find any odd behaviors please diff --git a/config/func_readdir/index.html b/config/func_readdir/index.html index 5e6303bf..cd38ae33 100644 --- a/config/func_readdir/index.html +++ b/config/func_readdir/index.html @@ -900,27 +900,6 @@ -

  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup diff --git a/config/functions_categories_and_policies/index.html b/config/functions_categories_and_policies/index.html index 0c38c9b1..83332823 100644 --- a/config/functions_categories_and_policies/index.html +++ b/config/functions_categories_and_policies/index.html @@ -631,57 +631,6 @@ -
    • - -
  • - - - func.readdir - - - -
    • - -
  • - - - ioctl - - - - -
    • @@ -1035,27 +984,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1472,7 +1400,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1647,57 +1575,6 @@ -
    • - -
  • - - - func.readdir - - - -
    • - -
  • - - - ioctl - - - - -
    • @@ -1946,129 +1823,6 @@ policies is not appropriate.

    -

    func.readdir

    -

    examples: func.readdir=seq, func.readdir=cor:4

    -

    readdir has policies to control how it manages reading directory -content.

    - - - - - - - - - - - - - - - - - - - - - -
    PolicyDescription
    seq"sequential" : Iterate over branches in the order defined. This is the default and traditional behavior found prior to the readdir policy introduction. This will be increasingly slower the more banches are defined. Especially if waiting for drives to spinup or network filesystems to respond.
    cosr"concurrent open, sequential read" : Concurrently open branch directories using a thread pool and process them in order of definition. This keeps memory and CPU usage low while also reducing the time spent waiting on branches to respond. Number of threads defaults to the number of logical cores. Can be overwritten via the syntax func.readdir=cosr:N where N is the number of threads.
    cor"concurrent open and read" : Concurrently open branch directories and immediately start reading their contents using a thread pool. This will result in slightly higher memory and CPU usage but reduced latency. Particularly when using higher latency / slower speed network filesystem branches. Unlike seq and cosr the order of files could change due the async nature of the thread pool. Number of threads defaults to the number of logical cores. Can be overwritten via the syntax func.readdir=cor:N where N is the number of threads.
    -

    Keep in mind that readdir mostly just provides a list of file names -in a directory and possibly some basic metadata about said files. To -know details about the files, as one would see from commands like -find or ls, it is required to call stat on the file which is -controlled by fuse.getattr.

    -

    ioctl

    -

    When ioctl is used with an open file then it will use the file -handle which was created at the original open call. However, when -using ioctl with a directory mergerfs will use the open policy to -find the directory to act on.

    - -

    NOTE: If you're receiving errors from software when files are -moved / renamed / linked then you should consider changing the create -policy to one which is not path preserving, enabling -ignorepponrename, or contacting the author of the offending software -and requesting that EXDEV (cross device / improper link) be properly -handled.

    -

    rename and link are tricky functions in a union -filesystem. 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 / improper link). So if a -rename's source and target are on different filesystems within the pool -it creates an issue.

    -

    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 compliant 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.

    -

    As a result a compromise was made in order to get most software to -work while still obeying mergerfs' policies. Below is the basic logic.

    - -

    The removals are subject to normal entitlement checks.

    -

    The above behavior will help minimize the likelihood of EXDEV being -returned but it will still be possible.

    -

    link uses the same strategy but without the removals.

    -

    statfs / statvfs

    -

    statvfs normalizes the source -filesystems 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 filesystem so multiple sources on the same drive will not result in -double counting its space. Other filesystems mounted further down the tree -of the branch will not be included when checking the mount's stats.

    -

    The options statfs and statfs_ignore can be used to modify -statfs behavior.

    -

    flush-on-close

    -

    https://lkml.kernel.org/linux-fsdevel/20211024132607.1636952-1-amir73il@gmail.com/T/

    -

    By default, FUSE would issue a flush before the release of a file -descriptor. This was considered a bit aggressive and a feature added -to give the FUSE server the ability to choose when that happens.

    -

    Options:

    - -

    For now it defaults to "opened-for-write" which is less aggressive -than the behavior before this feature was added. It should not be a -problem because the flush is really only relevant when a file is -written to. Given flush is irrelevant for many filesystems in the -future a branch specific flag may be added so only files opened on a -specific branch would be flushed on close.

    diff --git a/config/fuse_msg_size.md~ b/config/fuse_msg_size.md~ deleted file mode 100644 index a3ce2c60..00000000 --- a/config/fuse_msg_size.md~ +++ /dev/null @@ -1,6 +0,0 @@ -# fuse_msg_size -FUSE applications communicate with the kernel over a special character device: /dev/fuse. A large portion of the overhead associated with FUSE is the cost of going back and forth between user space and kernel space over that device. Generally speaking, the fewer trips needed the better the performance will be. Reducing the number of trips can be done a number of ways. Kernel level caching and increasing message sizes being two significant ones. When it comes to reads and writes if the message size is doubled the number of trips are approximately halved. - -In Linux 4.20 a new feature was added allowing the negotiation of the max message size. Since the size is in multiples of pages the feature is called max_pages. There is a maximum max_pages value of 256 (1MiB) and minimum of 1 (4KiB). The default used by Linux >=4.20, and hardcoded value used before 4.20, is 32 (128KiB). In mergerfs it's referred to as fuse_msg_size to make it clear what it impacts and provide some abstraction. - -Since there should be no downsides to increasing fuse_msg_size / max_pages, outside a minor bump in RAM usage due to larger message buffers, mergerfs defaults the value to 256. On kernels before 4.20 the value has no effect. The reason the value is configurable is to enable experimentation and benchmarking. See the BENCHMARKING section for examples. diff --git a/config/fuse_msg_size/index.html b/config/fuse_msg_size/index.html index 72e94e03..52cf4bc9 100644 --- a/config/fuse_msg_size/index.html +++ b/config/fuse_msg_size/index.html @@ -900,27 +900,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1484,6 +1463,10 @@

    fuse_msg_size

    +
      +
    • fuse_msg_size=UINT
      • +
    • Defaults to 256
      • +

    FUSE applications communicate with the kernel over a special character device: /dev/fuse. A large portion of the overhead associated with FUSE is the cost of going back and forth between user space and kernel diff --git a/config/inodecalc.md~ b/config/inodecalc.md~ deleted file mode 100644 index 004b8558..00000000 --- a/config/inodecalc.md~ +++ /dev/null @@ -1,47 +0,0 @@ -# inodecalc - -Inodes (st_ino) are unique identifiers within a filesystem. Each -mounted filesystem has device ID (st_dev) as well and together they -can uniquely identify a file on the whole of the system. Entries on -the same device with the same inode are in fact references to the same -underlying file. It is a many to one relationship between names and an -inode. Directories, however, do not have multiple links on most -systems due to the complexity they add. - -FUSE allows the server (mergerfs) to set inode values but not device -IDs. Creating an inode value is somewhat complex in mergerfs' case as -files aren't really in its control. If a policy changes what directory -or file is to be selected or something changes out of band it becomes -unclear what value should be used. Most software does not to care what -the values are but those that do often break if a value changes -unexpectedly. The tool find will abort a directory walk if it sees a -directory inode change. NFS can return stale handle errors if the -inode changes out of band. File dedup tools will usually leverage -device ids and inodes as a shortcut in searching for duplicate files -and would resort to full file comparisons should it find different -inode values. - -mergerfs offers multiple ways to calculate the inode in hopes of -covering different usecases. - -* `passthrough`: Passes through the underlying inode value. Mostly - intended for testing as using this does not address any of the - problems mentioned above and could confuse file deduplication - software as inodes from different filesystems can be the same. -* `path-hash`: Hashes the relative path of the entry in question. The - underlying file's values are completely ignored. This means the - inode value will always be the same for that file path. This is - useful when using NFS and you make changes out of band such as copy - data between branches. This also means that entries that do point to - the same file will not be recognizable via inodes. That does not - mean hard links don't work. They will. -* `path-hash32`: 32bit version of path-hash. -* `devino-hash`: Hashes the device id and inode of the underlying - entry. This won't prevent issues with NFS should the policy pick a - different file or files move out of band but will present the same - inode for underlying files that do too. -* `devino-hash32`: 32bit version of devino-hash. - -hybrid-hash: Performs path-hash on directories and devino-hash on other file types. Since directories can't have hard links the static value won't make a difference and the files will get values useful for finding duplicates. Probably the best to use if not using NFS. As such it is the default. - -hybrid-hash32: 32bit version of hybrid-hash. diff --git a/config/inodecalc/index.html b/config/inodecalc/index.html index 184ed7c7..aafc3f0d 100644 --- a/config/inodecalc/index.html +++ b/config/inodecalc/index.html @@ -900,27 +900,6 @@ -

  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup diff --git a/config/ioctl/index.html b/config/ioctl/index.html deleted file mode 100644 index 03992a8c..00000000 --- a/config/ioctl/index.html +++ /dev/null @@ -1,1590 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - ioctl - mergerfs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - - - - Skip to content - - -
    -
    - -
    - - - - - - -
    - - -
    - -
    - - - - - - -
    -
    - - - -
    -
    -
    - - - - - -
    -
    -
    - - - -
    -
    -
    - - - -
    -
    -
    - - - -
    -
    - - - - - - - - - - - - - - - - - - - - -

    ioctl

    -

    When ioctl is used with an open file then it will use the file -handle which was created at the original open call. However, when -using ioctl with a directory mergerfs will use the open policy to -find the directory to act on.

    - - - - - - - - - - - - - -
    -
    - - - -
    - - - -
    - - - -
    -
    -
    -
    - - - - - - - - - - \ No newline at end of file diff --git a/config/link-exdev.md~ b/config/link-exdev.md~ deleted file mode 100644 index 3904e56d..00000000 --- a/config/link-exdev.md~ +++ /dev/null @@ -1,11 +0,0 @@ -# link-exdev - -If using path preservation and a `link` fails with `EXDEV` make a call -to symlink where the target is the oldlink and the linkpath is the -newpath. The target value is determined by the value of link-exdev. - -passthrough: Return EXDEV as normal. -rel-symlink: A relative path from the newpath. -abs-base-symlink: An absolute value using the underlying branch. -abs-pool-symlink: An absolute value using the mergerfs mount point. -NOTE: It is possible that some applications check the file they link. In those cases, it is possible it will error or complain. diff --git a/config/link-exdev/index.html b/config/link-exdev/index.html index dbccbaee..064c1d8d 100644 --- a/config/link-exdev/index.html +++ b/config/link-exdev/index.html @@ -900,27 +900,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1495,6 +1474,7 @@ the newpath. The target value is determined by the value of underlying branch.
  • link-exdev=abs-pool-symlink: An absolute value using the mergerfs mount point.
    • +
  • Defaults to passthrough.

    • NOTE: It is possible that some applications check the file they link. In those cases, it is possible it will error or complain.

    diff --git a/config/link_cow.md~ b/config/link_cow.md~ new file mode 100644 index 00000000..fd7824cf --- /dev/null +++ b/config/link_cow.md~ @@ -0,0 +1,2 @@ +# link_cow + diff --git a/config/link_cow/index.html b/config/link_cow/index.html index d0fa34c0..81de0979 100644 --- a/config/link_cow/index.html +++ b/config/link_cow/index.html @@ -900,27 +900,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1484,6 +1463,17 @@

    link_cow

    +
      +
    • link_cow=true|false
      • +
    • Defaults to false
      • +
    +

    This feature offers similar functionality to what +cow-shell +offers.

    +

    When enabled if mergerfs is asked to open a file to write and the link +count on the file is greater than 1 it will copy the file to a +temporary new file and then rename it over the original. This will +atomically "break" the link. After that it will open the new file.

    diff --git a/config/nfsopenhack.md~ b/config/nfsopenhack.md~ deleted file mode 100644 index dce12636..00000000 --- a/config/nfsopenhack.md~ +++ /dev/null @@ -1,20 +0,0 @@ -# nfsopenhack - -NFS is not fully POSIX compliant and historically certain behaviors, -such as opening files with O_EXCL, are not or not well supported. When -mergerfs (or any FUSE filesystem) is exported over NFS some of these -issues come up due to how NFS and FUSE interact. - -This hack addresses the issue where the creation of a file with a -read-only mode but with a read/write or write only flag. Normally this -is perfectly valid but NFS chops the one open call into multiple -calls. Exactly how it is translated depends on the configuration and -versions of the NFS server and clients but it results in a permission -error because a normal user is not allowed to open a read-only file as -writable. - -Even though it's a more niche situation this hack breaks normal -security and behavior and as such is `off` by default. If set to `git` -it will only perform the hack when the path in question includes -`/.git/`. `all` will result in it applying anytime a read-only file -which is empty is opened for writing. diff --git a/config/nfsopenhack/index.html b/config/nfsopenhack/index.html index 2b510554..1da2963d 100644 --- a/config/nfsopenhack/index.html +++ b/config/nfsopenhack/index.html @@ -16,7 +16,7 @@ - + @@ -900,27 +900,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1489,6 +1468,7 @@
  • nfsopenhack=git: Apply hack if path includes /.git/.
  • nfsopenhack=all: Apply hack on all empty read-only files opened for writing.
    • +
  • Defaults to off.

    • NFS is not fully POSIX compliant and historically certain behaviors, such as opening files with O_EXCL, are not or not well @@ -1558,13 +1538,13 @@ which is empty is opened for writing.

    -     +
    Next
    - ioctl + statfs / statvfs
    diff --git a/config/nullrw.md~ b/config/nullrw.md~ deleted file mode 100644 index 2aa47a32..00000000 --- a/config/nullrw.md~ +++ /dev/null @@ -1,16 +0,0 @@ -# nullrw - -Due to how FUSE works there is an overhead to all requests made to a -FUSE filesystem that wouldn't exist for an in kernel one. Meaning that -even a simple passthrough will have some slowdown. However, generally -the overhead is minimal in comparison to the cost of the underlying -I/O. By disabling the underlying I/O we can test the theoretical -performance boundaries. - -By enabling `nullrw` mergerfs will work as it always does **except** -that all reads and writes will be no-ops. A write will succeed (the -size of the write will be returned as if it were successful) but -mergerfs does nothing with the data it was given. Similarly a read -will return the size requested but won't touch the buffer. - -See the [benchmarking](../benchmarking.md) section for suggestions on how to test. diff --git a/config/nullrw/index.html b/config/nullrw/index.html index 1c1762e4..5a3dcc16 100644 --- a/config/nullrw/index.html +++ b/config/nullrw/index.html @@ -900,27 +900,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1484,6 +1463,10 @@

    nullrw

    +
      +
    • nullrw=true|false
      • +
    • Defaults to false.
      • +

    Due to how FUSE works there is an overhead to all requests made to a FUSE filesystem that wouldn't exist for an in kernel one. Meaning that even a simple passthrough will have some slowdown. However, generally diff --git a/config/options/index.html b/config/options/index.html index ba048e34..fc6dd708 100644 --- a/config/options/index.html +++ b/config/options/index.html @@ -948,27 +948,6 @@ -

  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1385,7 +1364,7 @@ - Limit drive spinup + Limiting drive spinup diff --git a/config/pin-threads.md~ b/config/pin-threads.md~ deleted file mode 100644 index 9d56b94a..00000000 --- a/config/pin-threads.md~ +++ /dev/null @@ -1,15 +0,0 @@ -# pin-threads - -Simple strategies for pinning read and/or process threads. If process -threads are not enabled then the strategy simply works on the read -threads. Invalid values are ignored. - -* `pin-threads=R1L`: All read threads pinned to a single logical CPU. -* `pin-threads=R1P`: All read threads pinned to a single physical CPU. -* `pin-threads=RP1L`: All read and process threads pinned to a single logical CPU. -RP1P: All read and process threads pinned to a single physical CPU. -R1LP1L: All read threads pinned to a single logical CPU, all process threads pinned to a (if possible) different logical CPU. -R1PP1P: All read threads pinned to a single physical CPU, all process threads pinned to a (if possible) different logical CPU. -RPSL: All read and process threads are spread across all logical CPUs. -RPSP: All read and process threads are spread across all physical CPUs. -R1PPSP: All read threads are pinned to a single physical CPU while process threads are spread across all other physical CPUs. diff --git a/config/pin-threads/index.html b/config/pin-threads/index.html index d1431663..15021e5a 100644 --- a/config/pin-threads/index.html +++ b/config/pin-threads/index.html @@ -900,27 +900,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup diff --git a/config/readahead.md~ b/config/readahead.md~ new file mode 100644 index 00000000..e800ce21 --- /dev/null +++ b/config/readahead.md~ @@ -0,0 +1,2 @@ +# readahead + diff --git a/config/readahead/index.html b/config/readahead/index.html index 38ef7915..e79e3c18 100644 --- a/config/readahead/index.html +++ b/config/readahead/index.html @@ -900,27 +900,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1484,6 +1463,37 @@

    readahead

    +

    Sets the mergerfs and underlying filesystem readahead values. The +value unit is in kibibytes.

    +
      +
    • readahead=1024
      • +
    +

    While the max size of messages sent between the kernel and mergerfs is +configurable via the fuse_msg_size option that +doesn't mean that is the size used by the kernel for read and +writes.

    +

    Linux has a max read/write size of 2GB. Since the max FUSE message +size is just over 1MB the kernel will break up read and write requests +with buffers larger than that 1MB.

    +

    When page caching is disabled (cache.files=off), besides the kernel +breaking up requests with larger buffers, requests are effectively one +for one to mergerfs. A read or write request for X bytes is made to +the kernel and a request for X bytes is made to mergerfs. No +readahead behavior will +occur because there is no page cache available for it to store that +data. In FUSE this is referred to as "direct IO". Note that "direct +IO" is not the same as O_DIRECT.

    +

    When page caching is enabled the kernel can and will utilize +readahead. However, there are two values which impact the size of +the readahead requests. The filesystem's readahead value and the +FUSE max_readahead value. Whichever is lowest is used. The default +max_readahead in mergerfs is maxed out meaning only the filesystem +readahead value is relevant.

    +

    Preferably this value would be set by the user externally since it is +a generic feature but there is no standard way to do so mergerfs added +this feature to make it easier to set.

    +

    There is currently no way to set separate values for different +branches through mergerfs.

    diff --git a/config/rename-exdev.md~ b/config/rename-exdev.md~ deleted file mode 100644 index 1a342d54..00000000 --- a/config/rename-exdev.md~ +++ /dev/null @@ -1,19 +0,0 @@ -# rename-exdev - -If using path preservation and a `rename` fails with `EXDEV`: - -1. Move file from **/branch/a/b/c** to **/branch/.mergerfs_rename_exdev/a/b/c**. -2. symlink the rename's `newpath` to the moved file. - -The `target` value is determined by the value of `rename-exdev`. - -- passthrough: Return EXDEV as normal. -- rel-symlink: A relative path from the `newpath`. -- abs-symlink: An absolute value using the mergerfs mount point. - -NOTE: It is possible that some applications check the file they -rename. In those cases it is possible it will error or complain. - -NOTE: The reason `abs-symlink` is not split into two like `link-exdev` -is due to the complexities in managing absolute base symlinks when -multiple `oldpaths` exist. diff --git a/config/rename-exdev/index.html b/config/rename-exdev/index.html index 07d78b42..23baffe6 100644 --- a/config/rename-exdev/index.html +++ b/config/rename-exdev/index.html @@ -900,27 +900,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1495,6 +1474,7 @@
  • rename-exdev=rel-symlink: A relative path from the newpath.
  • rename-exdev=abs-symlink: An absolute value using the mergerfs mount point.
    • +
  • Defaults to passthrough.

    • NOTE: It is possible that some applications check the file they rename. In those cases it is possible it will error or complain.

    diff --git a/config/rename_and_link/index.html b/config/rename_and_link/index.html index 25da0f1d..e6791a52 100644 --- a/config/rename_and_link/index.html +++ b/config/rename_and_link/index.html @@ -900,27 +900,6 @@ -
  • - - - - - ioctl - - - - -
    • - - - - - - - - - -
  • @@ -1337,7 +1316,7 @@ - Limit drive spinup + Limiting drive spinup diff --git a/config/statfs/index.html b/config/statfs/index.html index 06cba194..7a106557 100644 --- a/config/statfs/index.html +++ b/config/statfs/index.html @@ -13,7 +13,7 @@ - + @@ -888,27 +888,6 @@ - - -
  • - - - - - ioctl - - - - -
    • - - - - - - - - @@ -921,6 +900,17 @@ + + @@ -931,6 +921,34 @@ + + + + @@ -1337,7 +1355,7 @@ - Limit drive spinup + Limiting drive spinup @@ -1454,6 +1472,23 @@ + + +
    @@ -1484,6 +1519,12 @@

    statfs / statvfs

    +

    statvfs normalizes the source filesystems based on the fragment size and sums the number of adjusted blocks and inodes. This means you will see the combined space of all @@ -1491,8 +1532,17 @@ sources. Total, used, and free. The sources however are dedupped based on the filesystem so multiple sources on the same drive will not result in double counting its space. Other filesystems mounted further down the tree of the branch will not be included when checking the mount's stats.

    -

    The options statfs and statfs_ignore can be used to modify -statfs behavior.

    +

    statfs_ignore

    +

    Modifies how statfs works. Will cause it to ignore branches of a +certain mode.

    + @@ -1528,7 +1578,7 @@ of the branch will not be included when checking the mount's stats.