Reference manual¶

This is the reference manual of meta-welma.

Classes¶

`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."

`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 = "allow-empty-password"
```

`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

`welma-license-digest`¶

This image-level 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"

`image-split`¶

This image-level 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.

It works together with the partition mapping that maps filesystems onto physical partitions. This description is given by IMAGE_PART_FILE.

Please refer to the Partitioning page for details about configuration and options.

`systemd-user`¶

This package-level class 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)"

Yocto 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.

WELMA_DATA_STORE
If WELMA_DATA_STORE = "1", then data provisioning storage is activated. See Data povisioning.

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.

WELMA_UPDATE_BUNDLE
Selects which packages should be put together in a single bundle. Must be a subset of WELMA_UPDATE_MODULES. By default all A/B modules are selected.

WELMA_UPDATE_BUNDLE_NAME
This gives the name of the generated bundle. For example, WELMA_UPDATE_BUNDLE_NAME = "bundle" will result in this file being built: tmp/deploy/images/${MACHINE}/${IMAGE_NAME}.bundle.{swu,mender}

WELMA_UPDATE_MODULES
Contains the list of modules that map to partitions and are subject to single or A/B update. This variable is automatically set after the .part configuration file (see Partitioning). Each module listed here leads to the build of a package.

Embedded Files¶

/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. See page Software Update.

/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, ...).

Reference manual¶

Classes¶

welma-image¶

welma-image-devel¶

welma-image-debug¶

welma-license-digest¶

image-split¶

systemd-user¶

Yocto variables¶

Embedded Files¶

Packages and Package Groups¶

`welma-image`¶

`welma-image-devel`¶

`welma-image-debug`¶

`welma-license-digest`¶

`image-split`¶

`systemd-user`¶