fuse-overlayfs(1)

🦋 fuse-overlayfs(1) 🦋

ok bestie, welcome to the General Commands Manual page for fuse-overlayfs — the little tool that stacks whole directory trees on top of each other like it's a fit check. Sit down, hydrate, and let's get into it 💅

---

✨ NAME ✨

fuse-overlayfs — combine directory trees in userspace

---

🎀 SYNOPSIS 🎀

mounting

fuse-overlayfs [-f] [-d] [-o OPTION[,OPTION2, ...]] mountpoint

unmounting

fusermount -u mountpoint

---

🌸 DESCRIPTION 🌸

So, what does it actually do? fuse-overlayfs combines (overlays) two or more directory trees into one. Iconic behaviour, no notes. 🫶

The big deal is that it can be used by unprivileged users inside a user namespace — no root era required, we love that for you. It's built with FUSE and works with Linux 4.18 or newer, so if your kernel is ancient, that's a you problem, not a me problem 😭

---

💅 OPTIONS 💅

• -f — Run in foreground. It stays put, in your face, main character energy. 👑
• -d, --debug, -o debug — Enable debugging mode. Fair warning: it can be very noisy 💀 it will simply not stop talking.
• -o lowerdir=low1[:low2...] — A list of directories separated by :. Their content is merged. Stack them like pancakes 🥞
• -o upperdir=upperdir — A directory merged on top of all the lowerdirs, where all the changes done to the file system will be written. This is where the drama gets recorded. ✍️
• -o workdir=workdir — A directory used internally by fuse-overlays, and ngl it must be on the same file system as the upperdir. No exceptions, no negotiating. 🚫
• -o uidmapping=UID:MAPPED-UID:LEN[,UID2:MAPPED-UID2:LEN2]
• -o gidmapping=GID:MAPPED-GID:LEN[,GID2:MAPPED-GID2:LEN2] — Specify the dynamic UID/GID mapping used by fuse-overlayfs when reading/writing files to the system.
• -o squash_to_root — Make every file and directory owned by the root user (0:0). Everything is root now. Collective ownership era. 🌈
• -o squash_to_uid=uid
• -o squash_to_gid=gid — Make every file and directory owned by the specified uid or gid. Heads up: this has higher precedence over squash_to_root, so if you set both, this one wins the argument. 🥇
• -o static_nlink — Set st_nlink to the static value 1 for all directories. This can be useful for higher latency file systems such as NFS, where counting the number of hard links for a directory with many files can be a slow operation. With this option enabled, the number of hard links reported when running stat for any directory is 1. Basically: skip the counting, we don't have time. ⏱️
• -o noacl — Disable ACL support in the FUSE file system.
• -o xino=off|auto|on — Controls how st_ino values are generated for files returned by fuse-overlayfs. When all lower and upper layers reside on the same underlying device, fuse-overlayfs exposes the real inode number from the underlying filesystem. When layers span multiple devices, an opaque inode number is generated; by default this value is not stable across mounts. 😵‍💫

The xino option modifies this behavior:

• xino=off — Disables extended inode generation. This matches the default behavior: when all layers are on the same device, the underlying inode number is used; otherwise an opaque, non-stable inode number is returned.
• xino=auto — Attempts to generate stable inode numbers across mounts by hashing the file handle returned by name_to_handle_at(2). This mode is used only if all layers support name_to_handle_at(2); if any layer does not, behavior falls back to xino=off. If all layers are on the same device, the underlying inode number is still used, regardless of this setting. She tries her best, but she also knows when to give up. 🧚
• xino=on — Requires that all layers support name_to_handle_at(2). If they do, inode numbers are derived from a hash of the file handle and remain stable across mounts. If any layer does not support name_to_handle_at(2), the mount fails. As with other modes, when all layers are on the same device, the underlying inode number always takes precedence. All or nothing, periodt. 💥

• -o ino32_t — Forces all returned st_ino values to be truncated to 32 bits. This option exists solely for compatibility with older 32-bit userspaces that cannot correctly handle 64-bit inode numbers. It has no functional benefit on modern systems and should not be used unless required for legacy compatibility. Like, it's giving legacy-support-only, bestie. 🙈
• -h, --help — Show additional options, provided by FUSE.
• -V, --version — Show versions of fuse-overlayfs and FUSE.

---

🧚 DYNAMIC UID AND GID MAPPING 🧚

The fuse-overlayfs dynamic mapping is an alternative and cheaper way to chown'ing the files on the host to accommodate the user namespace settings. Cheaper = better, obviously. ✨

It is useful to share the same storage among different user namespaces and counter effect the mapping done by the user namespace itself, and without requiring to chown the files. No messy permission makeovers required. 💖

Take, for example, two files with the following user and group IDs:

$ stat -c %u:%g lower/a lower/b
0:0
1:1

Also take note of the following user namespace configuration:

$ cat /proc/self/uid_map
         0       1000          1
         1     110000      65536

After mounting with fuse-overlayfs, the ownership would change:

$ stat -c %u:%g merged/a merged/b
65534:65534
65534:65534

65534 is the overflow ID used when the UID/GID is not known inside the user namespace. This happens because neither user IDs 0 nor 1 are mapped. So they just... don't exist in there. Gone. Unknown. mystery IDs. 👻

To map them, we'd mount the fuse-overlayfs file system using the following namespace configuration:

-o uidmapping=0:1000:1:1:110000:65536,gidmapping=0:1000:1:1:110000:65536

The result would then be the following:

$ stat -c %u:%g merged/a merged/b
0:0
1:1

Those are the same IDs visible from outside the user namespace. Slay, mapping worked, we ate. 🍓

---

👑 SEE ALSO 👑

fuse(8), mount(8), user_namespaces(7)

---

🌈 AVAILABILITY 🌈

The fuse-overlayfs command is available from https://github.com/containers/fuse-overlayfs under GNU GENERAL PUBLIC LICENSE Version 3 or later.

---

And that's the whole page, bestie 🫶 this was the User Commands section of the fuse-overlayfs(1) manual — go forth, mount responsibly, and remember: no cap, everything you just read is the actual spec. 💜