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.