Pull request #25: Docs/add overlayfs

Merge in ICO/coreos from docs/add_overlayfs to master

* commit '0acdffe0e57b24f68e8d9f50ca00e030efc3a82c':
  docs: add overlayfs documentation
  docs: change headline hirarchy and fix typos
  docs: add how to set a root password

documentation/using-coreos.rst

@@ -70,7 +70,7 @@ Then you can enter the following inside the product-init-build-env file:
 
     #!/bin/sh
 
-    # This script is used to setup the OE Build Envrionment
+    # This script is used to setup the OE Build Environment
     # Normally this is called as '. ./product-init-build-env <builddir>'
 
     # On some shell, we can get the path of this script when sources. Otherwise we
@@ -173,15 +173,16 @@ Open this file and enter the following:
 Then you can activate the distro by setting the `DISTRO` to `product` inside
 your `product/build/conf/local.conf` file. You should also set it in the 
 `product/templates/local.conf.sample` file so that it will be set as the default
-when create the build envrionment for the first time.
+when create the build environment for the first time.
 
 What to do next
 ###############
 
 How do I...
------------
+############
 
-**...add a PRODUCT_ROOT variable usable in recipes files?**
+...add a PRODUCT_ROOT variable usable in recipes files?
+*******************************************************
 
 Add this line inside your meta-product layer configuration file at 
 `product/layers/meta-product/conf/layer.conf`:
@@ -191,13 +192,130 @@ Add this line inside your meta-product layer configuration file at
     # Set a variable to get to the top of the metadata location
     PRODUCT_ROOT = '${@os.path.normpath("${LAYERDIR}/../../")}'
 
-**... add PRODUCT_METADATA_BRANCH and PRODUCT_METADATA_REVISION variables to get the
+... add PRODUCT_METADATA_BRANCH and PRODUCT_METADATA_REVISION variables to get the current git branch and git sha of the PRODUCT repository?
-current git branch and git sha of the PRODUCT repository?**
+*********************************************************************************************************************************************
 
 Create the file `product/layers/meta-product/classes/product_metadata_scm.bbclass`
 and copy the content of the coreos_metadata_scm.bbclass file. Replacing all
 reference to COREOS by PRODUCT should works.
 
+... set a root password
+***********************
+
+If you have `debug-tweaks` set in `EXTRA_IMAGE_FEATURES` you will not be asked for
+a root password when logging in. If `debug-tweaks` is not set (should not be set in
+the final product) you cannot login with root anymore. Therefore you need to set a
+root password with:
+
+.. code-block:: ini
+
+    IMAGE_CLASSES += "extrausers"
+
+    PASSWD='\$5\$sj6q14XssP2LRRFr\$U1EcE5DS/viWXWGdK1eRseoPzX6bSe5C9kWlKUXibl.'
+    EXTRA_USERS_PARAMS = "\
+        usermod -p '${PASSWD}' root; \
+        "
+
+The password needs to be provided as a hash and can be created on the host with
+following command:
+
+.. code-block:: bash
+
+    printf "%q\n" $(mkpasswd -m sha256crypt root)
+
+.. warning::
+
+    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
 ################################