tmpoverlay

tmpoverlay is a small, almost-POSIX shell script to create tmpfs-backed overlayfs mounts.

Features

• minimal requirements (sh, mount, getopt)
• single shell script, no compilation required
• small (7 KB, 2 KB after gzip -9)

Benefits over manually calling mkdir /tmp/x; mount ...

• separate tmpfs allows size limit (tmpoverlay -t size=SIZE)
• upperdir and workdir automatically managed
• tmpfs cleanup after mount so that umount frees RAM
• synchronizes owner, permissions, and xattrs (including ACLs)
• autodetects optimization flags (redirect_dir, metacopy, index, volatile)

Overmounting

Like any other Linux mount, an overlayfs mount only affects new directory lookups. If a process has its current directory or has files open inside the mount point, it continues to access the original directory, not the overlaid one. Each process also has a cached root directory pointer, which can only be modified by chroot (internally) or pivot_root (globally). The pivot_root(2)_ and pivot_root(8)_ man pages should be fully read and understood before using tmpoverlay to overmount /. It is also highly recommended to read busybox switch_root comment.

Changes to underlying filesystems

Per the kernel overlayfs documentation, changing underlying filesystems while the overlay is mounted is not supported:

Changes to the underlying filesystems while part of a mounted overlay filesystem are not allowed. If the underlying filesystem is changed, the behavior of the overlay is undefined, though it will not result in a crash or deadlock.

Unprivileged operation using user namespaces

Since Linux 5.11, overlayfs can be mounted in unprivileged user namespaces. This means that it is possible to temporarily place an overlay in a local context. For example, unshare -Umc --keep-caps sh -c 'tmpoverlay . && exec setpriv --inh-caps=-all $SHELL' has a similar effect to tmpoverlay ., but does not require privileges. In exchange, it only takes effect within the newly started shell, similar to environment variables.

Note that tmpfs overlay doesn't work properly with unmapped UIDs. In other words, after running tmpoverlay, only files owned by the current user can be modified; modifying other files will have unpredictable results.

This issue can be mitigated starting with Linux 5.12 using idmap, but this is not integrated in tmpoverlay due to a lack of standard utilities.

Pseudo-filesystems

Pseudo-filesystems like procfs and sysfs are not intended to be used with overlayfs. Therefore, running commands like tmpoverlay /proc may have unexpected results.

POSIX compliance

With the following exceptions, tmpoverlay is intended to be functional on POSIX-only shells:

• mount -t overlay is obviously required
• getopt -- is required for proper handling of options containing spaces
• getfattr is used for xattr copying but in case of failure, the system is assumed to not support xattrs and setfattr is skipped.
• realpath is required for canonicalizing paths if -c is not provided