Repository files navigation

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

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

Benefits over manually callingmkdir /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)

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

Perthe kernel overlayfs documentation, changing underlying filesystemswhile the overlay is mounted is not supported:

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

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 localcontext. For example,unshare -Umc --keep-caps sh -c 'tmpoverlay . && execsetpriv --inh-caps=-all $SHELL' has a similar effect totmpoverlay ., butdoes not require privileges. In exchange, it only takes effect within the newlystarted shell, similar to environment variables.

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

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

Pseudo-filesystems like procfs and sysfs are not intended to be used withoverlayfs. Therefore, running commands liketmpoverlay /proc may haveunexpected results.

With the following exceptions, tmpoverlay is intended to be functional onPOSIX-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 isassumed to not support xattrs and setfattr is skipped.
• realpath is required for canonicalizing paths if -c is not provided