README.md

meta-readonly-rootfs-overlay

This OpenEmbedded layer provides the necessary scripts and configurations to setup a writable root file system overlay on top of a read-only root file system.

Why does this exists?

Having a read-only root file system is useful for many scenarios:

• Separate user specific changes from system configuration, and being able to find differences
• Allow factory reset, by deleting the user specific changes
• Have a fallback image in case the user specific changes made the root file system no longer bootable.

Because some data on the root file system changes on first boot or while the system is running, just mounting the complete root file system as read-only breaks many applications. There are different solutions to this problem:

• Symlinking/Bind mounting files and directories that could potentially change while the system is running to a writable partition
• Instead of having a read-only root files system, mounting a writable overlay root file system, that uses a read-only file system as its base and writes changed data to another writable partition.

To implement the first solution, the developer needs to analyse which file needs to change and then create symlinks for them. When doing factory reset, the developer needs to overwrite every file that is linked with the factory configuration, to avoid dangling symlinks/binds. While this is more work on the developer side, it might increase the security, because only files that are symlinked/bind-mounted can be changed. However, IMO that is better left to file permissions.

This meta-layer provides the second solution. Here no investigation of writable files are needed and factory reset can be done by just deleting all files or formatting the writable volume.

Dependencies

This layer depends on:

  URI: git://git.openembedded.org/bitbake
  branch: krogoth

  URI: git://git.openembedded.org/openembedded-core
  layers: meta
  branch: krogoth

Patches

Please submit any patches against the readonly-rootfs-overlay layer via pull request.

Table of Contents

1. Adding the readonly-rootfs-overlay layer to your build
2. Read-only root filesystem
3. Kernel command line parameters

Adding the readonly-rootfs-overlay layer to your build

In order to use this layer, you need to make the build system aware of it.

Assuming the readonly-rootfs-overlay layer exists at the top-level of your OpenEmbedded source tree, you can add it to the build system by adding the location of the readonly-rootfs-overlay layer to bblayers.conf, along with any other layers needed. e.g.:

  BBLAYERS ?= " \
    /path/to/layers/meta \
    /path/to/layers/meta-poky \
    /path/to/layers/meta-yocto-bsp \
    /path/to/layers/meta-readonly-rootfs-overlay \
    "

To add the script to your image, just add:

  IMAGE_INSTALL_append = " initscripts-readonly-rootfs-overlay"

to your local.conf or image recipe. Or use core-image-rorootfs-overlay-initramfs as initrd.

Read-only root filesystem

If you use this layer you do not need to set read-only-rootfs in the IMAGE_FEATURES or EXTRA_IMAGE_FEATURES variable.

Kernel command line parameters

These examples are not meant to be complete. They just contain parameters that are used by the initscript of this repository. Some additional paramters might be necessary.

Example using initrd:

root=/dev/sda1 rootrw=/dev/sda2

This cmd line start /sbin/init with the /dev/sda1 partition as the read-only rootfs and the /dev/sda2 partition as the read-write persistent state.

root=/dev/sda1 rootrw=/dev/sda2 init=/bin/sh

The same as before but it now starts /bin/sh instead of /sbin/init.

Example without initrd:

root=/dev/sda1 rootrw=/dev/sda2 init=/init

This cmd line starts /sbin/init with /dev/sda1 partition as the read-only rootfs and the /dev/sda2 partition as the read-write persistent state. When using this init script without an initrd, init=/init has to be set.

root=/dev/sda1 rootrw=/dev/sda2 init=/init rootinit=/bin/sh

The same as before but it now starts /bin/sh instead of /sbin/init

Details

root= specifies the read-only root file system device. If this is not specified, the current rootfs is used.

rootfstype= if support for the read-only file system is not build into the kernel, you can specify the required module name here. It will also be used in the mount command.

rootoptions= specifies the mount options of the read-only file system. Defaults to noatime,nodiratime.

rootinit= if the init parameter was used to specify this init script, rootinit can be used to overwrite the default (/sbin/init).

rootrw= specifies the read-write file system device. If this is not specified, tmpfs is used.

rootrwfstype= if support for the read-write file system is not build into the kernel, you can specify the required module name here. It will also be used in the mount command.

rootrwoptions= specifies the mount options of the read-write file system. Defaults to rw,noatime,mode=755.

rootrwreset= set to yes if you want to delete all the files in the read-write file system prior to building the overlay root files system.