Skip to content

Configuration Classes

The tolomeo_* classes define the TLM_ variables, the parse-time required-variable check, the install helpers and the image accounts an integration overrides.

Classes

Class Inherits Provides
tolomeo_base — Filesystem-layout variables and the required-variable check
tolomeo_ota tolomeo_base OTA/update path variables and the anti-rollback policy
tolomeo_lib — do_install helper functions
tolomeo_config tolomeo_ota, tolomeo_lib Umbrella front-end for the whole interface (tolomeo_base transitively)
tolomeo_users extrausers Image account table and the EXTRA_USERS_PARAMS it generates

A recipe inherits the narrowest class it needs; a downstream layer inherits tolomeo_config for the whole interface. The TLM_ variables are weak (?=) except where a table says otherwise.

Filesystem-Layout Variables

Defined by tolomeo_base.

Variable Default Set in Description
TLM_DATA_DIR /data machine conf / distro conf Persistent writable mount point
TLM_CERTS_DIR /certs machine conf / distro conf Device certificate mount point
TLM_APP_DIR /app machine conf / distro conf / local.conf Application partition mount point
TLM_SHARED_DIR /shared machine conf / distro conf / local.conf Shared data mount point
TLM_CONFIGDIR ${sysconfdir}/tolomeo machine conf / distro conf / local.conf ToloMEO configuration directory (/etc/tolomeo)
TLM_CERTS_MOUNT_OPTIONS defaults machine conf / distro conf / local.conf Mount options for the certificate partition
TLM_APP_MOUNT_OPTIONS defaults machine conf / distro conf / local.conf Mount options for the application partition

The storage profiles tolomeo-mmc-storage.inc and tolomeo-mtd-storage.inc hard-assign TLM_DATA_DIR and TLM_CERTS_DIR (and TLM_CERTS_FSTYPE, plus TLM_CERTS_DEVICE in the eMMC profile). local.conf is parsed before the machine configuration, so it cannot override them on a machine that requires a profile.

The matching device and filesystem variables (TLM_CERTS_DEVICE, TLM_CERTS_FSTYPE, TLM_APP_DEVICE, TLM_APP_FSTYPE, and the TLM_SHARED_* pair) have no class default — the machine configuration supplies them. See Machine Configuration.

OTA Variables

Defined by tolomeo_ota. The SWUpdate bbappend, the tlm-swupdate service and its .toml, and the ota-monitor service read these values, including the anti-rollback policy. Override TLM_OTA_DIR and TLM_OTA_FILENAME to move the coupled paths together rather than setting TLM_OTA_FILE directly.

Variable Default Set in Description
TLM_OTA_DIR ${TLM_DATA_DIR}/tolomeo machine conf / distro conf / local.conf Directory the OTA package and state are written to
TLM_OTA_FILENAME ota.pkg machine conf / distro conf / local.conf Name the downloaded package is saved under
TLM_OTA_FILE derived — Full path SWUpdate installs from: ${TLM_OTA_DIR}/${TLM_OTA_FILENAME}
TLM_OTA_CHECKPOINT ${TLM_OTA_DIR}/ota-service.yml machine conf / distro conf / local.conf OTA state snapshot, so an interrupted update survives a restart
TLM_OTA_DESCRIPTOR ${sysconfdir}/swupdate/conf.d/descriptor.env machine conf / distro conf / local.conf Descriptor file the ToloMEO Edge agent writes and the OTA monitor watches
TLM_OTA_ALLOW_SAME_VERSION 0 distro conf / local.conf 1 makes tlm-swupdate and the SWUpdate launchers accept an update at the running version
TLM_OTA_ALLOW_DOWNGRADE 0 distro conf / local.conf 1 makes tlm-swupdate and the SWUpdate launchers accept an update older than the running version
TLM_OTA_ALLOW_SAME_VERSION_FLAG derived read-only 1 or 0 form of TLM_OTA_ALLOW_SAME_VERSION, for shell scripts
TLM_OTA_ALLOW_SAME_VERSION_BOOL derived read-only true or false form of TLM_OTA_ALLOW_SAME_VERSION, for the .toml
TLM_OTA_ALLOW_DOWNGRADE_FLAG derived read-only 1 or 0 form of TLM_OTA_ALLOW_DOWNGRADE, for shell scripts
TLM_OTA_ALLOW_DOWNGRADE_BOOL derived read-only true or false form of TLM_OTA_ALLOW_DOWNGRADE, for the .toml

Account Variables

Defined by tolomeo_users, an image class. tolomeo-image-prod.inc inherits it and sets TLM_USERS ?= "root admin"; any other image recipe can inherit tolomeo_users.

Variable Default Set in Description
TLM_USERS root image recipe / local.conf Space-separated accounts in the image
TLM_USERS[<account>] admin,/bin/bash, for admin image recipe / local.conf "<primary-group>,<shell>,<extra-groups>"; extra groups :-separated, shell defaults to /bin/sh; root takes none
TLM_USER_PASSWORD[<account>] — image recipe / local.conf crypt(3) hash for the account
SYS_USER_PASSWORD_<ACCOUNT> — kas env: crypt(3) hash; <ACCOUNT> is the account name upper-cased, - replaced by _
TLM_DEVEL_PASSWORD placeholder hash distro conf / local.conf root fallback; matches no password
DISABLE_ROOT 0 image recipe / local.conf 1 locks root, listed or not

Hashes are accepted raw or escaped with printf "%q".

Password Resolution

For each account the class takes the first non-empty value of:

  1. TLM_USER_PASSWORD[<account>]
  2. SYS_USER_PASSWORD_<ACCOUNT>
  3. TLM_DEVEL_PASSWORD — root only

Generated Commands

The class prepends its commands to EXTRA_USERS_PARAMS, so commands the image adds itself are kept and run after them. Per account it emits groupadd -f for each group, then useradd and usermod -p; for root, only usermod -p, or usermod -L when DISABLE_ROOT = "1".

The do_rootfs signature covers a digest of the generated value, so changing an account or rotating a password rebuilds the rootfs, and no hash is written to the signature files.

Validation

Parsing never fails on account errors: an invalid account is left out of the parse-time value. The tlm_users_check prefunc of do_rootfs repeats the generation strictly and stops the build on the first error:

Error Cause
no password for enabled account '<account>' No value found in the resolution order
password for account '<account>' is not a crypt(3) hash The value does not start with $ or has characters outside [A-Za-z0-9./=$]
account '<account>' is in TLM_USERS but has no TLM_USERS[<account>] definition tuple Non-root account without a tuple
account '<account>' has a malformed TLM_USERS[<account>] tuple More than three fields
invalid account name / invalid group name / invalid shell Name not matching [a-z_][a-z0-9_-]*, or shell not an absolute path
accounts '<a>' and '<b>' both resolve to SYS_USER_PASSWORD_<ACCOUNT> Two names differing only in - and _

Required-Variable Validation

tolomeo_base validates that the variables named in REQUIRED_VARS are non-empty. The check runs once at parse time on the bb.event.RecipeParsed event — not in do_configure — so a misconfiguration fails before any fetch or build work.

Variable Default Set in Description
REQUIRED_VARS "" recipe Space-separated variable names that must be non-empty at parse time

A recipe sets REQUIRED_VARS to the machine-supplied variables it depends on, for example:

inherit tolomeo_base
REQUIRED_VARS = "TLM_CERTS_DEVICE TLM_CERTS_FSTYPE"

When a listed variable is empty, parsing stops with:

<recipe>: required variable(s) not set: TLM_CERTS_DEVICE

Install Helpers

Defined by tolomeo_lib. Inherit the class and call the helpers from do_install.

Helper Does Mode
install_systemd_units <srcdir> <destdir> Installs *.service and *.path at the top of srcdir 0644
install_scripts <srcdir> <destdir> Installs *.sh at the top of srcdir 0755
install_configs <srcdir> <destdir> <file>... Installs the explicitly named files from srcdir 0644
expand_vars <file> KEY=VALUE... Replaces each @KEY@ placeholder in file with its value —

The three install_* helpers create destdir. install_systemd_units and install_scripts warn and return without error when srcdir does not exist; install_configs warns per missing file and continues. expand_vars takes KEY=VALUE pairs and is for build-time, trusted values only.

inherit tolomeo_lib

do_install() {
    install_systemd_units "${S}/systemd" "${D}${systemd_system_unitdir}"
    install_scripts       "${S}/scripts" "${D}${bindir}"
    install_configs       "${WORKDIR}"   "${D}${TLM_CONFIGDIR}" app.toml
    expand_vars           "${D}${TLM_CONFIGDIR}/app.toml" "TLM_CERTS_DIR=${TLM_CERTS_DIR}"
}

Build-Kind Distro Features

A distro declares its build kind with one of two features in its DISTRO_FEATURES. tolomeo-prod adds tlm-production and tolomeo-devel adds tlm-development.

Feature Effect
tlm-production /etc/issue shows the production banner; the ota-monitor recipe warns at parse time when TLM_OTA_ALLOW_DOWNGRADE is 1
tlm-development /etc/issue shows the development banner

A distro that declares neither feature gets the restricted-system banner.

See also