Git Product home page Git Product logo

aktualizr's Introduction

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

aktualizr

C++ reference implementation of GENIVI SOTA OTA update client.

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

Security

This client, and the GENIVI SOTA project, is aligned with the Uptane security framework for software updates. Full details and whitepapers can be found on their site.

Installation

Dependencies

The following debian packages are used in the project:

  • asn1c

  • build-essential

  • clang (optional)

  • clang-format-6.0 (optional)

  • clang-tidy-6.0 (optional)

  • cmake (>= 3.5)

  • curl (>= 7.47)

  • doxygen (when building additional documentation)

  • graphviz (when building additional documentation)

  • lcov (when building for code coverage)

  • libarchive-dev

  • libboost-dev

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

  • libpthread-stubs0-dev (>=0.3)

  • libsodium-dev

  • libsqlite3-dev

  • libssl-dev

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

Mac support

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

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

./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 Jenkins Pipelines definitions 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 Jenkinsfile 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

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.

  1. Add the following to local.conf:

    TOOLCHAIN_HOST_TASK_append = " nativesdk-cmake "
  2. Build the SDK:

    bitbake -c populate_sdk core-image-minimal
  3. 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):

    ./tmp/deploy/sdk/poky-sota-glibc-x86_64-core-image-minimal-core2-64-toolchain-2.2.2.sh
  4. Execute this script (or something similar, depending on where you installed it) to update the environment to point to the cross compilers:

    . /opt/poky-sota/2.2.2/environment-setup-core2-64-poky-linux

    You may want to verify that which cmake returns something like this:

    /opt/poky-sota/2.2.2/sysroots/x86_64-pokysdk-linux/usr/bin/cmake
  5. 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.

Aktualizr can be debugged remotely by exposing a port from the VM to development machine (the --gdb option to the run-qemu-ota script in meta-updater does this), then:

On the target:
gdbserver 0.0.0.0:2159 ./aktualizr --config /usr/lib/sota/sota.toml --loglevel 0
On the host:
$ gdb aktualizr
(gdb) target remote localhost:2159

In CLion the remote debugger is configured as follows:

CLion GDB configuration

It is also possible to run it inside valgrind:

On the target:
valgrind --vgdb=yes --vgdb-error=0 ./aktualizr --config /usr/lib/sota/sota.toml
vgdb --port=2159

Then connect the debugger as usual.

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.

Provisioning

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.

Maintainers

This code is maintained by the team at ATS Advanced Telematic Systems GmbH. If you have questions about the project, please reach us through Github issues for this repository.

Contribute

Complete contribution guidelines can be found in CONTRIBUTING.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 ATS Advanced Telematic Systems GmbH, 2016-2018.

aktualizr's People

Contributors

cajun-rat avatar embmk avatar gmacario avatar heartsucker avatar jochenschneider avatar lbonn avatar leon-anavi avatar merlhere avatar merltron avatar oytis avatar patriotyk avatar pattivacek avatar riqkum avatar rsalveti avatar seryogabrigada avatar stevana avatar tkfu avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.