aktualizr-config-options.adoc

Client configuration options

Note	We recommend that you view this article in our documentation portal. Not all of our articles render correctly in GitHub.

partial$aktualizr-version.adoc

Here, we provide reference documentation on aktualizr’s usage and configuration. However, if you need to go further than what’s possible with the command-line interface, you can also use libaktualizr to make your own client. In fact, aktualizr is a fairly thin wrapper around libaktualizr itself, and we provide also an even simpler example client along with doxygen docs of the libaktualizr API.

How .toml files are processed

Aktualizr is configured via .toml config files. One or more files or directories can be passed to the application via the --config flag (one per file or directory).

• If --config is not specified on the command line, aktualizr searches the following directories for files with a .toml extension:

  • /usr/lib/sota/conf.d

  • /etc/sota/conf.d/

Aktualizr searches for and processes these config files in systemd style using the following rules:

• If multiple files are found with the same name, the last detected file overrules and hides the others.

• Files are then processed in alphabetical order with the following conditions:

  • If a config option is specified in multiple files, the last entry overrules the previous entries.

  • But if a config option is specified in the first file but unspecified in the last file, the last entry does not overrule the previous entry.

For examples of configuration files, see the following resources:

• Config files used by unit tests

• Config files used by continuous integration tests

• Configuration fragments used in meta-updater recipes.

All fields are optional, and most have reasonable defaults that should be used unless you have a particular need to do otherwise.

Some options can also be set on the command line. The command line input always takes precedence over the config files. See the aktualizr source (or run aktualizr --help) for the available command line options.

Configuration options

logger

Configuration for the logger.

Name	Default	Description
loglevel	2	Log level, 0-5 (trace, debug, info, warning, error, fatal).

p11

Options for using a PKCS#11 compliant device for storing cryptographic keys.

Note	The key ID options require the corresponding options in the tls or uptane section to be set to pkcs11.

Name	Default	Description
module		Path to the shared object HSM driver.
pass		Password for accessing the HSM.
uptane_key_id		Key ID of the Uptane key in the HSM.
tls_cacert_id		Key ID of the TLS root CA certificate for authenticating the server.
tls_pkey_id		Key ID of the client’s TLS private key.
tls_clientcert_id		Key ID of the client’s TLS certificate.

tls

Configuration for client-server TLS connections.

Name	Default	Description
server		Server URL.
server_url_path		Path to a file that contains the server URL.
ca_source	"file"	Where to read the TLS root CA certificate from. Options: "file", "pkcs11".
pkey_source	"file"	Where to read the client’s TLS private key from. Options: "file", "pkcs11".
cert_source	"file"	Where to read the client’s TLS certificate from. Options: "file", "pkcs11".

Note that server_url_path is only used if server is empty. If both are empty, the server URL will be read from provision.provisioning_path if it is set and contains a file named autoprov.url.

provision

Options for how the device is provisioned with the backend.

Name	Default	Description
server		Server provisioning URL. If empty, set to tls.server.
p12_password		Password for PKCS#12 encryption.
expiry_days	"36000"	Provided in the ttl field of the device provisioning request sent to the server.
provision_path		Path to an archive containing provisioning data. See the reference documentation for the specification of the contents of this file.
device_id		Device ID of the Primary ECU. If left empty, a random name will be generated.
primary_ecu_serial		Serial number of the Primary ECU. If left empty, a random serial will be generated.
primary_ecu_hardware_id		The hardware ID of the Primary ECU (e.g., "raspberry-pi"). If left empty, the hostname of the device will be used.
ecu_registration_endpoint		ECU registration URL. If empty, set to uptane.director_server with /ecus appended.
mode	"SharedCred"	See the provisioning documentation for more details. Options: "DeviceCred", "SharedCred", "SharedCredReuse". The last is intended solely for testing purposes.

If you intend to provision with a server by using meta-updater, you will probably want to set provision.provision_path = "/var/sota/sota_provisioning_credentials.zip".

uptane

Options for Uptane.

Name	Default	Description
polling_sec	10	Interval between polls (in seconds).
director_server		Director server URL. If empty, set to tls.server with /director appended.
repo_server		Image repository server URL. If empty, set to tls.server with /repo appended.
key_source	"file"	Where to read the device’s private key from. Options: "file", "pkcs11".
key_type	"RSA2048"	Type of cryptographic keys to use. Options: "ED25519", "RSA2048", "RSA3072" or "RSA4096".
force_install_completion	false	Forces installation completion. Causes a system reboot when using the OSTree package manager. Emulates a reboot when using the fake package manager.
secondary_config_file	""	Secondary json configuration file. Example here: ../config/secondary/virtualsec.json
secondary_preinstall_wait_sec	600	Time to wait for reachable secondaries before attempting an installation.
update_lock_file	/run/lock/aktualizr-lock	If this file exists, and a flock() lock is held then updates will be disabled.

The default for update_lock_file depends on the setting of the TORIZON build flag. When not building in TORIZON mode update_lock_file defaults to ``.

pacman

Options for package management and update installation. Note that this only coincidentally shares the name with the ArchLinux pacman tool.

Name	Default	Description
type	"ostree"	Which package manager to use. Options: "ostree", "none".
os		OSTree operating system group. Only used with ostree.
sysroot		Path to an OSTree sysroot. Only used with ostree.
ostree_server		OSTree server URL. Only used with ostree. If empty, set to tls.server with /treehub appended.
packages_file	"/usr/package.manifest"	Path to a file for storing package manifest information. Only used with ostree.
images_path	"/var/sota/images"	Directory to store downloaded binary Targets. Only used with none.
fake_need_reboot	false	Simulate a wait-for-reboot with the "none" package manager. Used for testing.

storage

Options for how aktualizr stores data locally.

Name	Default	Description
type	"sqlite"	What type of storage driver to use. Options: "sqlite". The former "filesystem" option is now disabled, existing devices will be migrated (see note below)
path	"/var/sota"	Directory for storage. This should be a directory dedicated to aktualizr data. Aktualizr will attempt to set permissions on this directory, so this option should not be set to anything that is used for another purpose. In particular, do not set it to / or to your home directory, as this may render your system unusable.
sqldb_path	"sql.db"	Relative path to the database file.
uptane_metadata_path	"metadata"	Path to the uptane metadata store, for migration from filesystem.
uptane_private_key_path	"ecukey.der"	Relative path to the Uptane specific private key, for migration from filesystem.
uptane_public_key_path	"ecukey.pub"	Relative path to the Uptane specific public key, for migration from filesystem.
tls_cacert_path	"root.crt"	Relative path to the TLS root CA certificate, for migration from filesystem.
tls_pkey_path	"pkey.pem"	Relative path to the client’s TLS private key, for migration from filesystem.
tls_clientcert_path	"client.pem"	Relative path to the client’s TLS certificate, for migration from filesystem.

The only supported storage option is now sqlite.

Old systems configured with filesystem can be migrated by changing the type field to sqlite and keeping all the other fields as-is. At the next aktualizr run, the migration procedure will then run automatically and move existing data inside the database.

import

Options for importing data from the filesystem into the storage.

Name	Default	Description
base_path	"/var/sota/import"	Path to a common root directory to the subsequent files
uptane_private_key_path		Path to the device’s private key.
uptane_public_key_path		Path to the device’s public key.
tls_cacert_path		Path to the TLS root CA certificate.
tls_pkey_path		Path to the TLS private key.
tls_clientcert_path		Path to the TLS client certificate.

telemetry

Options for configuring how aktualizr communicates with the server.

Name	Default	Description
report_network	true	Enable reporting of device networking information to the server.

bootloader

Options for configuring boot-specific behavior

Name	Default	Description
rollback_mode	"none"	Controls rollback on supported platforms, see rollback.adoc. Options: "none", "uboot_generic", "uboot_masked"
reboot_sentinel_dir	"/var/run/aktualizr-session"	Base directory for reboot detection sentinel. Must reside in a temporary file system.
reboot_sentinel_name	"need_reboot"	Name of the reboot detection sentinel.
reboot_command	"/sbin/reboot"	Command to reboot the system after update completes. Applicable only if uptane::force_install_completion is set to true.