The client is intended to be installed on devices that wish to receive OTA updates from a GENIVI-compatible OTA server.
The client is responsible for:
Communicating with the OTA server
Authenticating using locally available device and user credentials
Reporting current software and hardware configuration to the server
Checking for any available updates for the device
Downloaded any available updates
Installing the updates on the system, or notifying other services of the availability of the downloaded file
Receiving or generating installation reports (success or failure) for attempts to install received software
Submitting installation reports to the server
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).
Table of Contents
The following debian packages are used in the project:
cmake (>= 3.5)
curl (>= 7.47)
doxygen (when building additional documentation)
graphviz (when building additional documentation)
lcov (when building for code coverage)
libboost-filesystem-dev (>= 1.58.0)
libboost-log-dev (>= 1.58.0)
libboost-program-options-dev (>= 1.58.0)
libboost-serialization-dev (>= 1.58.0, when building with OPCUA support)
libboost-iostreams-dev (>= 1.58.0, when building with OPCUA support)
libcurl4-openssl-dev (>= 7.47)
libdpkg-dev (when building with Debian packaging support)
libostree-dev (>= 2017.7, when building with OSTree support)
libp11-2 (when building with PKCS#11 support)
libp11-dev (when building with PKCS#11 support)
libsystemd-dev (when building with systemd support for secondaries)
python3-dev (when building tests)
python3-openssl (when building tests)
python3-venv (when building tests)
sqlite3 (when building tests)
valgrind (when building tests)
On a Mac, building aktualizr with a brew package manager standard installation is partially supported. You can install the necessary dependencies with brew as follows:
brew install asn1c boost cmake libarchive libsodium pkgconfig
This project uses git submodules. To checkout the code:
git clone --recursive https://github.com/advancedtelematic/aktualizr cd aktualizr
If you had an old checkout, forgot to include
--recursive or need to update the submodules, run:
git submodule update --init --recursive
aktualizr is built using CMake. To setup your
mkdir build cd build cmake -DCMAKE_BUILD_TYPE=Debug ..
You can then build the project from the
build directory using Make:
You can also create a debian package:
To use CMake’s 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.
Before checking in code, it must pass the following tests (along with their corresponding build targets):
compilation of the main targets and tests without warning:
validation against the project’s automatic formatting conventions:
make check-formatto run the check,
make formatto apply the transformation automatically
absence of clang-tidy warning:
full test suite run:
make check(test build included),
make test(only run the tests)
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:
CTEST_OUTPUT_ON_FAILURE=1 CTEST_PARALLEL_LEVEL=8 make -j8 qa
Some tests require additional setups, such as code coverage, HSM emulation or provisioning credentials (credentials.adoc). The exact reference about these steps is the 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.
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:
TEST_WITH_COVERAGE=1 TEST_WITH_P11=1 TEST_WITH_STATICTESTS=1 ./scripts/test.sh
Alternatively, scripts/run_docker_test.sh can directly run the test script:
./scripts/run_docker_test.sh Dockerfile \ -eTEST_WITH_COVERAGE=1 \ -eTEST_WITH_P11=1 \ -eTEST_WITH_STATICTESTS=1 \ -- ./scripts/test.sh
Developing and debugging with an OpenEmbedded system
By default OpenEmbedded builds fixed versions of software from a VCS using bitbake recipes. When developing Aktualizr itself it is useful to have a quicker edit-compile-run cycle and access to a debugger. The following steps will use OpenEmbedded to create a cross-compilation environment, then build inside that.
Add the following to local.conf:
TOOLCHAIN_HOST_TASK_append = " nativesdk-cmake "
Build the SDK:
bitbake -c populate_sdk core-image-minimal
That will create a self-extracting installer that can be copied to your development machine. Install it by executing this script (or a similarly-named one, depending on your environment):
Execute this script (or something similar, depending on where you installed it) to update the environment to point to the cross compilers:
You may want to verify that
which cmakereturns something like this:
Create a cmake build directory for this cross-compile:
mkdir build-cross cd build-cross cmake .. <options> make aktualizr
The compiled 'aktualizr' executable can be copied to the remote system and run.
gdbserver 0.0.0.0:2159 ./aktualizr --config /usr/lib/sota/sota.toml --loglevel 0
$ gdb aktualizr (gdb) target remote localhost:2159
In CLion the remote debugger is configured as follows:
It is also possible to run it inside valgrind:
valgrind --vgdb=yes --vgdb-error=0 ./aktualizr --config /usr/lib/sota/sota.toml vgdb --port=2159
Then connect the debugger as usual.
To run the aktualizr client, you will need to provide a toml-formatted configuration file using the command line option
aktualizr -c <path/configfile>
Additional command line options can be found in the code (see ../src/aktualizr_primary/main.cc) or by running
aktualizr --help. More details on configuring aktualizr can be found in docs/configuration.adoc. If you are using meta-updater, more information about configuring aktualizr in that environment can be found there.
If you intend to use aktualizr to authenticate with a server, you will need some form of provisioning. Aktualizr currently supports three methods of provisioning: automatic, implicit, and by using an HSM. You can learn more about the credentials files used to support provisioning in docs/credentials.adoc.
This code is maintained by the OTA team at HERE Technologies. If you have questions about the project, please reach us through Github issues for this repository.
Complete contribution guidelines can be found in CONTRIBUTING.md.
A changelog can be found in CHANGELOG.md.
We also require that contributors accept the terms of Linux Foundation’s Developer Certificate of Origin:
Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
Specific instructions can be found in CONTRIBUTING.md