From 6e02a1f674fb0b5861d7b18c3cdf70478bbb530a Mon Sep 17 00:00:00 2001 From: Antonio SJ Musumeci Date: Sun, 30 Nov 2025 22:30:55 -0600 Subject: [PATCH] technical_behavior_and_limitations.md --- .../faq/technical_behavior_and_limitations.md | 41 +++++++++---------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/mkdocs/docs/faq/technical_behavior_and_limitations.md b/mkdocs/docs/faq/technical_behavior_and_limitations.md index 49df8fba..2fc9ba98 100644 --- a/mkdocs/docs/faq/technical_behavior_and_limitations.md +++ b/mkdocs/docs/faq/technical_behavior_and_limitations.md @@ -253,28 +253,27 @@ decided that the credential handling would change. As of v2.42.0 mergerfs now runs effectively as root when performing more filesystem calls. On Linux it uses `capabilities` which allow any uid:gid it changes to to act as if it were root. This minimizes the -amount of credential changing. When creating new files, directories, +amount of credential changing slightly lowering the overhead compared +to the previous strategy. When creating new files, directories, symlinks, etc. it will change the thread's creds to the requester -uid:gid to ensure the file is created as the user atomically. - -On FreeBSD the situation is more complicated. As required by standards -most Unix/POSIX based systems a process and all its threads are under -the same uid and gid. However, on Linux each thread **may** have its -own credentials. This allows mergerfs to be multithreaded and for each -thread to change to the credentials as required by the incoming -message it is handling. However, currently on FreeBSD this is not -possible (though there has been -[discussions](https://wiki.freebsd.org/Per-Thread%20Credentials)) and -as such must change the credentials of the whole application when -actioning messages. mergerfs does optimize this behavior by only -changing credentials and locking the thread to do so if the process is -currently not the same as what is necessary by the incoming -request. As a result of this design FreeBSD may experience more -contention and therefore lower performance than Linux. - -Additionally, mergerfs [utilizes a cache for supplemental -groups](../known_issues_bugs.md#supplemental-user-groups) due the the -high cost of querying that information. +uid:gid to ensure the file is created as the user atomically. The per +thread part is possible because unlike most other Unix/POSIX systems +Linux allows individual threads to control their credentials rather +than it being process wide. This strategy is also used by Samba. + +On FreeBSD the situation is more complicated. Since FreeBSD does not +currently support per thread credentials (though there has been +[discussions](https://wiki.freebsd.org/Per-Thread%20Credentials)) +mergerfs runs as root and, for the time being, has to create files as +root and then lchown them. This is not ideal as there is a brief +moment where the uid:gid values are wrong and a process watching file +creation could notice. However, this should not be a problem in +practice. The alternative to this strategy is to create a setup where +a filesystem proxy of sorts is spawned for each uid:gid combination +needed and the main mergerfs process makes requests to those proxies +to do the work needed. The problem is that that kind of setup is both +more complex and slower. + ## Does mergerfs support idmap?