Raspberry Pi Overlay Root Filesystem

I copied this from https://yagrebu.net/unix/rpi-overlay.md so I don't loose it. I have done a lot of network booting and overlay file system work this last year and these are the best directions for overlay file system and don't want to loose them. I will rewrite them to include my own subtle changes at some point, and publish network booting and network booting + overlay file system (which is a total crazy mess with no directions).

Raspberry Pi Overlay Root Filesystem

This document describes a method to protect the root filesystem from writes while still allowing all applications to function as normal while writing to a temporary Overlay filesystem. Figuring this out would have been impossible for me without this excellent post by ejolson on the RPI.org forums.

For my installation I used a RPI 3 and the latest Raspbian Stretch Lite image (2017-11-29). I do not know if these instructions will work without modification on earlier RPI hardware.

Note: When the overlay filesystem is in place your RPI will function as usual, but any data generated after startup is only saved in RAM and will be lost upon reboot.

Let's Begin

First we need to create a initramfs image that contains the overlay module and a boot script to mount our root partition with the overlay. (All this could of course be compiled into the kernel image, but initramfs-tools(8) is an easier way to learn about the early init-process.)

echo overlay >>/etc/initramfs-tools/modules

Place the following boot script in /etc/initramfs-tools/scripts/overlay (download):

# Local filesystem mounting                     -*- shell-script -*-

#
# This script overrides local_mount_root() in /scripts/local
# and mounts root as a read-only filesystem with a temporary (rw)
# overlay filesystem.
#

. /scripts/local

local_mount_root()
{
        local_top
        local_device_setup "${ROOT}" "root file system"
        ROOT="${DEV}"

        # Get the root filesystem type if not set
        if [ -z "${ROOTFSTYPE}" ]; then
                FSTYPE=$(get_fstype "${ROOT}")
        else
                FSTYPE=${ROOTFSTYPE}
        fi

        local_premount

        # CHANGES TO THE ORIGINAL FUNCTION BEGIN HERE
        # N.B. this code still lacks error checking

        modprobe ${FSTYPE}
        checkfs ${ROOT} root "${FSTYPE}"

        # Create directories for root and the overlay
        mkdir /lower /upper

        # Mount read-only root to /lower
        if [ "${FSTYPE}" != "unknown" ]; then
                mount -r -t ${FSTYPE} ${ROOTFLAGS} ${ROOT} /lower
        else
                mount -r ${ROOTFLAGS} ${ROOT} /lower
        fi

        modprobe overlay

        # Mount a tmpfs for the overlay in /upper
        mount -t tmpfs tmpfs /upper
        mkdir /upper/data /upper/work

        # Mount the final overlay-root in $rootmnt
        mount -t overlay \
            -olowerdir=/lower,upperdir=/upper/data,workdir=/upper/work \
            overlay ${rootmnt}
}

Create the initramfs image:

update-initramfs -c -k $(uname -r)

It will be placed in /boot/initrd.img<kernel_version> - you can rename it to match your kernel file if you want.

Add the following to /boot/config.txt - where initrd7.img is the initramfs image you created in the previous step:

kernel=kernel7.img
initramfs initrd7.img

And finally, add boot=overlay to the beginning of /boot/cmdline.txt.

This should do it. Reboot and keep your fingers crossed.

Kernel Panic

If the OS doesn't come back up, there is probably a typo somewhere, or you missed something.

You can remove boot=overlay from cmdline.txt to boot as normal.

A serial connection can be really handy when trying to troubleshoot the startup process. USB TTL console cables are dirt cheap, just make sure you get one that outputs 3.3V on the TX line so that you don't fry your RPI. Use screen(1)'s buffer to scroll back and try to figure out where it went wrong.

The documentation is also quite good. Read the man page for initramfs-tools(8) and the default boot scripts themselves:

less /usr/share/initramfs-tools/init
less /usr/share/initramfs-tools/scripts/local

Finishing Touches

Read-Only /boot

The /boot filesystem is still mounted rw. You can protect it as well by adding ro to the boot partitions mount options in /etc/fstab:

PARTUUID=72a9e9a9-01   /boot   vfat   defaults,ro   0   2

overctl

Since I would be updating the filesystem on my RPI regularly, I wanted a secure way to enable and disable the overlay. overctl has the following features:

Usage: overctl [-h|-r|-s|-t|-w]
   -h, --help     This message
   -r, --ro       Set read-only root with overlay fs
   -s, --status   Show current state
   -t, --toggle   Toggle between -r and -w
   -w, --rw       Set read-write root

Place the script in /usr/local/sbin and mark the file as executable. You will also need to create the following files containing the cmdline.txt options that you wish to toggle between:

/boot/cmdline.txt.orig
/boot/cmdline.txt.overlay

motd(5)

I figured I could use a reminder of which state the RPI is in. So I cobbled together this motd(5) script:

#!/bin/sh

str=$(mount | grep ' on / ')

if echo $str | grep -q 'overlay'; then
        printf "\n------ INFO: / MOUNTED WITH OVERLAY ------\n\n"
elif echo $str | grep -q 'rw'; then
        printf "\n++++++ INFO: / MOUNTED READ-WRITE ++++++\n\n"
else
        printf "\n!!!!!! WARNING: / UNKNOWN STATE !!!!!!\n\n"
fi

Place the code above in /etc/update-motd.d/80-overlay and make sure the file is executable.