LM
/
coreos
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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
This commit is contained in:
Patrick Vogelaar 2022-12-15 15:59:21 +01:00
parent 831173afaf 0acdffe0e5
commit e4f701b315
1 changed files with 125 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
documentation/using-coreos.rst
View File

@ -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
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 <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
################################