:toc: macro :toc-title:
https://opensource.org/licenses/MPL-2.0[image:https://img.shields.io/badge/License-MPL%202.0-brightgreen.svg[License: MPL 2.0]] https://codecov.io/gh/advancedtelematic/aktualizr[image:https://codecov.io/gh/advancedtelematic/aktualizr/branch/master/graph/badge.svg[codecov]] https://bestpractices.coreinfrastructure.org/projects/674[image:https://bestpractices.coreinfrastructure.org/projects/674/badge[CII Best Practices]] https://github.com/RichardLitt/standard-readme[image:https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat[standard-readme compliant]]
[discrete] = aktualizr
The client is intended to be installed on devices that wish to receive OTA updates from an Uptane-compatible OTA server such as https://connect.ota.here.com/[HERE OTA Connect]. It is most commonly built by using the https://github.com/advancedtelematic/meta-updater[meta-updater] layer in a Yocto environment. You can use aktualizr as a stand-alone system tool or you can integrate libaktualizr into a larger project.
The client is responsible for:
The client maintains the integrity and confidentiality of the OTA update in transit, communicating with the server over a TLS link. The client can run either as a system service, periodically checking for updates, or can by triggered by other system interactions (for example on user request, or on receipt of a wake-up message from the OTA server).
[discrete] == Table of Contents
toc::[]
== Security
This client is aligned with the https://uptane.github.io[Uptane] security framework for software updates. Full details and documentation can be found on their site.
== Installation
=== Dependencies
To install the minimal requirements on Debian/Ubuntu, run this:
The default versions packaged in recent Debian/Ubuntu releases are generally new enough to be compatible. If you are using older releases or a different variety of Linux, there are a few known minimum versions:
Additional packages are used for non-essential components:
net-tools python3-dev python3-openssl python3-venv sqlite3 valgrind.clang clang-format-10 clang-tidy-10.doxygen graphviz.lcov.Some features also require additional packages:
libostree-dev (>= 2017.7).libp11-3 libp11-dev.fiu-utils libfiu-dev.=== Building
This project uses git submodules. To checkout the code:
If you had an old checkout, forgot to include --recursive or need to update the submodules, run:
aktualizr is built using CMake. To setup your build directory:
You can then build the project from the build directory using Make:
You can also create a link:docs/ota-client-guide/modules/ROOT/pages/deb-package-install.adoc[debian package]:
To use CMake's link:https://ninja-build.org/[Ninja] backend, add -G Ninja to the first CMake invocation. It has the advantage of running all targets in parallel by default and is recommended for local development.
=== Running tests
Before checking in code, it must pass the following tests (along with their corresponding build targets):
make and make build_testsmake check-format to run the check, make format to apply the transformation automaticallymake clang-tidymake check (test build included), make test (only run the tests)The qa target includes all of these checks, including auto-formatting:
Note that, by default, the compilation and tests run in sequence and the output of failing tests is suppressed. To run in parallel, for example with eight threads, and print the output of failing tests, run this:
Some tests require additional setups, such as code coverage, HSM emulation or link:docs/ota-client-guide/modules/ROOT/pages/provisioning-methods-and-credentialszip.adoc[provisioning credentials]. The exact reference about these steps is the link:scripts/test.sh[main test script] used for CI. It is parametrized by a list of environment variables and is used by our CI environments. To use it, run it in the project's root directory:
Note that it will run CMake itself in a dedicated build directory.
To get a list of the common environment variables and their corresponding system requirements, have a look at the link:ci/gitlab/.gitlab-ci.yml[Gitlab CI configuration] and the project's link:docker/[Dockerfiles].
=== Tags
Generate tags:
=== Building with Docker
Several Dockerfiles are provided to support building and testing the application without dependencies on your local environment.
If you have a working docker client and docker server running on your machine, you can build and run a docker image on the default environment with:
It will start a shell session inside the container, running as the same UID/GID as on the host system, with the current directory mounted as a docker volume. Any local code changes are then immediately in effect inside the container and user/group permissions are compatible in the two environments.
Inside the container, the test suite with coverage can be run with:
(see the content of link:ci/gitlab/.gitlab-ci.yml[] and link:scripts/test.sh[] for more testing options)
Alternatively, link:scripts/run_docker_test.sh[] can directly run the test script:
== Usage
=== Configuration
To run the aktualizr client, you will need to provide a toml-formatted configuration file using the command line option -c or --config:
Additional command line options can be found link:./src/aktualizr_primary/main.cc[in the code] or by running aktualizr --help. More details on configuring aktualizr can be found in link:docs/ota-client-guide/modules/ROOT/pages/aktualizr-config-options.adoc[]. If you are using https://github.com/advancedtelematic/meta-updater[meta-updater], more information about configuring aktualizr in that environment can be found there.
[#fake-device] === Running a "fake" device
Aktualizr is generally intended to run on embedded devices, but you may find it convenient to run it on your local system for development or testing. To get a binary you can run locally, you can:
Some more detailed instructions on how to configure a fake device can be found on https://docs.ota.here.com/quickstarts/install-a-client-locally-with-fake-secondaries.html[the OTA Connect docs site].
=== Provisioning
If you intend to use aktualizr to authenticate with a server, you will need some form of provisioning. Aktualizr currently supports provisioning with shared credentials or with device credentials. Device credential provisioning supports using an HSM to store private keys. The differences and details are explained in link:docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc[] and link:docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provisioning.adoc[]. You can learn more about the credentials files used to support provisioning in link:docs/ota-client-guide/modules/ROOT/pages/provisioning-methods-and-credentialszip.adoc[].
== Changelog
The changelog is available in link:CHANGELOG.md[].
== Maintainers
This code is maintained by the OTA team at https://www.here.com/products/automotive/ota-technology[HERE Technologies]. If you have questions about the project, please reach us through Github issues for this repository or email us at otaconnect.support@here.com.
== Contribute
Complete contribution guidelines can be found in link:CONTRIBUTING.md[].
== License
This code is licensed under the link:LICENSE[Mozilla Public License 2.0], a copy of which can be found in this repository. All code is copyright HERE Europe B.V., 2016-2020.
We require that contributors accept the terms of Linux Foundation's link:https://developercertificate.org/[Developer Certificate of Origin]. Specific instructions can be found in link:CONTRIBUTING.md[].