Verification of Read-Only Mode in the PL-R5 Trixie Environment

Industrial Raspberry Pi systems need to be robust, both in terms of hardware and software.
In particular, setting the system files to read-only can reduce the risk of corruption caused by unexpected shutdowns and prevent unintended changes from being permanently retained, making the system more robust.

Raspberry Pi OS Trixie differs significantly from previous versions, so some older information is no longer applicable.
In this article, I tested the read-only configuration again in a Trixie environment.

Test Environment

The Raspberry Pi system used for this test is designed for industrial applications, so it differs somewhat from commercially available Raspberry Pi CM-based systems.

• PL-R5 USB IP20 (https://pilink.jp/product/pl-r5-usb-ip20/)
• 32 GB microSD card
• Model: Raspberry Pi Compute Module 5 Rev 1.0
• OS: Debian GNU/Linux 13 (Trixie)
• Kernel: 6.18.29+rpt-rpi-2712

Check the Network Settings

Before enabling OverlayFS, make sure that sudo apt update completes successfully.

Because raspi-config installs the overlayroot package internally, the configuration process may fail if the network or DNS connection is unstable.
To check the network settings, I used the ip and nmcli commands as shown below.

ip route
default via 192.168.0.1 dev eth0 proto static metric 100 
192.168.0.0/24 dev eth0 proto kernel scope link src 192.168.0.10 metric 100

Use the nmcli command to check the connection name.

nmcli connection show

If there is no network connection, configure it by specifying the connection name listed under NAME.
The following is an example of configuring the network for eth0.
Alternatively, you can configure the network from the desktop GUI.

sudo nmcli connection modify "Wired connection 1" \
  ipv4.method manual \
  ipv4.addresses 192.168.0.10/24 \
  ipv4.gateway 192.168.0.1 \
  ipv4.dns 192.168.0.1 \
  ipv4.never-default no

From this point on, you can continue the setup via SSH.

Data Storage Area

This behavior depends on the design of the carrier board, so it is important to check the specifications of the system you are using.
For this PL-R5 configuration, the eMMC is used as the boot drive and the microSD card as the data storage area.

■ Note
With the PL-R5 running Raspberry Pi OS Trixie, I had to add dtoverlay=sdio-pi5 to /boot/firmware/config.txt for the microSD card to be recognized.
Add the line after [ALL].

Create a Writable Storage Location

When I checked the separate microSD device using the lsblk command, it was recognized as mmcblk2p1. I created a /data directory and added an entry to fstab so that the microSD card would be mounted automatically at startup.

lsblk

NAME         MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
loop0          7:0    0    2G  0 loop 
mmcblk0      179:0    0 29.1G  0 disk 
├─mmcblk0p1  179:1    0  512M  0 part /boot/firmware
└─mmcblk0p2  179:2    0 28.6G  0 part /
mmcblk0boot0 179:32   0    4M  1 disk 
mmcblk0boot1 179:64   0    4M  1 disk 
mmcblk2      179:96   0 28.8G  0 disk 
└─mmcblk2p1  179:97   0 28.8G  0 part 
zram0        254:0    0    2G  0 disk [SWAP]

Create the /data directory and mount the partition.

sudo mkdir -p /data
sudo mount /dev/mmcblk2p1 /data

Check the UUID.
The UUID is required when adding the entry to fstab.

sudo blkid /dev/mmcblk2p1
/dev/mmcblk2p1: LABEL="data" UUID="76a0c4e4-5072-411f-ae8e-4daf55604603" BLOCK_SIZE="4096" TYPE="ext4" PARTUUID="3dfbf2f1-01"

Add /data to fstab

Specify the UUID and add the following entry to the end of fstab.

sudo nano /etc/fstab

UUID=76a0c4e4-5072-411f-ae8e-4daf55604603 /data ext4 defaults 0 2

The automatic mount configuration is now complete. Reboot the system and use the lsblk command to verify that the partition is mounted correctly.

The preparation is now complete. The next step is to enable OverlayFS and make the system files read-only.

Enable OverlayFS

OverlayFS can be configured from the raspi-config menu by running sudo raspi-config.

Steps to Enable OverlayFS

Menu: Performance Options → Overlay File System → Enable

Keep the /boot partition writable.

Normally, OverlayFS should now be enabled. However, it did not work in this environment (the official Raspberry Pi OS and the PL-R5).
The cause was that the overlay module had not been loaded.
This behavior may vary depending on the version. If OverlayFS is not enabled after rebooting, try the following workaround.

Troubleshooting When OverlayFS Does Not Work

I encountered a situation where OverlayFS did not work even after it had been configured correctly and the system had been rebooted. There may be other possible causes, so the following solution will not apply in every case.
This workaround applies when the overlay module has not been loaded.

At the time of writing, I was able to resolve the issue by explicitly configuring the system to load the module.
This may depend on the environment, but I found that the required module was not being loaded automatically.

# Edit the modules file
sudo nano /etc/initramfs-tools/modules

# Add the following
overlay

# Update initramfs
sudo update-initramfs -u

# Reboot
sudo reboot

OverlayFS should now be enabled.
This workaround will no longer be necessary if the issue is fixed in a future Raspberry Pi OS update.

Exclude /data from OverlayFS

When OverlayFS is enabled using raspi-config, the /data directory created earlier is also made read-only.
Depending on the intended use, this may not be desirable, so we will configure /data to be excluded from OverlayFS.

Edit cmdline.txt.

sudo nano /boot/firmware/cmdline.txt

As shown below, append :recurse=0 to overlayroot=tmpfs at the beginning of the line.

overlayroot=tmpfs:recurse=0

Then reboot the system.
Before excluding /data, the output of the following command showed it under root-ro as read-only.

mount | grep /data

/dev/mmcblk2p1 on /media/root-ro/data type ext4 (ro,relatime)
/media/root-ro/data on /data type overlay (rw,relatime,lowerdir=/media/root-ro/data,upperdir=/media/root-rw/overlay/data,workdir=/media/root-rw/overlay-workdir/data,uuid=on)

After applying the exclusion setting, the output shows rw, meaning that /data can be read from and written to normally.

/dev/mmcblk2p1 on /data type ext4 (rw,relatime)

The root filesystem, meanwhile, remains mounted as overlayroot on / type overlay. This is expected and does not cause a problem.

mount | grep " on / "

overlayroot on / type overlay (rw,relatime,lowerdir=/media/root-ro,upperdir=/media/root-rw/overlay,workdir=/media/root-rw/overlay-workdir/_,uuid=on)

Use the following two commands to verify the status of /data and the root filesystem.

mount | grep /data
mount | grep " on / "

■ Note
When recurse=0 is specified, OverlayFS applies only to the root filesystem (/).
Because /data on the microSD card is mounted as a separate filesystem in this configuration, it is excluded from OverlayFS and data is written directly to the microSD card.
Although it is not explicitly written in the configuration, the internal default is effectively overlayroot=tmpfs:recurse=1.

Disable OverlayFS When Making Changes

One possible use of this configuration is to use the writable /data directory as the output destination for applications.
If you later need to install an application or change system settings while OverlayFS is enabled, changes made to the root filesystem will be lost after a reboot.
We therefore recommend temporarily disabling OverlayFS, making the required changes or additions, and then enabling it again.

OverlayFS must also be disabled when changing OS settings or updating packages.

To disable OverlayFS, follow the same raspi-config procedure used to enable it.
This time, select Disable.

Steps to Disable OverlayFS

Menu: Performance Options → Overlay File System → Disable

In this environment, OverlayFS could not be fully disabled using raspi-config alone, and the configuration file also had to be checked.
To complete the process, follow the workaround below.

Troubleshooting When OverlayFS Cannot Be Disabled

Normally, disabling OverlayFS with raspi-config should also remove the overlayroot=tmpfs entry added to cmdline.txt.
However, in this environment, the entry remained. No matter how many times I tried, OverlayFS was not disabled and the filesystem did not return to its normally writable state.

As a workaround, after following the normal procedure to disable OverlayFS, I had to manually remove the relevant entry.

sudo nano /boot/firmware/cmdline.txt

Delete the following entry from the beginning of the line.

overlayroot=tmpfs:recurse=0

As with the workaround for enabling OverlayFS, this step will no longer be necessary if the issue is fixed in a future Raspberry Pi OS update.

Operational Procedures Matter

In a system used for personal purposes, settings may be changed and applications added or removed frequently.
Using OverlayFS in this way can therefore be cumbersome.

In industrial applications rather than personal desktop environments, however, such changes are generally less frequent.
Because it is also possible to forget to re-enable OverlayFS after disabling it, one approach is to designate a maintenance day once a month and perform OS updates, configuration changes, and software installations together.

Commands can still be executed even when OverlayFS is enabled.
For example, sudo apt install ~ may appear to install a package successfully, and the installed software can actually be used. However, the changes are written only to temporary storage and will disappear after a reboot.

One drawback of OverlayFS is that it is not immediately obvious whether it is enabled or disabled.
For this reason, operational procedures after the system has been configured are particularly important.

Display the OverlayFS Status at SSH Login

Displaying a status message for system administrators can be useful.
Although this applies only to SSH logins, displaying the current OverlayFS status can help prevent administrators from forgetting to disable or re-enable it when necessary.

sudo nano ~/.bashrc

# OverlayFS status

if mount | grep -q "overlayroot on /"; then
    echo ""
    echo "======================================"
    echo " The system is currently in read-only mode (OverlayFS enabled)"
    echo " Changes will be lost after reboot"
    echo "======================================"
    echo ""
fi

This should make the current status easier to notice.

Issues with the raspi-config Method

In a Trixie environment, simply enabling OverlayFS with raspi-config may not always be enough for it to work correctly.

At least in the environment tested at the time of writing, it was necessary to explicitly add the overlay kernel module to /etc/initramfs-tools/modules.
In addition, cmdline.txt had to be edited after following the procedure to disable OverlayFS.

■ Enable:
raspi-config
↓
Enable
↓
Verify that overlay is listed in /etc/initramfs-tools/modules
If you add it, run sudo update-initramfs -u
↓
Add :recurse=0 to cmdline.txt (required each time OverlayFS is enabled)
↓
reboot

■ Disable:
raspi-config
↓
Disable
↓
Remove overlayroot=tmpfs:recurse=0 from cmdline.txt (required each time OverlayFS is disabled)
↓
reboot

In short, the process could not be completed using raspi-config alone in this environment.
Because no error message is displayed, the problem can easily go unnoticed.

Please note that the workarounds described in this article may no longer be necessary as Raspberry Pi OS is updated.
Hopefully, a future Raspberry Pi OS update will allow the entire process to be completed using raspi-config alone.