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:
TLM_USER_PASSWORD[<account>]SYS_USER_PASSWORD_<ACCOUNT>TLM_DEVEL_PASSWORD—rootonly
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:
When a listed variable is empty, parsing stops with:
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
- Configure meta-tolomeo for Your Machine — override the
TLM_interface from your layer - Configuration Interface — why the interface is designed this way
- Machine Configuration — the device and filesystem variables the machine supplies
- Manage User Accounts — add an account and supply its password