<commit_before>= Configuration
:aktualizr-github-url: https://github.com/advancedtelematic/aktualizr/tree/master
ifdef::env-github[]
:aktualizr-github-url: ..
endif::[]

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 `/usr/lib/sota/conf.d` and `/etc/sota/conf.d/` for files with a `.toml` extension. Aktualizr searches for and processes these config files in systemd style, meaning that if multiple files are found with the same name, the last one found overrules and hides the others. Files are then processed in alphabetical order, so if a config option is specified in multiple files, the last entry found overrules the others. If an option is left unspecified in a file processed after another file in which it was specified, it is not overruled.

Example config files used by unit tests, continuous integration tests, and https://github.com/advancedtelematic/meta-updater[meta-updater] recipes can be found in link:{aktualizr-github-url}/config/[], link:{aktualizr-github-url}/tests/config/[], and link:https://github.com/advancedtelematic/meta-updater/tree/rocko/recipes-sota/config/files[].

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 link:{aktualizr-github-url}/src/aktualizr_primary/main.cc[] (or run `aktualizr --help`) for the available command line options.

== `logger`

Configuration for the logger.

[options="header"]
|==========================================================================================
| Name       | Default  | Description
| `loglevel` | `2`      | Log level, 0-5 (trace, debug, info, warning, error, fatal).
|==========================================================================================

== `network`

Config options for networking and secondary device detection by the primary.

[options="header"]
|==========================================================================================
| Name                       | Default                                | Description
| `socket_commands_path`     | `"/tmp/sota-commands.socket"`          | Path to a socket to be used for transmitting commands.
| `socket_events_path`       | `"/tmp/sota-events.socket"`            | Path to a socket to be used for transmitting events.
| `socket_events`            | `"DownloadComplete", "DownloadFailed"` | Events to broadcast to connected sockets.
| `ipdiscovery_host`         | `"127.0.0.1"`                          | Subnetmask for primary to broadcast for secondary discovery.
| `ipdiscovery_port`         | `9031`                                 | Port for primary to broadcast for secondary discovery.
| `ipdiscovery_wait_seconds` | `2`                                   | Seconds to wait for secondaries to respond to discovery broadcast message.
| `ipuptane_port`            | `9030`                                 | Port to listen on for incoming messages

|==========================================================================================

== `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`.

[options="header"]
|==========================================================================================
| 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.

[options="header"]
|==========================================================================================
| 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.

[options="header"]
|==========================================================================================
| Name                        | Default   | Description
| `server`                    |           | Server provisioning URL. If empty, set to `tls.server`.
| `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.
| `provision_path`            |           | Path to an archive containing provisioning data. See link:{aktualizr-github-url}/docs/credentials.adoc[] for the specification of the contents of this file.
| `p12_password`              |           | Password for <PASSWORD>.
| `expiry_days`               | `"36000"` | Provided in the `ttl` field of the device provisioning request sent to the server.
| `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.
| `ecu_registration_endpoint` |           | Ecu provisioning URL. If empty, set to `uptane.director_server` with `/ecus` appended.
|==========================================================================================

If you intend to provision with a server by using https://github.com/advancedtelematic/meta-updater[meta-updater], you will probably want to set `provision.provision_path = "/var/sota/sota_provisioning_credentials.zip"`.

== `uptane`

Options for Uptane.

[options="header"]
|==========================================================================================
| Name                      | Default      | Description
| `running_mode`            | `full`       | Continuously poll the server (`full`), perform a full update cycle once and exit (`once`), only check for updates (`check`), only download updates (`download`) or only install updates (`install`).
| `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"`.
| `legacy_interface`        |              | Path to an executable interface for communicating with legacy secondary ECUs. See link:{aktualizr-github-url}/docs/legacysecondary.adoc[] for more information.
|==========================================================================================

== `discovery`

Config options for how secondary devices are detected by the primary.

[options="header"]
|==========================================================================================
| Name       | Default | Description
| `ipuptane` | `false` | Enable UDP multicast for secondary discovery.
|==========================================================================================

== `pacman`

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

[options="header"]
|==========================================================================================
| Name            | Default                   | Description
| `type`          | `"ostree"`                | Which package manager to use. Options: `"ostree"`, `"debian"`, `"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`.
|==========================================================================================

== `storage`

Options for how Aktualizr stores data locally.

[options="header"]
|==========================================================================================
| Name                      | Default                   | Description
| `type`                    | `"sqlite"`                | What type of storage driver to use. Options: `"sqlite"`. The former `"filesystem"` option is now disabled
| `path`                    | `"/var/sota"`             | Directory for storage. Only used with `filesystem`.
| `uptane_metadata_path`    | `"metadata"`              | Path to the uptane metadata store. Only used with `filesystem`.
| `uptane_private_key_path` | `"ecukey.der"`            | Relative path to the Uptane specific private key. Only used with `filesystem`.
| `uptane_public_key_path`  | `"ecukey.pub"`            | Relative path to the Uptane specific public key. Only used with `filesystem`.
| `tls_cacert_path`         | `"root.crt"`              | Relative path to the TLS root CA certificate. Only used with `filesystem`.
| `tls_pkey_path`           | `"pkey.pem"`              | Relative path to the client's TLS private key. Only used with `filesystem`.
| `tls_clientcert_path`     | `"client.pem"`            | Relative path to the client's TLS certificate. Only used with `filesystem`.
| `sqldb_path`              | `"sql.db"`                | Relative path to the database file. Only used with `sqlite`.
|==========================================================================================

== `import`

Options for importing data from the filesystem into the storage. Most useful if `storage.type` is `sqlite`.

[options="header"]
|==========================================================================================
| Name                      | Default | Description
| `base_path`               |         | Path to a common root directory to the subsequent files<commit_msg>Update doc about fs→sql migration<commit_after>= Configuration
:aktualizr-github-url: https://github.com/advancedtelematic/aktualizr/tree/master
ifdef::env-github[]
:aktualizr-github-url: ..
endif::[]

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 `/usr/lib/sota/conf.d` and `/etc/sota/conf.d/` for files with a `.toml` extension. Aktualizr searches for and processes these config files in systemd style, meaning that if multiple files are found with the same name, the last one found overrules and hides the others. Files are then processed in alphabetical order, so if a config option is specified in multiple files, the last entry found overrules the others. If an option is left unspecified in a file processed after another file in which it was specified, it is not overruled.

Example config files used by unit tests, continuous integration tests, and https://github.com/advancedtelematic/meta-updater[meta-updater] recipes can be found in link:{aktualizr-github-url}/config/[], link:{aktualizr-github-url}/tests/config/[], and link:https://github.com/advancedtelematic/meta-updater/tree/rocko/recipes-sota/config/files[].

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 link:{aktualizr-github-url}/src/aktualizr_primary/main.cc[] (or run `aktualizr --help`) for the available command line options.

== `logger`

Configuration for the logger.

[options="header"]
|==========================================================================================
| Name       | Default  | Description
| `loglevel` | `2`      | Log level, 0-5 (trace, debug, info, warning, error, fatal).
|==========================================================================================

== `network`

Config options for networking and secondary device detection by the primary.

[options="header"]
|==========================================================================================
| Name                       | Default                                | Description
| `socket_commands_path`     | `"/tmp/sota-commands.socket"`          | Path to a socket to be used for transmitting commands.
| `socket_events_path`       | `"/tmp/sota-events.socket"`            | Path to a socket to be used for transmitting events.
| `socket_events`            | `"DownloadComplete", "DownloadFailed"` | Events to broadcast to connected sockets.
| `ipdiscovery_host`         | `"127.0.0.1"`                          | Subnetmask for primary to broadcast for secondary discovery.
| `ipdiscovery_port`         | `9031`                                 | Port for primary to broadcast for secondary discovery.
| `ipdiscovery_wait_seconds` | `2`                                   | Seconds to wait for secondaries to respond to discovery broadcast message.
| `ipuptane_port`            | `9030`                                 | Port to listen on for incoming messages

|==========================================================================================

== `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`.

[options="header"]
|==========================================================================================
| 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.

[options="header"]
|==========================================================================================
| 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.

[options="header"]
|==========================================================================================
| Name                        | Default   | Description
| `server`                    |           | Server provisioning URL. If empty, set to `tls.server`.
| `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.
| `provision_path`            |           | Path to an archive containing provisioning data. See link:{aktualizr-github-url}/docs/credentials.adoc[] for the specification of the contents of this file.
| `<PASSWORD>_password`              |           | Password for <PASSWORD>.
| `expiry_days`               | `"36000"` | Provided in the `ttl` field of the device provisioning request sent to the server.
| `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.
| `ecu_registration_endpoint` |           | Ecu provisioning URL. If empty, set to `uptane.director_server` with `/ecus` appended.
|==========================================================================================

If you intend to provision with a server by using https://github.com/advancedtelematic/meta-updater[meta-updater], you will probably want to set `provision.provision_path = "/var/sota/sota_provisioning_credentials.zip"`.

== `uptane`

Options for Uptane.

[options="header"]
|==========================================================================================
| Name                      | Default      | Description
| `running_mode`            | `full`       | Continuously poll the server (`full`), perform a full update cycle once and exit (`once`), only check for updates (`check`), only download updates (`download`) or only install updates (`install`).
| `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"`.
| `legacy_interface`        |              | Path to an executable interface for communicating with legacy secondary ECUs. See link:{aktualizr-github-url}/docs/legacysecondary.adoc[] for more information.
|==========================================================================================

== `discovery`

Config options for how secondary devices are detected by the primary.

[options="header"]
|==========================================================================================
| Name       | Default | Description
| `ipuptane` | `false` | Enable UDP multicast for secondary discovery.
|==========================================================================================

== `pacman`

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

[options="header"]
|==========================================================================================
| Name            | Default                   | Description
| `type`          | `"ostree"`                | Which package manager to use. Options: `"ostree"`, `"debian"`, `"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`.
|==========================================================================================

== `storage`

Options for how Aktualizr stores data locally.

[options="header"]
|==========================================================================================
| 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
| `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`.
| `sqldb_path`              | `"sql.db"`                | Relative path to the database file.
|==========================================================================================

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.

[options="header"]
|==========================================================================================
| Name                      | Default | Description
| `base_path`               |         | Path to a common root directory to the subsequent files
{'fraction_non_alphanumeric': 0.23427369144231183, 'fraction_numerical': 0.005238524625359612, 'mean_word_length': 3.263225334065532, 'pattern_counts': {'":': 0, '<': 6, '<?xml version=': 0, '>': 6, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 28, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2847100', 'n_tokens_mistral': 5947, 'n_tokens_neox': 5478, 'n_words': 2126}