OverlayRootfs: Safeguard Your Root Filesystem for Better Security

Introduction to OverlayRootfs

OverlayRootfs refers to a root filesystem created using OverlayFS technology. OverlayFS is a union filesystem (UnionFS) that allows multiple filesystem layers to be merged into a single view and is widely used in Linux systems. Devices using OverlayRootfs can easily implement write-protection and factory reset features for the root filesystem.

Root File System Write Protection

On Firefly devices that support OverlayRootfs, the rootfs partition is mounted read-only at /root-ro (the lower layer). All user modifications are written to /userdata/rootfs_overlay (the upper layer) on the userdata partition, not to the rootfs partition. This ensures that the rootfs partition data remains read-only and is not corrupted. OverlayRootfs merges /root-ro and /userdata/rootfs_overlay into a single view, making it invisible to the user.

Example Description

Frequent power outages and reboots on Linux devices can damage read-write partitions, preventing them from booting properly. Firefly devices with OverlayRootfs enabled use the userdata partition as the actual read/write partition. Even if a power outage damages the userdata partition, the device can still boot the root file system in read-only mode. Users can still control the device to perform partition recovery and data preservation operations. Here's an example of a system booting in read-only mode after manually destroying the userdata partition:

You can create or delete a file to test OverlayRootfs. The real data is written to /userdata/rootfs_overlay.

1. # Create a file that can be found in the same directory under /userdata/rootfs_overlay/
2. root@firefly:~# touch /usr/local/bin/firefly-test
3. root@firefly:~# ls /userdata/rootfs_overlay/usr/local/bin/firefly-test
4. /userdata/rootfs_overlay/usr/local/bin/firefly-test
5.  
6. # Delete the corresponding files under /userdata/rootfs_overlay/. The corresponding files in the real file system will also be modified.
7. root@firefly:~# rm -rf /userdata/rootfs_overlay/usr/local/bin/firefly-test
8. root@firefly:~# ls /usr/local/bin/
9. disable_ModemManager.sh docker-compose ec200.sh quectel-CM restart_plank.sh

Since the rootfs partition is read-only and cannot be modified, you can use df -h to see that the available space on the rootfs partition is small. This is normal because the user actually writes to the userdata partition.

Restore Factory Settings

Executing "recovery reset" will automatically erase the userdata partition, restoring the device's file system to its initial state just after flashing.

1. # Create a file verification function and execute recovery reset to restore factory settings.
2. root@firefly:~# touch /home/firefly/test
3. root@firefly:~# ls /home/firefly/test
4. /home/firefly/test
5. root@firefly:~# recovery reset
6. command: --wipe_all
7. update: write command to command file: done
8. update: write command to misc file: done
9. update: reboot!
10.  
11. # After reboot
12. root@firefly:~# ls /home/firefly/test
13. ls: cannot access '/home/firefly/test': No such file or directory
14.  

Disable OverlayRootfs

OverlayRootfs may need to be disabled in some scenarios, such as fast startup, A&B system, etc. You can enable/disable the OverlayRootfs function by modifying the kernel startup parameters. For example, RK3576:

1. # Modify the kernel's dts chosen node.
2. kernel/arch/arm64/boot/dts/rockchip/rk3576-linux.dtsi
3.  
4. chosen: chosen {
5. // Disable OverlayRootfs functionality
6. //bootargs = "earlycon=uart8250,mmio32,0x2ad40000 console=ttyFIQ0 root=PARTUUID=614e0000-0000 rw rootwait rcupdate.rcu_expedited=1 rcu_nocbs=all";
7. // Enable OverlayRootfs functionality
8. bootargs = "earlycon=uart8250,mmio32,0x2ad40000 console=ttyFIQ0 root=PARTLABEL=rootfs rootfstype=ext4 ro rootwait overlayroot=device:dev=PARTLABEL=userdata,fstype=ext4,mkfs=1 rcupdate.rcu_expedited=1 rcu_nocbs=all net.ifnames=0";