diff --git a/documentation/using-coreos.rst b/documentation/using-coreos.rst index 160a03e..e262a7f 100644 --- a/documentation/using-coreos.rst +++ b/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 ' # 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 -current git branch and git sha of the PRODUCT repository?** - +... add PRODUCT_METADATA_BRANCH and PRODUCT_METADATA_REVISION variables to get the 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 `_. + +**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 `_. + +.. 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 ################################