Update Mechanism Reference
Complete technical reference for the meta-tolomeo update mechanism: DISTRO_FEATURES flags,
recipe variables, conf.d files, and runtime variables.
Table of Contents
DISTRO_FEATURES
| Feature |
Meaning |
Requires |
update-ota |
Enables OTA agent-placed file updates. Installs swupdate@.service, the base EnvironmentFile, and 00-source.conf with SWUPDATE_SOURCE=file. |
— |
update-ota-streaming |
Enables the update tool to fetch the artifact directly from a URL. Compiles curl support into the swupdate binary. Sets SWUPDATE_SOURCE=download. |
update-ota |
update-local |
Enables local USB-based updates. Installs swupdate-usb@.service and swupdate-usb.sh. |
— |
update-encrypted |
Compiles AES image and manifest decryption support into the swupdate binary. Does not provision the on-device decryption key — that is a BSP-layer responsibility. |
— |
Features are additive. Any combination is valid. update-ota and update-local are orthogonal.
Rootfs State Per Scenario
| Active features |
/etc/default/swupdate |
conf.d at build time |
conf.d at runtime |
update-ota |
✓ |
00-source.conf + 10-ota-file.conf |
— |
update-ota + update-ota-streaming |
✓ |
00-source.conf |
descriptor.env |
update-local |
✓ |
— |
— |
update-ota + update-local |
✓ |
00-source.conf + 10-ota-file.conf |
— |
update-ota + update-ota-streaming + update-local |
✓ |
00-source.conf |
descriptor.env |
Recipe Variables
| Variable |
Default |
Set in |
Description |
SWUPDATE_UPDATE_FILE |
/data/tolomeo/ota.pkg |
machine conf / bbappend |
Path where the management agent drops the .swu file. Applies only when update-ota is active without update-ota-streaming. |
SWUPDATE_SOURCE |
derived |
read-only |
file when update-ota-streaming is absent; download when present. Derived from DISTRO_FEATURES — cannot be set directly. |
SWUPDATE_PUBLIC_KEY |
— |
kas / machine conf |
Absolute path to the RSA public key used by swupdate for package signature verification. Required when update-ota or update-local is active. |
SWUPDATE_KEYDIR |
${BSPDIR}/keys |
kas / local.conf |
Unified directory for all key material (signing and encryption). |
SWUPDATE_ENC_KEYNAME |
swupdate-enc |
kas / local.conf |
Base name of the AES key file used for artifact encryption, without extension. |
SWUPDATE_AES_FILE |
derived |
read-only |
Full path to the AES key file: ${SWUPDATE_KEYDIR}/${SWUPDATE_ENC_KEYNAME}. Cannot be set directly. |
conf.d Files
Files in /etc/swupdate/conf.d/ are shell-sourced at runtime by swupdate.sh in sorted
filename order.
| Filename |
Installed when |
Token replaced at build |
Installed path |
00-source.conf |
update-ota is active |
@SWUPDATE_SOURCE@ → file or download |
/etc/swupdate/conf.d/00-source.conf |
10-ota-file.conf |
update-ota active AND update-ota-streaming absent |
@SWUPDATE_UPDATE_FILE@ → configured path |
/etc/swupdate/conf.d/10-ota-file.conf |
descriptor.env |
Not installed at build time |
— |
/etc/swupdate/conf.d/descriptor.env (written at runtime by the management agent) |
Runtime Variables
Required in streaming mode
| Variable |
Source |
Description |
URL |
descriptor.env |
Full URL of the .swu artifact to fetch. Required when SWUPDATE_SOURCE=download. |
Optional download tuning
All variables below are unset by default. When not set, swupdate built-in defaults apply.
| Variable |
swupdate flag |
Description |
SWUPDATE_DOWNLOAD_RETRIES |
-r |
Number of retry attempts on download failure |
SWUPDATE_DOWNLOAD_TIMEOUT |
-t |
Per-attempt timeout in seconds |
SWUPDATE_DOWNLOAD_MAX_SPEED |
-n |
Maximum download speed in bytes per second |
SWUPDATE_DOWNLOAD_NO_CHECK_CERT |
--no-check-certificate |
Disable TLS certificate verification (set to any non-empty value to enable) |
SWUPDATE_DOWNLOAD_SSL_KEY |
--ssl-key |
Path to client TLS private key |
SWUPDATE_DOWNLOAD_SSL_CERT |
--ssl-cert |
Path to client TLS certificate |
SWUPDATE_DOWNLOAD_CA_PATH |
--ca-path |
Path to CA certificate bundle |
Optional variables can be set in a conf.d fragment or passed via a systemd service drop-in.
Installed Paths Summary
| Path |
Installed when |
Description |
/etc/default/swupdate |
update-ota or update-local |
systemd EnvironmentFile: sets SWUPDATE_BIN, SWUPDATE_PUBLIC_KEY, SWUPDATE_CONF_DIR_ETC, SWUPDATE_CONF_DIR_LIB |
/etc/swupdate/certs/public.pem |
update-ota or update-local |
RSA public key for update package verification |
/lib/systemd/system/swupdate@.service |
update-ota |
Templated OTA update service |
/lib/systemd/system/swupdate-usb@.service |
update-local |
Templated USB update service |
<libdir>/swupdate/swupdate.sh |
always |
Update orchestration script |
<libdir>/swupdate/swupdate-usb.sh |
update-local |
USB device scan and handoff script |