Change overlayroot to use /etc/overlayroot.local.conf instead of cmdine.txt, and make it compatible with users' configuration

[JinShil]

See raspberrypi/bookworm-feedback#137 for a discussion of what prompted this pull request.

I believe the procedures to enable and disable the readonly file system overlay can be improved.

My understanding is that Raspberry Pi would prefer to follow the conventions and best practices of upstream repositories whenever possible. As I did my research on the aforementioned issue, I discovered, in the overlayroot documentation, that it should be enabled by modifying the /etc/overlayroot.local.conf file (See /etc/overlayroot.conf for documentation), and that changes to any overlayed file system can be made through the overlayroot-chroot command. See https://manpages.debian.org/bookworm/overlayroot/overlayroot-chroot.8.en.html

This method a few advantages:

1. It addresses the aforementioned issue making it compatible with users' overlayroot configuration
2. It is congruent with the upstream repository's intent
3. It does not need to modify /boot/cmdline.txt, meaning it is no longer necessary to reboot twice when enabling/disabling write protection on the /boot partition.

Although it is no longer necessary to reboot twice when enabling/disabling write protection on the /boot partition, I have not made such a change to keep this pull request as least intrusive as possible. Should this pull request be pulled, a subsequent pull request could be made to enable/disable overlayroot and the write protection on the boot partition simultaneously when one reboot.

[JinShil]

A little more detail on how this makes raspi-config more compatible with users' overlayroot configuration:

It is quite common for those utilizing the readonly overlay to also have another read/write partition or disk. Beginning with Bookworm, the overlayroot, through its default recurse=1 configuration, causes all partitions and disks to be read-only once the overlay is enabled.

For users that need a read/write partition or disk, they can add a commented line of #overlayroot="temps:recurse=0" (or whatever other configuration they prefer) to their /etc/overlayroot.local.conf file, and, using the implementation in this pull request, enabling the overlay will simply uncomment that line, leaving the user's configuration intact. Similarly, disabling the overlay will simply comment that line, leaving the user's configuration intact.

[JinShil]

It is also possible to disable the overlay by adding overlay="" or overlay="disabled" to /boot/cmdline.txt, but I figured I'd try overlayroot-chroot first as that appears to be what the authors of overlayroot intended, at least according to my reading of the source code at https://git.launchpad.net/cloud-initramfs-tools/

[JamesH65]

@XECDesign @ghollingworth Have you any thoughts on this?

[XECDesign]

@XECDesign @ghollingworth Have you any thoughts on this?

It has a few nice features over what we have already.

However, what we have already had been tested and works, so this isn't on my todo list right now.

[haukex]

I think it would be great if this or something like this would be supported. My current workaround is not pretty (applying this patch to raspi-config).

[JinShil]

what we have already had been tested and works

The reason for this pull request is that the current implementation does not work for those that utilize additional read-write partitions/disks.

Edit: Also, the implementation in Bullseye did work with read-write partitions and disks, so the implementation in Bookworm potentially breaks existing solutions.

[GrubbyHalo]

Just to add... I have a HAT that has a spi-nand memory device for use as r/w storage. Enabling the overlay on the pi (Bookworm) unexpectedly added the mount for that device to the overlay. This never happened in Bulleseye and previous.

[pietervandermeer]

If one uses a BTRFS data partition besides the boot and root partitions.. which was recommended in an official Raspberry Pi document, then this is a must-have. I just hacked raspi-config to modify cmdline.txt with:

"overlayroot=tmpfs:recurse=0" instead of the old "overlayroot=tmpfs"..

Can overlayroot-chroot be used in a script somehow?

[haukex]

Bump. I see that there are a number of other open pull requests related to the Overlay Filesystem: #135, #193, #208, #254. To the current maintainers - it looks like that's @spl237 and @XECDesign: Are there plans for the overlay filesystem functionality?

For anyone else encountering this issue, my workaround for this particular pull request is still the same as two years ago - this patch:

--- /usr/bin/raspi-config.orig	2025-09-02 12:59:22.179236681 +0200
+++ /usr/bin/raspi-config	2025-09-02 13:06:43.404133245 +0200
@@ -3484,7 +3484,7 @@
 
   # modify command line
   if ! grep -q "overlayroot=tmpfs" $CMDLINE ; then
-    sed -i $CMDLINE -e "s/^/overlayroot=tmpfs /"
+    sed -i $CMDLINE -e "s/^/overlayroot=tmpfs:recurse=0 /"
   fi
 
   if [ "$BOOTRO" = "yes" ] ; then
@@ -3507,7 +3507,7 @@
   fi
 
   # modify command line
-  sed -i $CMDLINE -e "s/\(.*\)overlayroot=tmpfs \(.*\)/\1\2/"
+  sed -i $CMDLINE -e "s/\(.*\)overlayroot=tmpfs:recurse=0 \(.*\)/\1\2/"
 
   if [ "$BOOTRO" = "yes" ] ; then
     if ! mount -o remount,ro /boot${FIRMWARE} 2>/dev/null ; then

[XECDesign]

Bump. I see that there are a number of other open pull requests related to the Overlay Filesystem: #135, #193, #208, #254. To the current maintainers - it looks like that's @spl237 and @XECDesign: Are there plans for the overlay filesystem functionality?

Yes, I'm convinced we should implement it better. But right now getting trixie and cloud-init ready are top priority. I don't want to merge things without a proper review (that has never worked out well), so this is going to have to sit on the shelf for a while.

[haukex]

@XECDesign Thanks for the reply, and of course I understand having a lot to do :-) I consider myself decent enough at bash, so feel free to let me know if there is anything I can do to help.

[JinShil]

I'm closing this.

I've recently found a much better way to have the benefits of a read-only file system overlay:

1. Forget the overlay. Just uninstall it with sudo apt purge overlayroot.
2. Create a read-write data partition. You may need to put it in between the boot and root partitions due to limitations in how raspi-config expands the file system to consume unutilized disk space (i.e. it's hardcoded to expect the root file system as the last partition).
3. Add ro to the kernel command line.
4. Add ro to the root file system's entry in /etc/fstab.
5. Add bind mounts for /var and any other directories you want to be read-write. Here's a sample:

proc                  /proc           proc    defaults             0       0
PARTUUID=bbf49b42-01  /boot/firmware  vfat    defaults             0       2
PARTUUID=bbf49b42-02  /data           ext4    defaults,noatime     0       1
PARTUUID=bbf49b42-03  /               ext4    defaults,noatime,ro  0       1
/data/.var            /var            none    rbind                0       0
/run/media            /media          none    rbind                0       0

Reboot and you'll have a read-only file system with a read-write data partition. Logs are written to /var, which is bind-mounted to /data/.var, and therefore, read-write. If you want to make changes to the root file system, just run sudo mount -o remount,rw / and make your changes. Use that method to reverse the aforementioned changes if you want to go back to a read-write file system. This is so much simpler than hassling with the complexity of the overlay.

[pietervandermeer]

@JinShil Thanks, yes, this would be ideal. Previously I used to run embedded systems just like that. Until Samba became required.. My question: does Samba also like your solution??? It really wants to write its logs. I tried bind mounts previously, but either I messed up, or Samba still didn't like it..

Also please note that a rw /var may become corrupted if its ext4 and someone pulls the plug. ext4 only has metadata journalling. You'd need a data partition with CoW functionality / full data journalling. But your solution would allow for that. Just change the data partition file system..