docs: add overlayfs documentation

documentation/using-coreos.rst

@@ -228,6 +228,94 @@ following command:
     This is for development only if you do not use `debug-tweaks`. For releases
     this would be a real security problem.
 
+... configure a overlay filesystem
+**********************************
+
+Especially when you have a read-only filesystem you might want to have some
+directories to be writeable. This can be achieved by using a overlay filesystem.
+It is distinguished between two scenarios:
+
+1. The directory is located somewhere under `/etc`
+2. The directory is located under all other directories (except `/etc`)
+
+The main difference for directories located under `/etc` is that they are mostly
+config files that are used during the init process. However the init process
+itself usually mounts the overlay filesystem. Therefore another mechanism is
+needed which mounts the overlay before the actual init. This is solved by
+replacing the actual init with a script that mounts the overlay filesystem and
+then starts the actual init binary. But don't worry Yocto handles this for you.
+
+Following are the steps to easily add a overlay filesystem:
+
+**Overlay filesystem for directories under `/etc`**
+
+1. Create a partition (in the wic file) and specify the mount point.
+
+.. code-block:: bash
+
+    part /mnt/overlay --fstype=ext4 --rootfs-dir=${IMAGE_ROOTFS}/mnt/overlay --label overlay --align 1024 --ondisk mmcblk1 --size 128M
+
+2. Add `overlayfs-etc` to your `IMAGE_FEATURES` in the image file (e.g. coreos-image-minimal.bb)
+
+.. code-block:: bash
+
+    IMAGE_FEATURES += "overlayfs-etc"
+
+3. Provide overlay filesystem details in the machine config file (e.g. cn9130-cex7.conf)
+
+.. code-block:: bash
+
+    OVERLAYFS_ETC_MOUNT_POINT = "/mnt/overlay"
+    OVERLAYFS_ETC_DEVICE = "/dev/mmcblk1p5"
+    OVERLAYFS_ETC_FSTYPE ?= "ext4"
+
+4. Specify the directory that will be provided through the overlay filesystem in a recipe or bbappend file
+
+.. code-block:: bash
+
+    OVERLAYFS_WRITABLE_PATHS[overlay] += "/etc/ssh"
+
+More detailed information is available under the official Yocto Project
+documentation under `overlayfs-etc <https://docs.yoctoproject.org/4.0.4/ref-manual/classes.html#overlayfs-etc-bbclass>`_.
+
+**Overlay filesystem for other directories**
+
+1. Create a partition (in the wic file) and specify the mount point.
+
+.. code-block:: bash
+
+    part /mnt/overlay --fstype=ext4 --rootfs-dir=${IMAGE_ROOTFS}/mnt/overlay --label overlay --align 1024 --ondisk mmcblk1 --size 128M
+
+2. Add `overlayfs` to your `DISTRO_FEATURES` in the distro configuration file (e.g. belden-coreos.conf)
+
+.. code-block:: bash
+
+    DISTRO_FEATURES += "overlayfs"
+
+3. Specify the mount points in the machine configuration (e.g. cn9130-cex7.conf)
+
+.. code-block:: bash
+
+    OVERLAYFS_MOUNT_POINT[overlay] = "/mnt/overlay"
+
+4. Specify the directory that will be provided through the overlay filesystem in a recipe or bbappend file
+
+.. code-block:: bash
+
+    inherit overlayfs
+    OVERLAYFS_WRITABLE_PATHS[overlay] += "/etc/ssh"
+
+More detailed information is available under the official Yocto Project
+documentation under `overlayfs <https://docs.yoctoproject.org/4.0.4/ref-manual/classes.html#overlayfs-bbclass>`_.
+
+.. note::
+    The overlayfs QA check is looking for a systemd mount unit which is not
+    needed if you use wic. Therefore just disable the QA check with:
+
+    .. code-block:: bash
+
+        OVERLAYFS_QA_SKIP[overlay] = "mount-configured"
+
 Alternative repository structure
 ################################