Skip to content

README.md

Latest commit

 

History

History
69 lines (60 loc) · 5.96 KB

README.md

File metadata and controls

69 lines (60 loc) · 5.96 KB

HawkBit Configuration Manager

Introduction

We identified Eclipse hawkBit to be a very good fit for an integration with the Arrowhead framework. The wrapper code in this directory enables to integrate Eclipse hawkBit with the Arrowhead mandatory core systems and function as a configuration manager. Eclipse hawkBit allows administrators of distributed systems, consisting of constrained, but also more powerful devices, such as contollers or gateways, to manage rollouts of configuration changes and software updates. The featureset comprises the creation of cascading rollouts of consecutive device groups and the definition of error thresholds triggering emergency shutdowns of a rollout.

Eclipse hawkBit consists of the following APIs and interfaces:

  • Direct Device Integration (DDI): The DDI is a REST-based API that allows devices to frequently request hawkBit for configuration/software updates (polling).
  • Device Management Federation (DMF): As the DDI only supports HTTP, it is necessary to enable developers to integrate new protocol implementations, as not every device includes an HTTP stack. The DDI therefore enables proprietary protocols and most importantly allows the integration of publish/subscribe based patterns, which are necessary to guarantee a faster rollout of configuration files and are also more efficient.
  • Management UI: The Management UI allows users to manage their devices, plan and create new software/configuration updates, and deal with potential problems during the rollout
  • Management API: the Management API allows the integration of other business solutions to integrate with the management interface of hawkBit

This is the first version of the Eclipse hawkBit wrapper, which does support the basic hawkBit functionality, but should not be considered stable. ‚‚‚

Architecture‚‚

The system consists of a Spring Boot application, which is responsible for managing connections with

Currently, the configuration manager wrapper only supports devices that are able to communicate via WebSocket connection. However, future implementations might integrate other protocols by adding other implementations for the Sping Boot service which interfaces the devices.

Authentication

The configuration manager uses a client certificate to connect to the Arrowhead Authorization system in order to retrieve the public key that is used to sign JWTs. Therefore the configuration manager needs its own client certificate, as desribed here. To generate new credentials you can use the generate-certificates.sh script in the certificates directory. You will need to modify the following properties:

  • CA_KEYSTORE - the path to the keystore containing the cloud certificate/keys
  • CA_KEYSTORE_PASS - password for the keystore
  • CLIENT_ID - this is the ID/name of the core system (should comply with the Arrowhead CN naming conventions, e.g.: hawkbitconfigurationmanager)
  • CLOUD_DOMAIN - the CN of the cloud certificate (results in the CN of the client certificate, when combined with the CLIENT_ID, e.g.: example.corp.arrowhead.eu)
  • CLIENT_KEYSTORE_PASS - the password of the keystore Also make sure to modify the openssl.cnf file and enter the correct subject alternative names in the [alt_names] section (e.g.: IP.1 = 127.0.0.1 or DNS.1 = example.com).

In order to work properly, you need to acquire the cloud certificate. Change the file name in the generate-certificates.sh script using the CA_KEYSTORE variable and the corresponding password using the CA_KEYSTORE_PASS variable. The resulting PKCS12 keystore will be named ${CLIENT_ID}.full.p12. The CN of the generated certificates is the combined value of CLIENT_ID.CLOUD_DOMAIN, e.g: configuration.example.corp.arrowhead.eu. Don't forget to save the corresponding password, which will be printed after successful generation. Do not push any certificates!

There also exists a truststore, which is used by the configuration manager wrapper to validate the certificates of the Arrowhead core systems. This truststore (file name truststore.p12) must be generated by using the cloud certificate, and then be placed in the certificates directory. However, you can also modify the path in the application.yml Arrowhead uses PKCS12 files to store certificates and keys. For more information on how to generate the trust store see the certificate section of the Arrowhead Framework documentation.

Compatibility

Currently, the following functionality of the hawkBit DMF API (version 0.3.0M6) is implemented and available to the user via WebSockets:

DMF API message type supported current version
THING_CREATED ☑ ☑
THING_REMOVED ☑ ☑
UPDATE_ATTRIBUTES
UPDATE_ACTION_STATUS ☑ ☑
PING
CANCEL_DOWNLOAD ☑ ☑
DOWNLOAD_AND_INSTALL or DOWNLOAD ☑ ☑
MULTI_ACTION
THING_DELETED ☑ ☑
PING_RESPONSE

Deployment

To use the configuration manager, you need a running instance of Eclipse hawkBit. You can use the hawkBit image from Dockerhub to deploy an instance and then wire up the configuration manager wrapper with it. As part of this repository, there exists a Dockerfile that can be used to either build and run a container with the wrapper locally, or build and push the image into a private container registry.