Welcome to RAUC hawkBit Updater’s documentation!

Using the RAUC hawkbit Updater

Authentication

As described on the hawkBit Authentication page in the “DDI API Authentication Modes” section, a device can be authenticated with a security token. A security token can be either a “Target” token or a “Gateway” token. The “Target” security token is specific to a single target defined in hawkBit. In the RAUC hawkBit updater’s configuration file it’s referred to as auth_token.

Targets can also be connected through a gateway which manages the targets directly and as a result these targets are indirectly connected to the hawkBit update server. The “Gateway” token is used to authenticate this gateway and allow it to manage all the targets under its tenant. With RAUC hawkBit updater such token can be used to authenticate all targets on the server. I.e. same gateway token can be used in a configuration file replicated on many targets. In the RAUC hawkBit updater’s configuration file it’s called gateway_token. Although gateway token is very handy during development or testing, it’s recommended to use this token with care because it can be used to authenticate any device.

Reference

Configuration File

Example configuration:

[client]
hawkbit_server            = 127.0.0.1:8080
ssl                       = false
ssl_verify                = false
tenant_id                 = DEFAULT
target_name               = test-target
auth_token                = bhVahL1Il1shie2aj2poojeChee6ahShu
bundle_download_location  = /tmp/bundle.raucb

[device]
key1                      = valueA
key2                      = valueB

[client] section

Configures how to connect to a hawkBit server, etc.

Mandatory options:

hawkbit_server=<host>[:<port>]

The IP or hostname of the hawkbit server to connect to (Punycode representation must be used for host names containing Unicode characters). The port can be provided optionally, separated by a colon.

target_name=<name>

Unique name string to identify controller.

auth_token=<token>

Controller-specific authentication token. This is set for each device individually. For details, refer to https://www.eclipse.org/hawkbit/concepts/authentication/.

Note

Either auth_token or gateway_token must be provided

gateway_token=<token>

Gateway authentication token. This is a tenant-wide token and must explicitly be enabled in hakwBit first. It is actually meant to authenticate a gateway that itself manages/authenticates multiple targets, thus use with care. For details, refer to https://www.eclipse.org/hawkbit/concepts/authentication/.

Note

Either auth_token or gateway_token must be provided

bundle_download_location=<path>

Full path to where the bundle should be downloaded to. E.g. set to /tmp/_bundle.raucb to let rauc-hawkbit-updater use this location within /tmp.

Optional options:

tenant_id=<ID>

ID of the tenant to connect to. Defaults to DEFAULT.

ssl=<boolean>

Whether to use SSL connections (https) or not (http). Defaults to true.

ssl_verify=<boolean>

Whether to enforce SSL verification or not. Defaults to true.

connect_timeout=<seconds>

HTTP connection setup timeout [seconds]. Defaults to 20 seconds.

timeout=<seconds>

HTTP request timeout [seconds]. Defaults to 60 seconds.

retry_wait=<seconds>

Time to wait before retrying in case an error occurred [seconds]. Defaults to 60 seconds.

post_update_reboot=<boolean>

Whether to reboot the system after a successful update. Defaults to false.

Important

Note that this results in an immediate reboot without contacting the system manager and without terminating any processes or unmounting any file systems. This may result in data loss.

log_level=<level>

Log level to print, where level is a string of

  • debug

  • info

  • message

  • critical

  • error

  • fatal

Defaults to message.

[device] section

This section allows to set a custom list of key-value pairs that will be used as config data target attribute for device registration. They can be used for target filtering.

Important

The [device] section is mandatory and at least one key-value pair must be configured.

Contributing

Thank you for thinking about contributing to RAUC hawkBit Updater! Various backgrounds and use-cases are essential for making RAUC hawkBit Updater work well for all users.

The following should help you with submitting your changes, but don’t let these guidelines keep you from opening a pull request. If in doubt, we’d prefer to see the code earlier as a work-in-progress PR and help you with the submission process.

Workflow

  • Changes should be submitted via a GitHub pull request.

  • Try to limit each commit to a single conceptual change.

  • Add a signed-of-by line to your commits according to the Developer’s Certificate of Origin (see below).

  • Check that the tests still work before submitting the pull request. Also check the CI’s feedback on the pull request after submission.

  • When adding new features, please also add the corresponding documentation and test code.

  • If your change affects backward compatibility, describe the necessary changes in the commit message and update the examples where needed.

Code

  • Basically follow the Linux kernel coding style

Documentation

Developer’s Certificate of Origin

RAUC hawkBit Updater uses the Developer’s Certificate of Origin 1.1 with the same process as used for the Linux kernel:

Developer’s Certificate of Origin 1.1

By making a contribution to this project, I certify that:

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

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

  3. The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

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

Then you just add a line (using git commit -s) saying:

Signed-off-by: Random J Developer <random@developer.example.org>

using your real name (sorry, no pseudonyms or anonymous contributions).

Changes in RAUC hawkBit Updater

Release 1.0 (released Sep 15, 2021)

This is the initial release of RAUC hawkBit Updater.

The RAUC hawkBit updater is a simple commandline tool / daemon written in C (glib). The daemon runs on your target and operates as an interface between the RAUC D-Bus API and the hawkBit DDI API.

_images/rauc-hawkbit-updater-scheme.png