How does fuse-overlayfs run inside a container without --privileged or CAP_SYS_ADMIN?
The short answer: user namespaces + a single kernel flag added in Linux 4.18.
But this is not documented anywhere clearly — that's the point of this page.
We checked every relevant man page:
| Man page | What it covers | Mentions user ns + FUSE mount? |
|---|---|---|
man 2 mount |
needs CAP_SYS_ADMIN |
No |
man 4 fuse |
wire protocol only (messages over /dev/fuse) | No |
man 7 user_namespaces |
lists allowed mounts (tmpfs, proc, overlayfs) | No FUSE |
man 8 mount.fuse3 |
needs root or CAP_SYS_ADMIN |
No |
| fuse-overlayfs README | "requires kernel > 4.18" | No explanation why |
Nowhere does any doc say: "FUSE can be mounted inside a user namespace without CAP_SYS_ADMIN since Linux 4.18"
Commit 4ad769f3c346ec3d458e255548dec26ca5284cf6 by Eric W. Biederman (May 31, 2018):
"fuse: Allow fully unprivileged mounts"
The entire change in fs/fuse/inode.c:
// before (Linux < 4.18)
.fs_flags = FS_HAS_SUBTYPE,
// after (Linux >= 4.18)
.fs_flags = FS_HAS_SUBTYPE | FS_USERNS_MOUNT,
One flag. That's it.
The kernel checks this flag in mount_capable() inside fs/super.c:
bool mount_capable(struct fs_context *fc)
{
if (!(fc->fs_type->fs_flags & FS_USERNS_MOUNT))
return capable(CAP_SYS_ADMIN); // needs REAL root (host)
else
return ns_capable(fc->user_ns, CAP_SYS_ADMIN); // root inside user ns is enough
}