diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2881e3bf17..dba489c44c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ We welcome code contributions from the community and are very happy to receive f Issue Tracker ---- -This project uses the Github issue tracker. Please report bugs, issues and feature requests here +This project uses the Github issue tracker. Please report bugs, issues and feature requests here. Code quality and style ---- @@ -17,7 +17,7 @@ All code should be developed according to the [Google C++ style guide](https://g - Wherever possible, automated testing should be used - Tests cases should at least exercise all documented requirements - If automated testing is not possible, manual test cases should be described - * It must be easy for a developer checking out a project to run the test suite based on the information in the README.md file + * It must be easy for a developer checking out a project to run the test suite based on the information in the [readme](README.adoc) * All code must pass all unit tests before a merge request is made - Tests that don't pass should be marked pending (with justification) or should be fixed. * All code must pass formatting and static linting tests @@ -40,7 +40,7 @@ All code should be developed according to the [Google C++ style guide](https://g Making a Pull Request ---- -When you start developing a feature, please create a feature branch that includes the type of branch, the ID of the issue, and a brief description. For example `feat/9/https-support`, `bugfix/11/fix-token-expiry` or `refactor/13/tidy-up-imports`. Please do not mix feature development, bugfixes and refactoring into the same branch. +When you start developing a feature, please create a feature branch that includes the type of branch, the ID of the issue or ticket if available, and a brief description. For example `feat/9/https-support`, `fix/OTA-123/fix-token-expiry` or `refactor/tidy-up-imports`. Please do not mix feature development, bugfixes and refactoring into the same branch. When your feature is ready, push the branch and make a pull request. We will review the request and give you feedback. Once the code passes the review it can be merged into master and the branch can be deleted. diff --git a/README.adoc b/README.adoc index 74d3da2155..0a0ea3d223 100644 --- a/README.adoc +++ b/README.adoc @@ -10,7 +10,7 @@ https://opensource.org/licenses/MPL-2.0[image:https://img.shields.io/badge/Licen C++ implementation of https://uptane.github.io[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. +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: @@ -18,7 +18,7 @@ The client is responsible for: * 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 +* 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 @@ -32,46 +32,41 @@ toc::[] == Security -This client is aligned with the https://uptane.github.io[Uptane] security framework for software updates. Full details and whitepapers can be found on their site. +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 -The following debian packages are used in the project: +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: -* 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) +* libboost-* (>= 1.58.0) * 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) +* libpthread-stubs0-dev (>= 0.3) + +Additional packages are used for non-essential components: + +* To build the test suite, you will need `python3-dev python3-openssl python3-venv sqlite3 valgrind`. +* To run the lintint 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`. +* For OPCUA support, you will need `libboost-iostreams-dev libboost-serialization-dev`. +* For Debian packagin support, you will need `libdpkg-dev`. ==== Mac support @@ -207,78 +202,6 @@ Alternatively, link:scripts/run_docker_test.sh[] can directly run the test scrip -- ./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 .. -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 https://github.com/advancedtelematic/meta-updater/blob/rocko/scripts/run-qemu-ota[run-qemu-ota script] in https://github.com/advancedtelematic/meta-updater[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: - -image:docs/clion-debugger.png[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 @@ -294,21 +217,21 @@ Additional command line options can be found in the code (see link:../src/aktual [#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. To get a binary you can run locally, you can: +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: * follow the <>, * install a Ubuntu packages from the https://github.com/advancedtelematic/aktualizr/releases[Releases page], or * install through <> -Some more detailed instructions on how to configure a fake device can be found on https://docs.atsgarage.com/quickstarts/install-a-client-locally-with-fake-secondaries.html[the OTA Connect docs site]. +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 three methods of provisioning: link:docs/automatic-provisioning.adoc[automatic], link:docs/implicit-provisioning.adoc[implicit], and link:docs/hsm-provisioning.adoc[by using an HSM]. You can learn more about the credentials files used to support provisioning in link:docs/credentials.adoc[]. +If you intend to use aktualizr to authenticate with a server, you will need some form of provisioning. Aktualizr currently supports two methods of provisioning: link:docs/automatic-provisioning.adoc[automatic] and link:docs/implicit-provisioning.adoc[implicit]. You can also implicitly provision link:docs/hsm-provisioning.adoc[by using an HSM]. You can learn more about the credentials files used to support provisioning in link:docs/credentials.adoc[]. == Maintainers -This code is maintained by the OTA team at https://www.here.com/en/products-services/here-automotive-suite/ota-software-management/here-ota-connect[HERE Technologies]. If you have questions about the project, please reach us through Github issues for this repository. +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 diff --git a/config/CMakeLists.txt b/config/CMakeLists.txt index 3bcc2ee1b3..566acf5b3d 100644 --- a/config/CMakeLists.txt +++ b/config/CMakeLists.txt @@ -17,5 +17,5 @@ if(BUILD_DEB) COMPONENT aktualizr) endif(BUILD_DEB) -install(DIRECTORY DESTINATION /etc/sota/conf.d COMPONENT aktualizr) +install(DIRECTORY DESTINATION etc/sota/conf.d COMPONENT aktualizr) install(DIRECTORY DESTINATION lib/sota/conf.d COMPONENT aktualizr) diff --git a/docs/INDEX.md b/docs/INDEX.md index 74821698d5..3be476fbb9 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -15,4 +15,4 @@ The client is responsible for the following tasks: The aktualizr client application is a thin wrapper around the client library "libaktualizr". You could regard this library as a kind of toolbox. You can use the parts in this library to build a software update solution that conforms to the Uptane standard. -For all controllers that run aktualizr or include libaktualizr, you’ll need to implement some form of key provisioning. The OTA Connect documentation explains in detail how to [select a provisioning method](https://docs.atsgarage.com/client-config/client-provisioning-methods.html) that suits your use case. For more information on how you can use this library, also see the [reference docs](https://github.com/advancedtelematic/aktualizr/tree/master/docs). +For all controllers that run aktualizr or include libaktualizr, you’ll need to implement some form of key provisioning. The OTA Connect documentation explains in detail how to [select a provisioning method](https://docs.ota.here.com/client-config/client-provisioning-methods.html) that suits your use case. For more information on how you can use this library, also see the [reference docs](https://github.com/advancedtelematic/aktualizr/tree/master/docs). diff --git a/docs/deb-package-install.adoc b/docs/deb-package-install.adoc index 728cb3fdc7..8652a9fdd8 100644 --- a/docs/deb-package-install.adoc +++ b/docs/deb-package-install.adoc @@ -8,7 +8,7 @@ sudo apt install ./aktualizr.deb === Setting up aktualizr -The debian package will install, enable, and start an `aktualizr` systemd service immediately after it's installed. However, there are some configuration steps that should be taken before the service starts. To use aktualizr with a server (i.e. https://github.com/advancedtelematic/ota-community-edition/[OTA Community Edition] or https://docs.atsgarage.com[HERE OTA Connect]), you will need to download the provisioning credentials file provided by the server and place it at `/var/sota/sota_provisioning_credentials.zip`. +The debian package will install, enable, and start an `aktualizr` systemd service immediately after it's installed. However, there are some configuration steps that should be taken before the service starts. To use aktualizr with a server (i.e. https://github.com/advancedtelematic/ota-community-edition/[OTA Community Edition] or https://docs.ota.here.com[HERE OTA Connect]), you will need to download the provisioning credentials file provided by the server and place it at `/var/sota/sota_provisioning_credentials.zip`. You can pass any other command line arguments in this file, as well. diff --git a/docs/debugging-tips.adoc b/docs/debugging-tips.adoc index fd48dd8eb0..5a9cedf6c9 100644 --- a/docs/debugging-tips.adoc +++ b/docs/debugging-tips.adoc @@ -81,11 +81,11 @@ TARGET_LENGTH="130" # the size of the target # This command will create the update (but not schedule it anywhere) -MTU_UPDATE=$(http POST 'https://ci-app.atsgarage.com/api/v1/multi_target_updates' Csrf-Token:"$CSRF_TOKEN" Cookie:"$COOKIE" targets:="{\"$ECU_HARDWARE\": {\"to\": {\"target\": \"$TARGET\", \"checksum\": {\"method\": \"sha256\", \"hash\":\"$HASH\"}, \"targetLength\": $TARGET_LENGTH}}}" | tr -d '"') +MTU_UPDATE=$(http POST 'https://app.atsgarage.com/api/v1/multi_target_updates' Csrf-Token:"$CSRF_TOKEN" Cookie:"$COOKIE" targets:="{\"$ECU_HARDWARE\": {\"to\": {\"target\": \"$TARGET\", \"checksum\": {\"method\": \"sha256\", \"hash\":\"$HASH\"}, \"targetLength\": $TARGET_LENGTH}}}" | tr -d '"') echo "The mtu-update is: $MTU_UPDATE" # Schedule the update on the device -http PUT "https://ci-app.atsgarage.com/api/v1/admin/devices/$DEVICE/multi_target_update/$MTU_UPDATE" Csrf-Token:"$CSRF_TOKEN" Cookie:"$COOKIE" +http PUT "https://app.atsgarage.com/api/v1/admin/devices/$DEVICE/multi_target_update/$MTU_UPDATE" Csrf-Token:"$CSRF_TOKEN" Cookie:"$COOKIE" ``` @@ -149,7 +149,7 @@ aktualizr can be tested against a dummy repository containing fake images First, generate a repository using `aktualizr-repo` command: - `aktualizr-repo generate repo_dir` + `aktualizr-repo generate repo_dir` Then, serve the generated directory using a web server. @@ -176,3 +176,77 @@ server { == Inject faults See link:./fault-injection.adoc[fault-injection.adoc] + +== 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 .. +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 https://github.com/advancedtelematic/meta-updater/blob/master/scripts/run-qemu-ota[run-qemu-ota script] in https://github.com/advancedtelematic/meta-updater[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: + +image:clion-debugger.png[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. + + diff --git a/docs/opcua-bridge.adoc b/docs/opcua-bridge.adoc index e9af69f1b8..c464f58756 100644 --- a/docs/opcua-bridge.adoc +++ b/docs/opcua-bridge.adoc @@ -19,7 +19,7 @@ On secondary side it is required to use `--opcua` command line option to enable == OPC-UA Bridge Demo Notes -Check instructions stated in https://docs.atsgarage.com/quickstarts/raspberry-pi.html[Raspberry PI] to prepare primary and secondary images. At the moment no dedicated +Check instructions stated in https://docs.ota.here.com/quickstarts/raspberry-pi.html[Raspberry Pi] to prepare primary and secondary images. At the moment no dedicated SOTA feature is introduced to activate OPC-UA, so ensure that build options mentioned above are set. === Raspberry PI 3 Wireless Support