1 files changed, 162 insertions, 0 deletions
diff --git a/recipes-core/initrdscripts/README.md b/recipes-core/initrdscripts/README.md
new file mode 100644
index 0000000..a038dfa
--- /dev/null
+++ b/recipes-core/initrdscripts/README.md
@@ -0,0 +1,162 @@
+# 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](#adding-the-readonly-rootfs-overlay-layer-to-your-build)
+1. [Read-only root filesystem](#read-only-root-filesystem)
+1. [Kernel command line parameters](#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.