6.7 KiB
Runtime Interface
mergerfs has runtime interfaces allowing users to query certain
filesystem information, get and set config, and trigger certain
activities while it is running.
The interface is provided via the POSIX extended attributes filesystem
API which is a namespaced key=value pair store associated with a
file. Since mergerfs primarily uses key=value pairs for config it
fits well and is a known and reasonably well supported API.
There are two targets for xattr calls. One is a pseudo file used for
getting and setting config and issuing certain commands. The other are
files found on the filesystem for querying certain mergerfs specific
information about them.
.mergerfs pseudo file
<mountpoint>/.mergerfs
mergerfs provides this pseudo file for the runtime modification of
certain options and issuing commands. The file will not show up in
readdir but can be stat'ed and viewed/manipulated via
listxattr,
getxattr, and
setxattr calls.
Any changes made at runtime are NOT persisted. If you wish for values to persist they must be included as options wherever you configure the mounting of mergerfs (/etc/fstab, systemd, etc.).
Command Line Tooling
Extended attributes is prevelant enough that there are common tools available for interacting with them.
In Debian / Ubuntu distributions you can get the tools getfattr and setfattr from attr package.
$ sudo apt-get install attr
Config
Keys
Use getfattr -d /mountpoint/.mergerfs to see all supported
configuration keys. It is effectively the same as the
options prefixed with user.mergerfs.. Some are
informational or only can be set at startup and therefore read-only.
Example: option cache.files would be user.mergerfs.cache.files.
Values
Same as the command line options.
Getting
getfattr -n user.mergerfs.branches /mountpoint/.mergerfs
ENOATTR will be returned if the key doesn't exist as normal with
getxattr.
Setting
setfattr -n user.mergerfs.branches -v VALUE /mountpoint/.mergerfs
setxattr will return EROFS
(Read-only filesystem) on read-only keys. ENOATTR will be returned
if the key does not exist. If the value attempting to be set is not
valid EINVAL will be returned.
user.mergerfs.branches
branches has the ability to understand some simple instructions to
make manipulation of the list easier. The [list] is simply what is
described in the branches docs.
| Value | Description |
|---|---|
| [list] | set |
| +<[list] | prepend to existing list |
| +>[list] | append to existing list |
| -[list] | remove all values provided |
| -< | remove first in list |
| -> | remove last in list |
NOTE: if the value of branches is set to something invalid /
non-existant mergerfs will return a bogus entry when the mount point
directory is stat'ed and create a fake file entry when listing the
directory telling the user "error: no valid mergerfs branch found,
check config". This is done to ensure the user understands the
situation and continue to be able to access the xattr interface.
Example
[trapexit:/mnt/mergerfs] $ getfattr -d .mergerfs
user.mergerfs.branches="/mnt/a=RW:/mnt/b=RW"
user.mergerfs.minfreespace="4294967295"
user.mergerfs.moveonenospc="false"
...
[trapexit:/mnt/mergerfs] $ getfattr -n user.mergerfs.category.create .mergerfs
user.mergerfs.category.search="mfs"
[trapexit:/mnt/mergerfs] $ setfattr -n user.mergerfs.category.create -v pfrd .mergerfs
[trapexit:/mnt/mergerfs] $ getfattr -n user.mergerfs.category.create .mergerfs
user.mergerfs.category.search="prfd"
[trapexit:/mnt/mergerfs] $ setfattr -n user.mergerfs.branches -v "'+</mnt/c=RO .mergerfs
[trapexit:/mnt/mergerfs] $ getfattr -n user.mergerfs.branches .mergerfs
user.mergerfs.branches="/mnt/c=RO:/mnt/a=RW:/mnt/b=RW"
Commands
There are a number of commands / behaviors which can be triggerd by
writing (setfattr,
setxattr) particular xattr
keys of /mountpoint/.mergerfs. These keys do not show up in key
listings.
Commands can take an argument however currently no command uses or allows a value.
| Key | Value | Description |
|---|---|---|
| user.mergerfs.cmd.gc | (empty) | Trigger a thorough garbage collection of certain pools of resources. The xattr value is not used. |
| user.mergerfs.cmd.gc1 | (empty) | Trigger a simple garbage collection of certain pools of resources. This is also done on a timer. |
| user.mergerfs.cmd.invalidate-all-nodes | (empty) | Attempts to invalidate FUSE file nodes. Primarily used for debugging. |
| user.mergerfs.cmd.invalidate-gid-cache | (empty) | Invalidates all entries in gid cache. Primarily used for debugging but can also be useful in cases where gid supplemental groups change. |
| user.mergerfs.cmd.clear-gid-cache | (empty) | Clears all entries in the gid cache. Primarily used for debugging but can also be useful in cases where gid supplemental groups change. |
[trapexit:/mnt/mergerfs] $ setfattr -n user.mergerfs.cmd.gc /mnt/mergerfs/.mergerfs
[trapexit:/mnt/mergerfs] $ journalctl -t mergerfs | tail -n1
Jul 20 15:36:18 hostname mergerfs[1931348]: running basic garbage collection
file / directory xattrs
There is certain information mergerfs knows or calculates about a
file that can be useful in building tooling or debugging.
The keys below can be queried (getfattr -n key,
getxattr) to get the described
information. These keys will not show up in any listing (getfattr -d, listxattr). Attempting
to set them will result in an error.
| Key | Return Value |
|---|---|
| user.mergerfs.basepath | The base mount point for the file given the current getattr policy. |
| user.mergerfs.relpath | The relative path of the file from the perspective of the mount point. |
| user.mergerfs.fullpath | The full path of the original file given the getattr policy. |
| user.mergerfs.allpaths | A NULL ('\0') separated list of full paths to all files found. |
[trapexit:/mnt/mergerfs] $ getfattr -n user.mergerfs.fullpath test
user.mergerfs.fullpath="/mnt/a/test"
[trapexit:/mnt/mergerfs] $ getfattr -n user.mergerfs.allpaths .
user.mergerfs.allpaths="/mnt/a\000/mnt/b\000/mnt/c"