Skip to content

Latest commit

 

History

History
211 lines (158 loc) · 13.9 KB

aktualizr-config-options.adoc

File metadata and controls

211 lines (158 loc) · 13.9 KB
Raw

Client configuration options

Note

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

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:

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.

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.