Skip to content

Raspberry Pi OverlayFS: Read-Only Root and Kiosk Guide

Raspberry Pi OS can protect its root filesystem with OverlayFS so runtime changes go to a temporary RAM-backed upper layer and disappear after reboot. This is useful for kiosks, classroom devices, digital signs, and appliances that must return to a known state. It is not appropriate until every required persistent file has a deliberate home.

Quick answer

  1. Update and back up the working system.
  2. List databases, logs, keys, uploads, and state that must persist.
  3. Move that data to a separate writable filesystem where necessary.
  4. Open sudo raspi-config.
  5. Choose Performance Options → Overlay File System.
  6. Enable the root overlay; decide separately whether to protect the boot partition.
  7. Reboot and prove that disposable changes vanish while required data remains.
  8. Document how to disable the overlay before future OS updates.

The official Raspberry Pi configuration documentation describes the supported menu and desktop controls. Raspberry Pi also publishes an application note on making a more resilient filesystem.

How OverlayFS works

Layer Purpose Survives reboot in the Raspberry Pi OS read-only-root mode?
Lower Original root filesystem Yes, but remains unchanged while overlay is active
Upper New and modified files No; stored in RAM for the supported temporary overlay
Work Internal OverlayFS operations No
Merged Combined view applications use as / Presents both layers

When a program first changes a file from the lower layer, OverlayFS copies it to the upper layer and modifies that copy. Deleting a lower-layer file creates a whiteout in the upper layer. The lower file remains intact and becomes visible again after the temporary upper layer is discarded.

This differs from a Device Tree overlay. Both use the word “overlay,” but a Device Tree overlay describes hardware; OverlayFS combines filesystem layers.

Decide whether OverlayFS fits

Good candidates

  • kiosk or digital-signage image restored by reboot
  • supervised classroom or exhibition device
  • disposable integration-test system
  • appliance configured through a separate persistent data partition
  • system exposed to unexpected power removal after its data path is designed accordingly

Poor candidates without redesign

  • database or home server writing state throughout /var/lib
  • system that receives unattended upgrades while overlay is active
  • remote-only device with no tested recovery route
  • desktop expected to retain accounts, browser profiles, and package changes
  • recorder, camera, or sensor logger without separate persistent storage

OverlayFS reduces writes to the lower root while active. It does not replace clean shutdown, reliable power, backups, or suitable storage.

Inventory persistent data

Run the real workload for an hour, then inspect recently modified files:

1
2
sudo find /etc /home /var -xdev -type f -mmin -60 \
  -printf '%TY-%Tm-%Td %TH:%TM:%TS %s %p\n' | sort

Check common state directories:

1
2
3
sudo du -xhd1 /var/lib /var/log /home 2>/dev/null | sort -h
systemctl --failed
findmnt -o TARGET,SOURCE,FSTYPE,OPTIONS

Classify every write:

Data Usually persistent? Example strategy
Application database Yes Separate writable filesystem and backup
SSH host keys Yes Preserve /etc/ssh state in the base image
VPN identity/state Yes Persistent application-specific directory
Uploads and recordings Yes Dedicated data filesystem
Package changes Yes Disable overlay during maintenance
Temporary cache No Leave in upper layer or bounded tmpfs
Debug logs Depends Remote logging or bounded persistent location

Do not bind-mount broad directories such as all of /etc or /var without understanding what becomes writable and how it is backed up.

Prepare a rollback

Before activation:

1
2
3
4
sudo apt update
sudo apt full-upgrade
systemctl --failed
vcgencmd get_throttled

Create a restorable image or file-level backup, and keep another bootable storage device. Record:

  • Raspberry Pi model and OS release
  • root and boot device names
  • enabled services
  • persistent mount definitions
  • the exact procedure to disable OverlayFS
  • how to attach a keyboard/display or mount bootfs elsewhere

Test the backup restoration before deployment. A backup that has never been restored is only an assumption.

Enable the supported read-only root

Open the configuration menu:

1
sudo raspi-config

Choose Performance Options → Overlay File System. The tool asks two distinct questions:

  1. Enable the overlay for the root filesystem.
  2. Write-protect the boot partition.

Enable only the root overlay for the first test. Keeping the boot partition writable initially simplifies recovery; protect it later only if the threat model requires it and the maintenance process works.

Reboot when prompted:

1
sudo reboot

Verify that it works

Inspect mounts after reconnecting:

1
2
3
findmnt /
findmnt -t overlay
mount | grep -E ' on / |type overlay'

Create a disposable marker:

1
2
3
4
printf 'overlay test %s\n' "$(date --iso-8601=seconds)" \
  | sudo tee /etc/overlay-test.txt
cat /etc/overlay-test.txt
sudo reboot

After reboot, the marker should be absent:

1
test ! -e /etc/overlay-test.txt && echo 'temporary root change discarded'

Now verify the data that must persist. Create a marker in the dedicated writable location, restart the application, reboot, and confirm its database, uploads, identity, and configuration remain valid.

Measure RAM and upper-layer growth

The temporary upper layer consumes memory as files change. Monitor the system during the longest expected workload:

1
2
3
4
free -h
df -hT
findmnt -t overlay
watch -n 2 'free -h; df -h /'

Also check memory pressure and OOM history:

1
2
cat /proc/pressure/memory
journalctl -k -b --no-pager | grep -Ei 'out of memory|oom-kill|killed process'

If the upper layer grows without bound, identify the writer with iotop and application logs. Do not solve it by assigning all RAM to the overlay; fix or relocate the write source.

Use the memory pressure and OOM guide for a repeatable load test.

Maintenance and OS updates

Changes made while the root overlay is active disappear after reboot, including package installations and configuration edits. Use this maintenance sequence:

  1. Schedule downtime and confirm recent backups.
  2. Disable OverlayFS using the same raspi-config menu.
  3. Reboot and verify that / is writable without the temporary overlay.
  4. Apply updates and required configuration.
  5. Reboot once and test the application with OverlayFS still disabled.
  6. Re-enable OverlayFS.
  7. Reboot again and run persistence and reset tests.

Example update checks while the overlay is disabled:

1
2
3
4
5
findmnt /
sudo apt update
sudo apt full-upgrade
systemctl --failed
journalctl -b -p warning --no-pager

Do not automate updates during the overlay-enabled state and assume they were committed to the lower filesystem.

Disable OverlayFS

Open:

1
sudo raspi-config

Return to Performance Options → Overlay File System, disable the root overlay, and remove boot write protection if maintenance requires it. Reboot and verify:

1
2
findmnt /
sudo sh -c 'touch /etc/write-test && rm /etc/write-test'

If the menu cannot complete, use the documented backup/recovery path rather than copying undocumented initramfs commands from another OS release.

Recover a system that does not boot

  1. Disconnect power and remove the storage only after activity stops.
  2. Mount bootfs on another computer or boot known-good recovery media.
  3. Preserve a copy of the current boot files before editing.
  4. Inspect recent changes and free space.
  5. Restore the last working configuration or disable the overlay through the supported tool from a bootable environment.
  6. Boot with a display/console attached and inspect the journal.

Do not repeatedly power-cycle a filesystem that may be damaged. Image or back up important partitions before repair attempts.

Directory-level OverlayFS experiment

To learn the lower/upper/work/merged model without changing the root filesystem, use disposable directories:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
mkdir -p "$HOME/overlay-demo"/{lower,upper,work,merged}
printf 'original\n' > "$HOME/overlay-demo/lower/example.txt"

sudo mount -t overlay overlay \
  -o "lowerdir=$HOME/overlay-demo/lower,upperdir=$HOME/overlay-demo/upper,workdir=$HOME/overlay-demo/work" \
  "$HOME/overlay-demo/merged"

cat "$HOME/overlay-demo/merged/example.txt"
printf 'changed\n' > "$HOME/overlay-demo/merged/example.txt"
cat "$HOME/overlay-demo/upper/example.txt"
sudo umount "$HOME/overlay-demo/merged"

upperdir and workdir must be on the same filesystem, and workdir must be empty. See the Linux kernel OverlayFS documentation for filesystem requirements and advanced behaviour.

Benchmark checklist

Compare the same workload with and without OverlayFS:

Metric Normal root OverlayFS root
Test duration
Application-ready time
Root device writes
Peak RAM used
Peak memory PSI
Persistent-data test
Reboot-reset test n/a
Update/recovery test

Record raw data and leave result cells blank until measured on named hardware. Use the benchmark methodology to control power, cooling, storage, and repetitions.

Common mistakes

  • Confusing OverlayFS with Device Tree overlays
  • Enabling it before classifying persistent data
  • Protecting /boot before testing the maintenance path
  • Assuming package updates persist while the overlay is active
  • Storing databases or identity only in the temporary upper layer
  • Ignoring RAM growth on a low-memory board
  • Using manual initramfs scripts copied from a different OS release
  • Treating read-only root as a backup

FAQ

Does Raspberry Pi OS include OverlayFS support?

Yes. Current Raspberry Pi OS exposes a supported read-only-root option in the desktop Control Centre and raspi-config.

Are changes saved while OverlayFS is enabled?

Changes to the overlaid root are temporary and disappear after reboot. Separately mounted writable data can persist.

Does OverlayFS prevent every SD card write?

No. The boot partition and other writable filesystems may still receive writes. Measure the actual block devices.

Can I update Raspberry Pi OS with OverlayFS enabled?

Commands may appear to work, but root changes are placed in the temporary layer. Disable the overlay, reboot, update and test, then re-enable it.

Is OverlayFS faster?

RAM-backed writes can be faster, but copy-up and memory pressure have costs. Its primary value here is controlled persistence and reduced lower-root writes, not a guaranteed speed increase.