Skip to content
C++ SOTA Client
C++ C CMake Python Shell TSQL Other
Branch: master
Clone or download
Latest commit a3f279c Aug 23, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode Add docs for running locally Apr 26, 2018
ci/gitlab Allow failure of veracode CI trigger Aug 23, 2019
cmake-modules Add ability to set a prefix for an aktualizr test Mar 21, 2019
config OTA-2488: Move Managed and Virtual secondaries out of Uptane namespace Jul 3, 2019
docker Merge pull request #1263 from advancedtelematic/feat/c-api Aug 2, 2019
docs DOCS: edits in response to @merltron's feedback Aug 22, 2019
fuzz Move unit tests to source dirs May 15, 2018
include C API: UptaneCycle and campaigns Jul 26, 2019
partial Make aktualizr buildable without partial and isotp checkout Mar 12, 2019
scripts Rename "repo/image" to "repo/repo" Aug 23, 2019
src Rename "repo/image" to "repo/repo" Aug 23, 2019
tests Rename "repo/image" to "repo/repo" Aug 23, 2019
third_party Bump googletest Jun 4, 2019
.clang-format Sources formtatted with 160 columns Feb 16, 2017
.clang-tidy Disallow pointer arithmetic with clang-tidy May 9, 2018
.dockerignore Fix releases (again) Feb 7, 2018
.gitattributes Add gitattributes for files to not export Apr 30, 2019
.gitignore OTA-2683: Migrate documentation platform Aug 15, 2019
.gitmodules Make aktualizr buildable without partial and isotp checkout Mar 12, 2019
.ort.yml Also exclude license metadata and RIOT. Aug 2, 2019
.travis.yml Add a timeout for Travis runs Aug 15, 2019
CHANGELOG.md Update changelog for 2019.6 release. Aug 20, 2019
CMakeLists.txt Move everything doxygen-related to a new subdirectory. Aug 21, 2019
CONTRIBUTING.md Use the name of the project, not something weirdly generic. Jun 17, 2019
CTestCustom.cmake Configure large output limit for CTest Apr 18, 2018
Dockerfile Switch main CI to Ubuntu bionic and release for xenial/bionic Sep 1, 2018
LICENSE Initial commit Nov 25, 2016
README.adoc Remove dependency on libdpkg Jul 26, 2019
actions.md Merge pull request #1279 from advancedtelematic/refactor/rename-aktua… Aug 14, 2019
codecov.yml Fix ignore files Jan 11, 2019
thirdparty.spdx Remove dependency on libdpkg Jul 26, 2019

README.adoc

License: MPL 2.0 TravisCI Build Status codecov CII Best Practices standard-readme compliant

aktualizr

C++ implementation of Uptane OTA update client.

The client is intended to be installed on devices that wish to receive OTA updates from an Uptane-compatible OTA server such as HERE OTA Connect. It is most commonly built by using the 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:

  • 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

  • Downloading 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

Security

This client is aligned with the 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:

sudo apt install asn1c build-essential cmake curl libarchive-dev libboost-dev libboost-filesystem-dev libboost-log-dev libboost-program-options-dev libcurl4-openssl-dev libpthread-stubs0-dev libsodium-dev libsqlite3-dev libssl-dev

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:

  • cmake (>= 3.5)

  • curl (>= 7.47)

  • libboost-* (>= 1.58.0)

  • libcurl4-openssl-dev (>= 7.47)

  • libpthread-stubs0-dev (>= 0.3)

Additional packages are used for non-essential components:

  • To build the test suite, you will need net-tools python3-dev python3-openssl python3-venv sqlite3 valgrind.

  • To run the linting tools, you will need clang clang-format-6.0 clang-tidy-6.0.

  • To build additional documentation, you will need doxygen graphviz.

  • To build with code coverage, you will need lcov.

Some features also require additional packages:

  • For OSTree support, you will need libostree-dev (>= 2017.7).

  • For PKCS#11 support, you will need libp11-2 libp11-dev.

  • For systemd support for secondaries, you will need libsystemd-dev.

  • For fault injection, you will need fiu-utils libfiu-dev.

Mac support

You can install the latest release of aktualizr on MacOS (mostly useful for trying out a SOTA server with a fake device) using homebrew:

brew tap advancedtelematic/otaconnect
brew install aktualizr

You can also build it yourself, with basic dependencies from homebrew. You can install the necessary dependencies as follows:

brew install asn1c boost cmake libarchive libsodium pkgconfig python3

If you also want to compile the SOTA tools:

brew install gettext && brew unlink gettext && brew link --force gettext

and run cmake with -DBUILD_SOTA_TOOLS=ON.

Building

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 build directory:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..

You can then build the project from the build directory using Make:

make

You can also create a debian package:

make 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.

Running tests

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: make and make build_tests

  • validation against the project’s automatic formatting conventions: make check-format to run the check, make format to apply the transformation automatically

  • absence of clang-tidy warning: make clang-tidy

  • full test suite run: make check (test build included), make test (only run the tests)

The qa target includes all of these checks, including auto-formatting:

make qa

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 (docs/provisioning-methods-and-credentialszip.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:

./scripts/test.sh

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 Gitlab CI configuration and the project’s Dockerfiles.

Tags

Generate tags:

make 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:

./scripts/run_docker_test.sh Dockerfile

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

(see the content of ci/gitlab/.gitlab-ci.yml and scripts/test.sh for more testing options)

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

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:

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.

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 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 docs/client-provisioning-methods.adoc and docs/provision-with-device-credentials.adoc. You can learn more about the credentials files used to support provisioning in docs/provisioning-methods-and-credentialszip.adoc.

Maintainers

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 or email us at otaconnect.support@here.com.

Contribute

Complete contribution guidelines can be found in CONTRIBUTING.md.

Changelog

A changelog can be found in CHANGELOG.md.

License

This code is licensed under the Mozilla Public License 2.0, a copy of which can be found in this repository. All code is copyright HERE Europe B.V., 2016-2019.

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

You can’t perform that action at this time.