Skip to content

meta-welma Reference Manual

Images classes

Image class welma-image

This is the main class for Welma images, to be used for production images.

Here are the image features available for images that inherit welma-image:

  • default-shell-dash / default-shell-bash: Enables selecting the default shell (/bin/sh). By default default-shell-dash is selected by welma-image. Selecting default-shell-bash takes precedence and replaces the default shell with bash.

  • secure-storage: Adds packages for using secure storage. This needs some specific machine support. See page Secure storage.

  • development: Adds interactive programs and SSH access, typically used by developers (bash, less, vi, ...).

  • automatic-testing: Adds SSH access by key. (It is recommended to also activate the image feature ssh-server-openssh to actually use the keys)

The image features can be controlled by the variables IMAGE_FEATURES and EXTRA_IMAGE_FEATURES that you typically configure in your image recipes.

The following image features are selected by default: read-only-rootfs, default-shell-dash

The following variables can be customized in your image recipe:

  • WELMA_ROOT_PASSWD: Defines a password for root in an image recipe. Default value: * (ie: the user cannot log in).

  • WELMA_USER_PASSWD: Defines a password for user in an image recipe. Default value: * (ie: the user cannot log in).

  • WELMA_USER_NAME: Defines the name of the unprivileged user. Default value: user. Be sure to have it aligned with files/passwd if using useradd-staticids

  • WELMA_USER_GROUPS: Defines to which groups user shall belong.

Example:

inherit welma-image

# Blank test password:
#     printf "%q" $(mkpasswd -m sha256crypt '' SALT0000)
WELMA_ROOT_PASSWD = "\$5\$SALT0000\$Zi7.Rm.pCHZCGmah/kOZA4xKNPVyZDjIP4hRpJSkxQ."

Image class image-split

This class splits your image into smaller filesystems.

During the do_image task, rootfs is split into smaller filesystems, according to the description given by IMAGE_SPLIT_FILE (default welma.split).

meta-welma/split/welma.split
split   boot    /boot   vfat    overhead=1.1,minsize=4096
split   sysro   /       ext4    overhead=1.1
split   appro   /app    ext4    overhead=1.1,extrasize=4096
split   sysrw   /var    ext4    overhead=1.3,extrasize=390000

migrate /home   /var/home   bind

You may override this files by placing your copy in the split directory of your Yocto layer.

Warning

In version 1.1.0, only the 5th column of this file may be modified as the feature is not completely generic and some parts are still hard-coded in meta-welma (boot/vfat, sysro/ext4, ...).

Image class initramfs-minimal

This class is a minimal basis for building an initramfs image.

Image class welma-image-devel

This class is intended to be used in images for developers (and not for production images).

Default image features selected when inheriting this class: development, ssh-server-openssh

welma-image-devel, also adds the following:

  • Blank passwords for root and user (see WELMA_ROOT_PASSWD and WELMA_USER_PASSWD)
  • You may define EXTRA_IMAGE_FEATURES_DEV to select features that you want for developers but not for the production image.

Eg: 

EXTRA_IMAGE_FEATURES_DEV = "debug-tweaks"

Image class welma-image-debug

This class is for developers and adds debugging tools such as:

  • gdbserver,
  • TCF daemon (Target Communication Framework for the Eclipse IDE), ...

Default image features selected when inheriting this class: development, ssh-server-openssh

Image class welma-uefi-comboapp

This class is used for UEFI-Based machines only, it is based on meta-intel's uefi-comboapp class, and is used to inject the SWK certificate into the initial ramdisk before packing the comboapp file.

Other Image Classes

welma-image-mender
Generates .mender modules if IMAGE_FSTYPES contains mender.
Inherited by welma-image when WELMA_UPDATE is mender or mender-connected.

welma-image-swu
Generates .swu modules if IMAGE_FSTYPES contains swu.
Inherited by welma-image when WELMA_UPDATE is swupdate.

welma-image-update
Redirects to welma-image-swu of welma-image-mender depending on WELMA_UPDATE.

welma-verity
Generates images for filesystems under dm-verity control.

welma-image-ptest
Generates an image with ptest.

Other classes

Class fitimage

This bbclass is used to generate a U-Boot-compatible FIT image.

It is inspired from kernel-fitimage.bbclass but useable outside kernel recipes.

Usage: 

fitimage_assemble ...
Arguments: 
    FITIMAGE-ITS  Output fitimage.its
    FITIMAGE      Output fitimage
    KERNEL        Input kernel image
    UBOOT-SCRIPT  Input u-boot script
    SETUP         Input setup file (x86)
    INITRAMFS     Input initramfs image
Input variables: 
    KERNEL_DEVICETREE      List of dtb to be integrated (possibly overlays),
                           searched in DEPLOY_DIR_IMAGE.
    UBOOT_ARCH
    UBOOT_DTB_LOADADDRESS
    UBOOT_DTBO_LOADADDRESS
    UBOOT_ENTRYPOINT
    UBOOT_ENTRYSYMBOL
    UBOOT_LOADADDRESS
    UBOOT_RD_ENTRYPOINT
    UBOOT_RD_LOADADDRESS
Prerequisites:

  • Have a uboot-compatible kernel deployed (inherit kernel-uboot-deploy from your kernel recipe) and a companion .comp file that indicates the compression scheme:
    • KERNEL
    • KERNEL.comp

Class kernel-uboot-deploy

This bbclass is used to deploy a FIT-compatible kernel image.

The deployed files are:

  • u-boot/linux.bin: the Linux kernel in a FIT-compatible format
  • u-boot/linux.bin.comp: the compression algorithm used (none, gzip, ...)

Usage:

  • Have your kernel recipe inherit this bbclass
  • In your FIT image recipe, use ${DEPLOY_DIR_IMAGE}/u-boot/linux.bin{.comp}

Class systemd-user

systemd-user.bbclass is used for installing and enabling systemd user units, similarly to what systemd.bbclass does for systemd system units.

The files that enable the units are created in /app/user/<uid>/systemd/user (SYSTEMD_UNIT_PATH is set accordingly in Welma).

Usage:

SYSTEMD_USER_PACKAGES = "${PN} ..."
Packages that have systemd user units.

SYSTEMD_USER_AUTO_ENABLE = "enable"
Or any other value to disable.

SYSTEMD_USER_SERVICE:${PN} = "unit ..."
Units to take into account in a given package.

SYSTEMD_USERS = "username ..."
Users for which the units shall be enabled. Note that the recipe must also add these users via inherit useradd, USERADD_PACKAGES, USERADD_PARAM.

Example: 

inherit systemd-user
SYSTEMD_USER_PACKAGES = "${PN}"
SYSTEMD_USER_SERVICE:${PN} = "unit1.service"
SYSTEMD_USER_AUTO_ENABLE = "enable"
SYSTEMD_USERS = "user1"

  • unit1.service has WantedBy=default.target.
  • unit1.service has RequiredBy=other.service.
  • user1 had user id 2001.

This creates the symbolic links: 

/app/user/2001/systemd/user/default.target.wants/unit1.service -> ${systemd_user_unitdir}/unit1.service
/app/user/2001/systemd/user/other.service.requires/unit1.service -> ${systemd_user_unitdir}/unit1.service

Example of resulting runtime status (with unit1 being cinematicexperience): 

$ systemctl --user status 
   ...
   CGroup: /user.slice/user-2000.slice/user@2000.service
           |-app.slice
           | `-cinematicexperience.service
           |   `- 1075 /usr/share/cinematicexperience-1.0/Qt5_CinematicExperience -platform wayland
           `-init.scope
             |- 1069 /lib/systemd/systemd --user
             `- 1070 "(sd-pam)"

Class welma-license-digest

This class enables generating a HTML report on embedded software, with versions and licenses.

The following variables may be defined:

  • WELMA_LIC_DIGEST_IMAGES: Defines which image(s) should be considered for the report. The report on these will have a per-package granularity. The image names must be separated by spaces.

  • WELMA_LIC_DIGEST_BOOT: Defines which other recipe(s) should be considered. you typically set here parts that are not packages of an image (typically boot files). The recipe names must be separated by spaces.

After bitbaking the recipe, the generated report is generated in: ${DEPLOY_DIR}/images/${MACHINE}/${PN}-${MACHINE}.html

Example:

license-digest.bb
inherit welma-license-digest

WELMA_LIC_DIGEST_IMAGES = "welma-image-minimal"
WELMA_LIC_DIGEST_BOOT = "u-boot"

Global Variables

These are the variables that can be used globally (defined in .conf files).

BOOT_SIGNING_MECHANISM
This selects the boot signing mechanism, and is highly dependant on the machine. Available values: imx.

DISTRO
Welma supplies the following distributions: welma, welma-wayland, welma-x11, for usage headless, graphical with Wayland or X11.

MENDER_SERVER_URL
Mender variable.
Applicable if WELMA_UPDATE is mender or mender-connected.
Eg: MENDER_SERVER_URL = "https://example.com:443"

MENDER_TENANT_TOKEN
Mender variable.
Applicable if WELMA_UPDATE is mender or mender-connected.

PARTITION_SIZE_APPRO
PARTITION_SIZE_BOOT
PARTITION_SIZE_SYSRO
PARTITION_SIZE_SYSRW
(scarthgap only) These variables set the size of partitions. They are used in the WKS (wic) description file. They take an integer value optionally followed by one of the units: "k" for kibibyte, "M" for mebibyte and "G" for gibibyte (defaults to "M" if none specified).

Eg: PARTITION_SIZE_SYSRO = "350M"

WELMA_GIT_NAMESPACE
WELMA_GIT_URI_BASE
WELMA_GIT_PROTOCOL
These variables may be modified to match where Welma specific components are hosted.

WELMA_KEY_SWK1_PUB
Path to the SWK1 public key, as a X509 certificate (PEM). On Arm machines, it is injected in U-Boot.
Applicable and mandatory if WELMA_SECURE_BOOT is 1.

WELMA_KEY_SWK1_PRIV
Path to the SWK1 private key (PEM).
Applicable and mandatory if WELMA_SECURE_BOOT is 1.

WELMA_KEY_SWK2_PUB
Path to the SWK2 public key, as a X509 certificate (PEM).
If defined, it is injected in the ramdisk (in the kernel FIT image).

WELMA_KEY_SWK2_PRIV
Path to the SWK2 private key (PEM).

WELMA_SECURE_BOOT
If WELMA_SECURE_BOOT = "1", then secure boot is activated. This activates the authentication of the bootloader (when supported by the machine), BOOT, SYSRO and APPRO.

WELMA_SECURE_UPDATE
If WELMA_SECURE_BOOT = "1", then secure update is activated: during the software update procedure, modules will be authenticated before being installed. This requires that at least one of SWK1 or SWK2 is set (see related variables).

WELMA_UPDATE
Selects the underlying software update mechanism. Possible values: swupdate, mender, mender-connected
Default: swupdate
You need to add the Swupdate or Mender layer accordingly in your bblayer.conf.

Embedded Files

/app
Is a directory dedicated to application programs. By default it is the mountpoint of the APPRO module.

/etc/hwrevision
Defines the swupdate hardware revision.
Applicable if WELMA_UPDATE is swupdate.

/etc/machine-id
Defines a machine identifier with a hard-coded value. This should be modified to have different identifiers on real products.

/etc/mender/mender.conf
Is the read-only part of Mender configuration.
Applicable if WELMA_UPDATE is mender or mender-connected.

/etc/os-release
Contains the definition of the firmware type used by the system in the FIRMWARE_TYPE variable.
This variable is set to UEFI for UEFI-Based machines.

/etc/swupdate.cfg
Is the swupdate configuration.
Applicable if WELMA_UPDATE is swupdate.

/etc/updated.conf
Is the updated daemon configuration.

/etc/welma-partitions.conf
Defines how the filesystems are mapped on the partitions.

/data
Is a directory needed by Mender. By default it is a bind mountpoint of /var/data.
Applicable if WELMA_UPDATE is mender or mender-connected.

/run/swk/swk.pub
Defines the public key that shall be used for authenticating dm-verity partitions (when WELMA_SECURE_BOOT = 1) and software update modules (when WELMA_SECURE_UPDATE = 1). It points to swk2.pub or swk1.pub. If both are provisioned, SWK2 takes precedence. (See also WELMA_KEY_SWK1_PUB and WELMA_KEY_SWK2_PUB)

/var
Is a mountpoint for SYSRW.

/var/lib/mender/device_type
Defines the type of the device. By default the type is ${MACHINE}.
Applicable if WELMA_UPDATE is mender or mender-connected.

/var/lib/mender/mender.conf
Is the read-write part of Mender configuration.
Applicable if WELMA_UPDATE is mender or mender-connected.

/var/lib/mender/mender-agent.pem
Is the private key used by the mender-client daemon.
Applicable if WELMA_UPDATE is mender-connected.

/var/lib/tee
Is the directory for OP-TEE secure storage.
Applicable if secure-storage is used.

Packages and Package Groups

  • coreutils-essential: Adds a minimal subset of programs of coreutils.
  • packagegroup-welma-essential: Adds programs to work on files and filesystems.
  • packagegroup-welma-interactive: Adds packages for developers to interact with the target system.
  • packagegroup-welma-keystore-optee: Add packages for using OP-TEE secure storage and PKCS11 trusted app.
  • packagegroup-welma-tracing: Adds packages for developers to trace the target system (strace, tcpdump, ...).

Recipes

recipes-bsp/welma-verity-packer-native/welma-verity-packer-native_1.0.0.bb
Installs build-welma-verity-device in recipe-sysroot.

recipes-bsp/welma-signing-tools-native/welma-signing-tools-native_git.bb
Installs signing tools in recipe-sysroot. These tools are used for secure boot and secure update.

recipes-core/network-config/network-config.bb
Installs minimal network configuration.

recipes-core/shell-profile-conf/shell-profile-conf_1.0.bb
Installs login shell profile and configuration.

recipes-core/ssh-authorized-keys/ssh-authorized-keys_1.0.bb
Installs a public key in ${ROOT_HOME}/.ssh/authorized_keys.

recipes-core/systemd/systemd-user-welmaconf.bb
Configures the systemd user manager with a specific SYSTEMD_UNIT_PATH:

  • add /app/lib/systemd/user:/app/user/%i/systemd/user
  • remove /home

recipes-core/systemd/systemd-welma-conf.bb
Installs default Welma configuration files.

recipes-core/welma-partitions/welma-partitions.bb
Installs /etc/welma-partitions.conf.

recipes-graphics/qt-eglfs-conf/qt-eglfs-conf_1.0.bb
Installs eglfs environment for some machines.

recipes-support/bootflags/bootflags_1.1.bb
Installs the bootflags program for controlling the bootflags.

recipes-support/bootflags/bootflags-uboot-source.bb
Provides the bootflags source code for U-Boot.

recipes-support/keys-mender/keys-mender.bb
Installs a private key for the mender-client daemon.
By default a test key is provided: WELMA_KEY_MENDER_PRIVATE = "keys/key-mender-test".

recipes-support/libconfig-tool/libconfig-tool.bb
Installs a simple program for parsing sw-description format.

recipes-support/update/*.bb
Install Welma update programs.

recipes-support/update-tools/swu.bb
Provides a -native tool for creating, reading, signing SWU files.

recipes-welma/fitimage/welma-fitimage.bb
Installs the FIT image in /boot.

recipes-welma/images/welma-image-minimal.bb
recipes-welma/images/welma-image-minimal-dbg.bb
recipes-welma/images/welma-image-minimal-dev.bb
Defines Welma reference images (production, debug, development).

recipes-welma/initramfs/welma-image-initramfs.bb
Defines the initramfs image.

Bbappends

dynamic-layers/mender/recipes-mender/mender-client/mender-client_%.bbappend
This bbappend configures mender for Welma.
Applicable if WELMA_UPDATE is mender or mender-connected.

dynamic-layers/swupdate/recipes-support/swupdate/swupdate_*.bbappend
This bbappend configures swupdate for Welma. In particular: /etc/swupdate.cfg, /etc/hwrevision.
Applicable if WELMA_UPDATE is swupdate.

recipes-core/base-files/base-files_%.bbappend
This bbappend modifies the base fstab file to add mounts determined by WELMA_PARTITIONS.

recipes-core/coreutils/coreutils_%.bbappend
This bbappend splits into a smaller coreutils-essential package that contains the /bin/* subset of coreutils commands.

recipes-core/initrdscripts/initramfs-boot_%.bbappend
This bbappend provides a custom init-boot.sh script.

recipes-core/systemd/systemd-conf_%.bbappend
This bbappend prevents the installation of the default dhcp-ethernet network configuration. The Welma network configuration is provided by the recipe and package network-config.