From 8990e24c0f1d9a1eec7ff7898fb897680acaa0a5 Mon Sep 17 00:00:00 2001 From: Antonio SJ Musumeci Date: Tue, 29 Sep 2020 18:50:25 -0400 Subject: [PATCH] README.md: add details on per branch minfreespace --- README.md | 24 ++++++++++++++++++++---- man/mergerfs.1 | 43 ++++++++++++++++++++++++++++--------------- 2 files changed, 48 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index e23c2f79..09535349 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ See the mergerfs [wiki for real world deployments](https://github.com/trapexit/m * **config**: Path to a config file. Same arguments as below in key=val format. * **branches**: Colon delimited list of branches. * **allow_other**: A libfuse option which allows users besides the one which ran mergerfs to see the filesystem. This is required for most use-cases. -* **minfreespace=SIZE**: The minimum space value used for creation policies. Understands 'K', 'M', and 'G' to represent kilobyte, megabyte, and gigabyte respectively. (default: 4G) +* **minfreespace=SIZE**: The minimum space value used for creation policies. Can be overridden by branch specific option. Understands 'K', 'M', and 'G' to represent kilobyte, megabyte, and gigabyte respectively. (default: 4G) * **moveonenospc=BOOL|POLICY**: When enabled if a **write** fails with **ENOSPC** (no space left on device) or **EDQUOT** (disk quota exceeded) the policy selected will run to find a new location for the file. An attempt to move the file to that branch will occur (keeping all metadata possible) and if successful the original is unlinked and the write retried. (default: false, true = mfs) * **use_ino**: Causes mergerfs to supply file/directory inodes rather than libfuse. While not a default it is recommended it be enabled so that linked files share the same inode value. * **inodecalc=passthrough|path-hash|devino-hash|hybrid-hash**: Selects the inode calculation algorithm. (default: hybrid-hash) @@ -149,11 +149,27 @@ See the mergerfs [wiki for real world deployments](https://github.com/trapexit/m ### branches -The 'branches' (formerly 'srcmounts') argument is a colon (':') delimited list of paths to be pooled together. It does not matter if the paths are on the same or different drives nor does it matter the filesystem. Used and available space will not be duplicated for paths on the same device and any features which aren't supported by the underlying filesystem (such as file attributes or extended attributes) will return the appropriate errors. +The 'branches' (formerly 'srcmounts') argument is a colon (':') delimited list of paths to be pooled together. It does not matter if the paths are on the same or different drives nor does it matter the filesystem (within reason). Used and available space will not be duplicated for paths on the same device and any features which aren't supported by the underlying filesystem (such as file attributes or extended attributes) will return the appropriate errors. + +Branches currently have two options which can be set. A type which impacts whether or not the branch is included in a policy calculation and a individual minfreespace value. The values are set by prepending an `=` at the end of a branch designation and using commas as delimiters. Example: /mnt/drive=RW,1234 + + +#### branch type + +* RW: (read/write) - Default behavior. Will be eligible in all policy categories. +* RO: (read-only) - Will be excluded from `create` and `action` policies. Same as a read-only mounted filesystem would be (though faster to process). +* NC: (no-create) - Will be excluded from `create` policies. You can't create on that branch but you can change or delete. + + +#### minfreespace + +Same purpose as the global option but specific to the branch. If not set the global value is used. + + +#### globbing To make it easier to include multiple branches mergerfs supports [globbing](http://linux.die.net/man/7/glob). **The globbing tokens MUST be escaped when using via the shell else the shell itself will apply the glob itself.** -Each branch can have a suffix of `=RW` (read / write), `=RO` (read-only), or `=NC` (no create). These suffixes work with globs as well and will apply to each path found. `RW` is the default behavior and those paths will be eligible for all policy categories. `RO` will exclude those paths from `create` and `action` policies (just as a filesystem being mounted `ro` would). `NC` will exclude those paths from `create` policies (you can't create but you can change / delete). ``` # mergerfs -o allow_other,use_ino /mnt/disk\*:/mnt/cdrom /media/drives @@ -168,7 +184,7 @@ To have the pool mounted at boot or otherwise accessible from related tools use /mnt/disk*:/mnt/cdrom /mnt/pool fuse.mergerfs allow_other,use_ino 0 0 ``` -**NOTE:** the globbing is done at mount or xattr update time (see below). If a new directory is added matching the glob after the fact it will not be automatically included. +**NOTE:** the globbing is done at mount or when updated using the runtime API. If a new directory is added matching the glob after the fact it will not be automatically included. **NOTE:** for mounting via **fstab** to work you must have **mount.fuse** installed. For Ubuntu/Debian it is included in the **fuse** package. diff --git a/man/mergerfs.1 b/man/mergerfs.1 index 124ac8d8..62682465 100644 --- a/man/mergerfs.1 +++ b/man/mergerfs.1 @@ -127,6 +127,7 @@ This is required for most use\-cases. .IP \[bu] 2 \f[B]minfreespace=SIZE\f[]: The minimum space value used for creation policies. +Can be overridden by branch specific option. Understands \[aq]K\[aq], \[aq]M\[aq], and \[aq]G\[aq] to represent kilobyte, megabyte, and gigabyte respectively. (default: 4G) @@ -331,28 +332,40 @@ POLICY = mergerfs function policy The \[aq]branches\[aq] (formerly \[aq]srcmounts\[aq]) argument is a colon (\[aq]:\[aq]) delimited list of paths to be pooled together. It does not matter if the paths are on the same or different drives nor -does it matter the filesystem. +does it matter the filesystem (within reason). Used and available space will not be duplicated for paths on the same device and any features which aren\[aq]t supported by the underlying filesystem (such as file attributes or extended attributes) will return the appropriate errors. .PP +Branches currently have two options which can be set. +A type which impacts whether or not the branch is included in a policy +calculation and a individual minfreespace value. +The values are set by prepending an \f[C]=\f[] at the end of a branch +designation and using commas as delimiters. +Example: /mnt/drive=RW,1234 +.SS branch type +.IP \[bu] 2 +RW: (read/write) \- Default behavior. +Will be eligible in all policy categories. +.IP \[bu] 2 +RO: (read\-only) \- Will be excluded from \f[C]create\f[] and +\f[C]action\f[] policies. +Same as a read\-only mounted filesystem would be (though faster to +process). +.IP \[bu] 2 +NC: (no\-create) \- Will be excluded from \f[C]create\f[] policies. +You can\[aq]t create on that branch but you can change or delete. +.SS minfreespace +.PP +Same purpose as the global option but specific to the branch. +If not set the global value is used. +.SS globbing +.PP To make it easier to include multiple branches mergerfs supports globbing (http://linux.die.net/man/7/glob). \f[B]The globbing tokens MUST be escaped when using via the shell else the shell itself will apply the glob itself.\f[] -.PP -Each branch can have a suffix of \f[C]=RW\f[] (read / write), -\f[C]=RO\f[] (read\-only), or \f[C]=NC\f[] (no create). -These suffixes work with globs as well and will apply to each path -found. -\f[C]RW\f[] is the default behavior and those paths will be eligible for -all policy categories. -\f[C]RO\f[] will exclude those paths from \f[C]create\f[] and -\f[C]action\f[] policies (just as a filesystem being mounted \f[C]ro\f[] -would). -\f[C]NC\f[] will exclude those paths from \f[C]create\f[] policies (you -can\[aq]t create but you can change / delete). .IP .nf \f[C] @@ -373,8 +386,8 @@ tools use \f[B]/etc/fstab\f[]. \f[] .fi .PP -\f[B]NOTE:\f[] the globbing is done at mount or xattr update time (see -below). +\f[B]NOTE:\f[] the globbing is done at mount or when updated using the +runtime API. If a new directory is added matching the glob after the fact it will not be automatically included. .PP