383 lines
13 KiB
ReStructuredText
383 lines
13 KiB
ReStructuredText
********************************
|
|
Setting up a CoreOS based distro
|
|
********************************
|
|
|
|
This chapter explains how to setup a distro based on CoreOS.
|
|
|
|
Repository structures
|
|
#####################
|
|
|
|
OpenEmbedded is a flexible tool, but we encourage each of our users to adopt
|
|
the same structure as CoreOS. In this chapter, replace each usage of `PRODUCT`
|
|
or `product` by a unique name related to your product.
|
|
|
|
.. code-block::
|
|
|
|
product/
|
|
├── build/ (ignored by git)
|
|
├── documentation/
|
|
├── layers/
|
|
| └── coreos/ (submodule)
|
|
| | └── bitbake/ (submodule)
|
|
| | └── layers/
|
|
| | | ├── openembedded-core (submodule)
|
|
| | | ├── meta-belden-coreos
|
|
| | | ├── meta-belden-coreos-bsp
|
|
| | | └── ...
|
|
| | └── ...
|
|
| ├── meta-product/
|
|
| ├── meta-other-layers/
|
|
| └── ...
|
|
├── scripts/
|
|
├── templates/
|
|
├── product-init-build-env
|
|
├── .gitignore
|
|
|
|
Creating the structures
|
|
#######################
|
|
|
|
.. code-block:: sh
|
|
|
|
~$ mkdir product
|
|
~$ cd product
|
|
~/product$ git init
|
|
~/product$ git submodule init
|
|
|
|
~/product$ mkdir layers
|
|
~/product$ mkdir scripts
|
|
|
|
~/product$ git submodule add -b <branch> ssh://git@bitbucket.gad.local:7999/ico/coreos.git layers/coreos
|
|
~/product$ git submodule update --init --recursive
|
|
|
|
~/product$ cp -r layers/coreos/templates ./templates
|
|
~/product$ cp layers/coreos/.gitignore ./.gitignore
|
|
|
|
~/product$ touch product-init-build-env
|
|
~/product$ chmod +x product-init-build-env
|
|
~/product$ nano product-init-build-env
|
|
|
|
.. note::
|
|
|
|
By copying the .gitignore file of CoreOS, the build directory in the the product
|
|
repository will not be tracked by Git, which is the recommended approach as using
|
|
`devtool modify` modifies the local `bblayers.conf`. Instead we recommend to
|
|
keep the template directory up to date so that a sane configuration can be
|
|
created when fetching the repository for the first time.
|
|
|
|
Then you can enter the following inside the product-init-build-env file:
|
|
|
|
.. code-block:: sh
|
|
|
|
#!/bin/sh
|
|
|
|
# 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
|
|
# use the current directory as a fallback
|
|
if [ -z "$PRODUCT_ROOT" ]; then
|
|
if [ -n "$BASH_SOURCE" ]; then
|
|
PRODUCT_ROOT=$(dirname "$BASH_SOURCE")
|
|
elif [ -n "$ZSH_NAME" ]; then
|
|
PRODUCT_ROOT=$(dirname "$0")
|
|
else
|
|
PRODUCT_ROOT="$(pwd)"
|
|
fi
|
|
fi
|
|
|
|
# Get a non relative path to the root directory
|
|
PRODUCT_ROOT=$(readlink -f "${PRODUCT_ROOT}")
|
|
|
|
# CoreOS init settings
|
|
COREOS_ROOT="${PRODUCT_ROOT}/layers/coreos"
|
|
TEMPLATECONF="${PRODUCT_ROOT}/templates"
|
|
|
|
# Call the coreos-init-build-env scripts of CoreOS
|
|
. "${COREOS_ROOT}/coreos-init-build-env" "${1:-$PRODUCT_ROOT/build}"
|
|
|
|
# From here the scripts and functions defined by CoreOS and
|
|
# OpenEmbedded-Core are available
|
|
|
|
# Add support for ##PRODUCTS_LAYERSDIR## inside of bblayer template
|
|
coreos-bblayers-envsub PRODUCT_LAYERSDIR "${PRODUCT_ROOT}/layers"
|
|
|
|
# Add the scripts directory of the product to the path
|
|
coreos_path_add "${PRODUCT_ROOT}/scripts"
|
|
|
|
Using your new project
|
|
######################
|
|
|
|
.. code-block:: sh
|
|
|
|
~product$ source product-init-build-env
|
|
|
|
Creating your product layers
|
|
############################
|
|
|
|
You can create a new layer and add it to your active bblayers.conf file like
|
|
this:
|
|
|
|
.. code-block:: sh
|
|
|
|
~product/build$ bitbake-layers create-layer ../layers/meta-belden-bsp
|
|
~product/build$ bitbake-layers add-layer ../layers/meta-product
|
|
|
|
Don't forget to update your templates `projects/templates/bblayers.conf.sample`
|
|
file. Inside this file use `##PRODUCT_LAYERSDIR##/meta-product` to have a
|
|
machine agnostic path.
|
|
|
|
Optional: Change some git settings
|
|
##################################
|
|
|
|
If you want to always `--recurse-submodules` when using `git pull`, you can
|
|
change your `submodule.recurse` git setting, either locally or globally
|
|
|
|
.. code-block:: sh
|
|
|
|
~/product$ git config submodule.recurse true # Only inside of product repo
|
|
~/product$ git config --global submodule.recurse true # Set it for all repos
|
|
|
|
|
|
Create your own distro based on CoreOS
|
|
######################################
|
|
|
|
Create a new file inside configuration file inside
|
|
`product/layers/meta-product/conf/distro`. For a distro named `product`, you will create
|
|
`product/layers/meta-product/conf/distro/product.conf`.
|
|
|
|
Open this file and enter the following:
|
|
|
|
.. code-block:: ini
|
|
|
|
# This should come at the beginning of the file, to ensure that you use
|
|
# CoreOS defaults
|
|
require conf/distro/belden-coreos.conf
|
|
|
|
# This should always be set in your own configuration file, to not use the
|
|
# values of CoreOS
|
|
DISTRO = "product"
|
|
DISTRO_NAME = "Product Linux Distribution"
|
|
MAINTAINER = "Belden Product Team"
|
|
|
|
# You may want to add a version and a codename to your distro instead of
|
|
# using the version and codename of CoreOS
|
|
DISTRO_VERSION = "2022.05"
|
|
DISTRO_CODENAME = "ProductOS Summer 2022 Edition"
|
|
|
|
# Here you can override settings from the CoreOS distro or from
|
|
# OpenEmbedded-core. But keep in mind that the CoreOS team doesn't support
|
|
# all the features of OpenEmbedded-Core. We have added some checks for some
|
|
# of the settings that we don't allow to change or that we don't support.
|
|
# See the coreos-sanity.bbclass file for more info.
|
|
|
|
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 environment for the first time.
|
|
|
|
What to do next
|
|
###############
|
|
|
|
How do I...
|
|
############
|
|
|
|
...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`:
|
|
|
|
.. code-block:: ini
|
|
|
|
# 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?
|
|
*********************************************************************************************************************************************
|
|
|
|
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.
|
|
|
|
... start fast and easy development
|
|
***********************************
|
|
|
|
By adding `debug-tweaks` to `EXTRA_IMAGE_FEATURES` the image is made suitable
|
|
for development. This allows for example root login with no password.
|
|
For a complete list of the functionality that is added or removed by using
|
|
`debug-tweaks` have a look at the official documentation.
|
|
|
|
Following CoreOS specific functionality was added to `debug-tweaks`:
|
|
|
|
* disables the read-only filesystem.
|
|
|
|
.. warning::
|
|
|
|
This is for development only and must not be used for production images.
|
|
|
|
... 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
|
|
################################
|
|
|
|
It's also possible but not recommended to clone CoreOS without any submodule, to
|
|
create a more flat structure. But then you have to ensure and manage the
|
|
Bitbake et OpenEmbedded-Core version by yourself.
|
|
|
|
.. important::
|
|
|
|
CoreOS is only tested with the version of Bitbake and OpenEmbedded-Core used
|
|
in the CoreOS repository as submodule. By doing this you have to ensure that
|
|
you project stay in sync with CoreOS regarding CoreOS version and
|
|
corresponding Bitbake and OpenEmbedded-Core version.
|
|
|
|
|
|
.. code-block::
|
|
|
|
product/
|
|
├── build/ (ignored by git)
|
|
├── bitbake/ (submodule)
|
|
├── documentation/
|
|
├── layers/
|
|
| ├── openembedded-core (submodule)
|
|
| └── coreos/ (cloned without submodule)
|
|
| | ├── layers/
|
|
| | | ├── meta-belden-coreos
|
|
| | | ├── meta-belden-coreos-bsp
|
|
| | | └── ...
|
|
| | └── ...
|
|
| ├── meta-product/
|
|
| ├── meta-other-layers/
|
|
| └── ...
|
|
├── scripts/
|
|
├── templates/
|
|
├── product-init-build-env
|
|
├── .gitignore
|
|
|
|
Setting this structure is out of the scope for this documentation, but as a
|
|
hint, to implement it you have to set in `product-init-build-env`:
|
|
|
|
- `BITBAKEDIR` to the path of the Bitbake repository
|
|
- `OEROOT` to the path of the OpenEmbedded-Core repository
|
|
|
|
.. important::
|
|
|
|
Calling directly oe-init-build-env from OpenEmbedded-Core is not supported!
|
|
Ensure that your product-init-build-env call coreos-init-build-env egal if
|
|
you use the recommended or alternative repository structures.
|