diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 000000000..e69de29bb diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..5f422d84c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,58 @@ +# IoT. Update. Device. + +Eclipse hawkBit™ is a domain independent back-end framework for rolling out software updates to constrained edge devices as well as more powerful controllers and gateways connected to IP based networking infrastructure. + +

+ eclipse foundation logo +

+ +--- + +## Interfaces + +hawkBit offers a direct device integration via HTTP or a device management federation API which allows to connect devices with different protocol adapter. Users can make use of the graphical user interface and other service can interact with hawkBit through the RESTful management API. + +--- + +## Rollout + +
+ +
+ +hawkBit supports an easy and flexible rollout management which allows you to update a large amount of devices in separated groups. + +- Cascading start of the deployment groups based on installation status of the previous group. +- Emergency shutdown of the rollout in case a group exceeds the defined error threshold. +- Rollout progress monitoring for the entire rollout and the individual groups. + +
+ +
+ +Rollout Diagram + +
+ +
+ +--- + +## Package Model + +
+ +
+ +Package Model Diagram + +
+ +
+ +A software update does not always contain only a single file. +The hawkBit meta model allows you to configure your files in virtual software and distribution packages. + +
+ +
diff --git a/docs/_coverpage.md b/docs/_coverpage.md new file mode 100644 index 000000000..5b2eb9665 --- /dev/null +++ b/docs/_coverpage.md @@ -0,0 +1,17 @@ + +hawkBit logo + + + +# Open‑source software update server for IoT devices. + +[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=eclipse-hawkbit_hawkbit&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=eclipse-hawkbit_hawkbit) +[![Maven Central](https://img.shields.io/maven-central/v/org.eclipse.hawkbit/hawkbit-parent?label=maven-central&color=blue)](https://search.maven.org/search?q=g:org.eclipse.hawkbit) +[![Lines of code](https://img.shields.io/badge/dynamic/xml.svg?label=Lines%20of%20code&url=https%3A%2F%2Fwww.openhub.net%2Fprojects%2Fhawkbit.xml%3Fapi_key%3D30bc3f3fad087c2c5a6a67a8071665ba0fbe3b6236ffbf71b7d20849f4a5e35a&query=%2Fresponse%2Fresult%2Fproject%2Fanalysis%2Ftotal_code_lines&colorB=lightgrey)](https://www.openhub.net/p/hawkbit) +[![Join the chat at https://gitter.im/eclipse/hawkbit](https://badges.gitter.im/eclipse/hawkbit.svg)](https://gitter.im/eclipse/hawkbit?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) + +[Documentation](README) +[Release notes](release-notes) +[GitHub](https://github.com/eclipse-hawkbit/hawkbit) + +![color](#F0EEEA) diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 000000000..ce65e32df --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,46 @@ +- Getting Started + - [Overview](README.md) + - [What is hawkBit](what-is-hawkbit.md) + - [Quick Start](quick-start.md) + - [Features](features.md) + +- Guides + - [Run hawkBit](run-hawkbit.md) + - [Feign Client](feign-client.md) + - [Clustering](clustering.md) + +-Concepts + - [Authentication](authentication.md) + - [Authorization](authorization.md) + - [Data model](datamodel.md) + - [Rollout management](rollout-management.md) + - [Targets state](targetstate.md) + +- APIs + - [Management API](management-api.md) + - [Direct Device Integration API](direct-device-integration-api.md) + - [Device Management Federation API](device-management-federation-api.md) + +- [Release notes](release-notes.md) + +
+ +- [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=eclipse-hawkbit_hawkbit&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=eclipse-hawkbit_hawkbit) +- [![Maven Central](https://img.shields.io/maven-central/v/org.eclipse.hawkbit/hawkbit-parent?label=maven-central&color=blue)](https://search.maven.org/search?q=g:org.eclipse.hawkbit) + + + + +- [![Join the chat at https://gitter.im/eclipse/hawkbit](https://badges.gitter.im/eclipse/hawkbit.svg)](https://gitter.im/eclipse/hawkbit?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) + +- [![License](https://img.shields.io/badge/License-EPL%202.0-green.svg)](https://opensource.org/licenses/EPL-2.0) + +
+ +

+ eclipse foundation logo +

diff --git a/docs/authentication.md b/docs/authentication.md new file mode 100644 index 000000000..95b7b12fe --- /dev/null +++ b/docs/authentication.md @@ -0,0 +1,295 @@ +# Authentication + +A hawkBit update server can be accessed in four different ways: + +- _Direct Device Integration (DDI) API_ by **targets**. +- _Management API_ by 3rd party **applications**. +- _Device Management Federation (DMF) API_ by 3rd party **applications** through AMQP. + +--- + +## DDI API Authentication Modes + +### Security Token + +hawkBit supports multiple ways to authenticate a target against the server. The different authentication modes can be +individual enabled and disabled within hawkBit. Both on system level (with Spring Boot properties) as per individual +tenant. + +#### Target Security Token Authentication + +There is a 32 alphanumeric character security-token for each created target within IoT hawkBit. This token can be used +to authenticate the target at hawkBit through the HTTP-Authorization header with the custom scheme _TargetToken_. + +```http +GET /DEFAULT/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1 +Host: your.hawkBit.server +Authorization: TargetToken bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY +``` + +The target security token is provided in **DMF API** as part of the update message in order to allow +DMF clients to leverage the feature or can it be manually retrieved per target +by **Management UI** or in the **Management UI** in the target details. + +Note: needs to be enabled in your hawkBit installation (See [DdiSecurityProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java) +for system-wide enablement) **and** in the tenant configuration (set [TenantConfigurationProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-repository/hawkbit-repository-api/src/main/java/org/eclipse/hawkbit/tenancy/configuration/TenantConfigurationProperties.java)#TenantConfigurationKey.AUTHENTICATION_MODE_TARGET_SECURITY_TOKEN_ENABLED, _authentication.targettoken.enabled_ to true). That allows both the +operator and the individual customer (if run in a multi-tenant setup) to enable this access method. + +#### Gateway Security Token Authentication + +Often the targets are connected through a gateway which manages the targets directly and as a result are indirectly +connected to the hawkBit update server. + +To authenticate this gateway and allow it to manage all target instances under its tenant there is a _GatewayToken_ to +authenticate this gateway through the HTTP-Authorization header with a custom scheme _GatewayToken_. This is of course +also handy during development or for testing purposes. However, we generally recommend to use this token with care as it +allows to act _in the name of_ any device. + +```http +GET /DEVICE/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1 +Host: your.hawkBit.server +Authorization: GatewayToken 3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW +``` + +Note: needs to be enabled in your hawkBit installation (See [DdiSecurityProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java) +for system-wide enablement) **and** in the tenant configuration (set [TenantConfigurationProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-repository/hawkbit-repository-api/src/main/java/org/eclipse/hawkbit/tenancy/configuration/TenantConfigurationProperties.java)#TenantConfigurationKey.AUTHENTICATION_MODE_GATEWAY_SECURITY_TOKEN_ENABLED, _authentication.gatewaytoken.enabled_ to true). That allows both the +operator and the individual customer (if run in a multi-tenant setup) to enable this access method. + +### Certificate Authentication by Reverse Proxy + +hawkBit offers a certificate-based authentication mechanism, also known as mutual TLS (mTLS), which eliminates the need +to share a security token with the server. To implement this, you'll require a reverse proxy deployed in front of the +hawkBit server to handle authentication. This process involves obtaining certificates (and keys) for both the client and +the reverse proxy and configuring hawkBit accordingly. + +Initially, you'll need to obtain certificates (and keys) for these components from the same or different Certificate +Authorities (CAs). Once you have acquired certificates you have to set them up to both the client and the hawkBit +server. + +Then you shall enable *Allow targets to authenticate via a certificate authenticated by a reverse proxy* and set the +fingerprint of the client certificate issuer(s) (as a comma separated list). + +To authenticate the request to hawBit the following condition shall be met: + +- the common name of the client certificate shall match the controller/client id +- the TLS Issuer(s) hash of the presented client certificate shall be set for the tenant. + +For that you shall: +- enable header authentication in the tenant configuration - set [TenantConfigurationProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-repository/hawkbit-repository-api/src/main/java/org/eclipse/hawkbit/tenancy/configuration/TenantConfigurationProperties.java)#TenantConfigurationKey.AUTHENTICATION_MODE_HEADER_ENABLED, _authentication.header.enabled_ to true. +- set / configure the issuer, for the tenant, in the tenant configuration - set [TenantConfigurationProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-repository/hawkbit-repository-api/src/main/java/org/eclipse/hawkbit/tenancy/configuration/TenantConfigurationProperties.java)#AUTHENTICATION_MODE_HEADER_AUTHORITY_NAME.AUTHENTICATION_MODE_HEADER_ENABLED, _aauthentication.header.authority_ to issuer hash. + + You can use the following command to get the issuer hash + ```shell + openssl x509 -in client_certificate.crt -issuer_hash -noout` + ``` + +Here is an example diagram that shows all the communication between the hawkBit, reverse proxy and client. For the sake +of simplification we assume that there are not intermediate certificates and the certificate and key are as follows: + +- client_ca.crt signs client.crt +- server_ca.crt signs server.crt + +- client has the client.crt, client.key and server_ca.crt +- server (in this case reverse proxy) has the server.crt, server.key and client_ca.crt + +

+ eclipse foundation logo +

+ +#### Example - Nginx Reverse Proxy Configurations + +Nginx doesn't support obtaining the issuer hash without addons. Therefore, in this example we bypass sending real SSL +Issuer hash to hawhBit but do certificate issuer validation at Nginx and then supply shared (between Nginx and hawkBit) +fixed hash "Hawkbit". You could use any value here as long as it is matched with the *Allow targets to authenticate via +a certificate authenticated by a reverse proxy* setting in the hawkBit UI. Note that for multi-tenant scenarios with +different trusted CAs this example won't work. + +1. Hawkbit Configurations + + There are also some configurations that you need update when you deployed your hawkbit service. + + You need to add the given setting to your hawkBit configurations so that hawkBit can generate the URLs according to + the https that the client will use to download. If you're deploying hawkBit as a Docker container, add these + configurations as environmental values in the docker-compose.yml file. + +```properties +server.forward-headers-strategy=NATIVE +``` + +2. In Hawkbit's UI section, under system configuration, make sure to select *Allow targets to authenticate via a + certificate authenticated by a reverse proxy* and input the fixed issuer hash as "Hawkbit". This can be whetever you + have configured in the nginx configuration in `proxy_set_header X-Ssl-Issuer-Hash-1` below. + +3. After placing your certificates and keys, you need to deploy your proxy server and apply the provided configurations. + You can apply mutual TLS specifically to the URL given below to implement the process only for devices using the + Device Integration API: + + `hawkbit.dev.example.com/default/controller/` + + This ensures that other clients, like UI users, can connect to hawkBit without requiring client certificates. They + can use Username and Password in the Management API, eliminating the need for authentication and making it more + user-friendly. + +```nginx +# Nginx Hawkbit Configurations + +# Gets the Common Name of the certificate from the client certificate. +map $ssl_client_s_dn $ssl_client_s_dn_cn { + default ""; + ~CN=(?[^,]+) $CN; +} + +server { + listen 80; + listen [::]:80; + + server_name hawkbit.dev.example.com www.hawkbit.dev.example.com; + server_tokens off; + + location /.well-known/acme-challenge/ { + root /var/www/certbot; + } + + location / { + return 301 https://hawkbit.dev.example.com$request_uri; + } +} + +server { + listen 443 ssl; + listen [::]:443 ssl; + + server_name hawkbit.dev.example.com; + + ssl_certificate /etc/nginx/ssl/live/hawkbit.dev.example.com/server.crt; + ssl_certificate_key /etc/nginx/ssl/live/hawkbit.dev.example.com/server.key; + + ssl_client_certificate /etc/nginx/client-cer/client_ca.crt; + ssl_verify_client optional; + ssl_verify_depth 3; + + + # For devices that is using device integration API, + # Mutual TLS is required. + location ~*/.*/controller/ { + if ($ssl_client_verify != SUCCESS) { + return 403; + } + + proxy_pass http://hawkbit.dev.example.com:8080; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + + # Client certificate Common Name and Issuer Hash is required + # for auth in hawkbit. + proxy_set_header X-Ssl-Client-Cn $ssl_client_s_dn_cn; + proxy_set_header X-Ssl-Issuer-Hash-1 Hawkbit; + + # These are required for clients to upload and download software. + proxy_request_buffering off; + client_max_body_size 1000m; + } + + # For clients that is using UI or Management API + location / { + proxy_pass http://hawkbit.dev.example.com:8080; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_request_buffering off; + client_max_body_size 1000m; + } +} +``` + +4. To deploy Nginx, you could use a `.yml` file. Here's an example `docker-compose.yml` file for Nginx Docker. + +```yml +version: '3' + +services: + webserver: + image: nginx:latest + ports: + - 80:80 + - 443:443 + restart: always + volumes: + - ./nginx/conf/:/etc/nginx/conf.d/:ro + - ./certbot/www:/var/www/certbot/:ro + - ./certbot/conf/:/etc/nginx/ssl/:ro + - ./client-cer/:/etc/nginx/client-cer/ + - ./landing-page/:/etc/webserver/landing-page + certbot: + image: certbot/certbot:latest + volumes: + - ./certbot/www/:/var/www/certbot/:rw + - ./certbot/conf/:/etc/letsencrypt/:rw +``` + +`/client-cer/:/etc/nginx/client-cer/` is the designated location for the certificate authority that has signed the +client certificate. The presented client certificate will be verified against this CA. + +5. After successfully generating your certificates with the correct chain, deploying your Nginx and Hawkbit services + with appropriate configurations, and updating the settings on the device side, you will be able to establish a + certificate-based authentication mechanism. This will eliminate the necessity of sharing a security token with the + server. + +  + +##### Swupdate Suricatta Configurations + +If the client is utilizing the SWUpdate Suricatta service, the configurations on the device or client side should also +be adjusted as follows. Remember to change id, url and certificate names to your needs. + +The location of the config file is `/etc/swupdate/swupdate.conf` + +```yml +suricatta : +{ +tenant = "default"; +id = "device_id"; +url = "https://hawkbit.dev.example.com"; +nocheckcert = false; +cafile = "server_ca.crt"; +sslkey = "/etc/ssl/certs/client.key"; +sslcert = "/etc/ssl/certs/client.crt"; +}; +``` + +If your client service is a linux, you can use the command bellow to see the logs produced by the swupdate. + +```shell +journalctl --follow -u swupdate +``` + +  + +##### Testing + +You can test the communication by using the Curl command below to see if you successfully implemented mutual TLS: + +```shell +curl -L -v --cert client.crt --key client.key --cacert server_ca.crt https://hawkbit.dev.example.com/default/controller/v1/{device-id} +``` + +In the UI, after uploading an SWU package and requesting a firmware update, you can use the link below to attempt to +install the software package. + +``` +curl -L -v --cert client.crt --key client.key --cacert server_ca.crt https://hawkbit.dev.example.com/default/controller/v1/{device-id}/softwaremodules/{artifact-id}/artifacts/hawkbit_updated_5.swu --output outputfile +``` + +--- + +## DMF API + +Authentication is provided by _RabbitMQ_ [vhost and user credentials](https://www.rabbitmq.com/access-control.html) that +is used for the integration. + +--- + +## Management API + +- Basic Auth diff --git a/docs/authorization.md b/docs/authorization.md new file mode 100644 index 000000000..12ac2cba9 --- /dev/null +++ b/docs/authorization.md @@ -0,0 +1,117 @@ +# Authorization +Authorization is handled separately for _Direct Device Integration (DDI) API_ and _Device Management Federation (DMF) +API_ (where successful authentication includes full authorization) and _Management API_ and _UI_ which is based on +Spring +security [authorities](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/im/authentication/SpPermission.java). + +However, keep in mind that hawkBit does not offer an off the shelf authentication provider to leverage these permissions +and the underlying multi user/tenant capabilities of hawkBit but it supports authentication providers offering an OpenID +Connect interface. Check out [Spring security documentation](http://projects.spring.io/spring-security/) for further +information. In +hawkBit [SecurityAutoConfiguration](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-autoconfigure/src/main/java/org/eclipse/hawkbit/autoconfigure/security/SecurityAutoConfiguration.java) +is a good starting point for integration. + +The default implementation is single user/tenant with basic auth and the logged in user is provided with all +permissions. Additionally, the application properties may be configured for multiple static users; +see [Multiple Users](#multiple-users) for details. + +--- + +## DDI API + +An authenticated target is permitted to: + +- retrieve commands from the server +- provide feedback to the the server +- download artifacts that are assigned to it + +A target might be permitted to download artifacts without authentication (if enabled, see above). Only the download can +be permitted to disable the authentication. This can be used in scenarios where the artifacts itself are e.g. signed and +secured. + +--- + +## Management API and UI + +### Multiple Users + +hawkBit optionally supports configuring multiple static users through the application properties. In this case, the user +and password Spring security properties are ignored. +An example configuration is given below. +```properties +hawkbit.security.user.admin.password={noop}admin +hawkbit.security.user.admin.firstname=Test +hawkbit.security.user.admin.lastname=Admin +hawkbit.security.user.admin.email=admin@test.de +hawkbit.security.user.admin.permissions=ALL + +hawkbit.security.user.test.password={noop}test +hawkbit.security.user.test.firstname=Test +hawkbit.security.user.test.lastname=Tester +hawkbit.security.user.test.email=test@tester.com +hawkbit.security.user.test.permissions=READ_TARGET,UPDATE_TARGET,CREATE_TARGET,DELETE_TARGET +``` +A permissions value of `ALL` will provide that user with all possible permissions. Passwords need to be specified with +the used password encoder in brackets. In this example, `noop` is used as the plaintext encoder. For production use, it +is recommended to use a hash function designed for passwords such as *bcrypt*. See +this [blog post](https://spring.io/blog/2017/11/01/spring-security-5-0-0-rc1-released#password-storage-format) for more +information on password encoders in Spring Security. + +### OpenID Connect + +hawkbit supports authentication providers which use the OpenID Connect standard, an authentication layer built on top of +the OAuth 2.0 protocol. +An example configuration is given below. +```properties +spring.security.oauth2.client.registration.oidc.client-id=clientID +spring.security.oauth2.client.provider.oidc.issuer-uri=https://oidc-provider/issuer-uri +spring.security.oauth2.client.provider.oidc.jwk-set-uri=https://oidc-provider/jwk-set-uri +``` +Note: at the moment only DEFAULT tenant is supported. By default the resource_access//roles claim is mapped +to hawkBit permissions. + +### Delivered Permissions + +- READ_/UPDATE_/CREATE_/DELETE_TARGET for: + - Target entities including metadata (that includes also the installed and assigned distribution sets) + - Target tags + - Target actions + - Target registration rules + - Bulk operations + - Target filters + +- READ_/UPDATE_/CREATE_/DELETE_REPOSITORY for: + - Distribution sets + - Software Modules + - Artifacts + - DS tags + +- DOWNLOAD_REPOSITORY_ARTIFACT + - Permission to download artifacts of a software module (Note: READ_REPOSITORY allows only to read the metadata). + +- READ_TARGET_SECURITY_TOKEN + - Permission to read the target security token. The security token is security concerned and should be protected. + +- READ_TENANT_CONFIGURATION/TENANT_CONFIGURATION + - Permission to read/administrate the tenant settings. + +- READ_/UPDATE_/CREATE_/DELETE_/HANDLE_/APPROVE_ROLLOUT for: + - Managing rollouts and provision targets through a rollout. + +### Permission Matrix for example uses cases that need more than one permission + +| Use Case | Needed permissions | +|----------------------------------------------------------------------------|----------------------------------------------------------------------------| +| Search _targets_ by installed or assigned _distribution set_ | READ_REPOSITORY, READ_TARGET | +| Assign _DS_ to a _target_ | READ_REPOSITORY, UPDATE_TARGET | +| Assign DS to target through a _Rollout_, i.e. _Rollout_ creation and start | READ_REPOSITORY, READ_TARGET, READ_ROLLOUT, CREATE_ROLLOUT, HANDLE_ROLLOUT | +| Read _Rollout_ status including its _deployment groups_ | READ_REPOSITORY, READ_ROLLOUT | +| Checks _targets_ inside _Rollout deployment group_ | READ_REPOSITORY, READ_TARGET, READ_ROLLOUT | + +--- + +## Device Management Federation API + +The provided _RabbitMQ_ [vhost and user](https://www.rabbitmq.com/access-control.html) should be provided with the +necessary permissions to send messages to hawkBit through the exchange and receive messages from it through the +specified queue. diff --git a/docs/clustering.md b/docs/clustering.md new file mode 100644 index 000000000..5dab3d8c2 --- /dev/null +++ b/docs/clustering.md @@ -0,0 +1,65 @@ +# Clustering + +hawkBit is able to run in a cluster with some constraints. This guide provides insights into the basic +concepts and how to setup your own cluster. You can find additional information in the hawkBit runtime’s [README](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-monolith/hawkbit-update-server/README.md). + +--- + +### Big picture +

+ Clustering Diagram +

+ +--- + +### Events + +Event communication between nodes is based on [Spring Cloud Bus](https://cloud.spring.io/spring-cloud-bus/) and [Spring Cloud Stream](http://docs.spring.io/spring-cloud-stream/docs/current/reference/htmlsingle/). +There are different binder implementations available. The hawkBit Update Server uses the **RabbitMQ binder**. +Every node gets its own queue to receive cluster events, the default payload is JSON. If an event is thrown locally at one node, it will be automatically delivered to all other available nodes via the Spring Cloud Bus’s topic exchange. + + +

+ Clustering Diagram +

+Via the `ServiceMatcher` you can check whether an event happened locally at one node or on a different node: + +```java +serviceMatcher.isFromSelf(event) +``` + +--- + +### Caching + +Every node is maintaining its own caches independent from other nodes. +So there is no globally shared/synchronized cache instance within the cluster. + +In order to keep nodes in sync, a **TTL (time to live)** can be set for all caches to ensure that after some time the cache is refreshed from the database. +To enable the TTL just set the property `hawkbit.cache.global.ttl` (value in milliseconds). + +Of course, you can implement a shared cache, e.g. Redis. See [CacheAutoConfiguration](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-autoconfigure/src/main/java/org/eclipse/hawkbit/autoconfigure/cache/CacheAutoConfiguration.java). + +--- + +### Schedulers + +Every node has multiple schedulers which run after a defined period of time. +All schedulers always run on every node. + +This has to be kept in mind e.g. if the scheduler executes critical code which has to be executed only once. + +--- + +### Known constraints + +#### Denial-of-Service (DoS) filter + +hawkBit owns the feature of guarding itself from DoS attacks: a **DoS filter**. +It reduces the maximum number of requests per second which can be configured for read and write requests. + +This mechanism is only working for every node separately, i.e. in a cluster environment the worst-case behaviour would be that the maximum number of requests per second will be increased to its product if every request is handled by a different node. + +The same constraint exists with the validator to check if a user tried too many logins within a defined period of time. +See [DosFilter](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-rest-core/src/main/java/org/eclipse/hawkbit/rest/security/DosFilter.java). + diff --git a/docs/datamodel.md b/docs/datamodel.md new file mode 100644 index 000000000..08a4fcbd3 --- /dev/null +++ b/docs/datamodel.md @@ -0,0 +1,73 @@ +# Data model +The hawkBit data model was designed to have enough flexibility to define complex software structures (e.g. operating +system, runtimes, apps, different kind of artifacts) on one side and simplicity compared to the capabilities of a full +blown configuration management on the other. + + +It does define a hierarchy of software that starts with a distribution, which can have (sub-)modules and these may have +multiple artifacts. However, it does not consider any kind of dependency definitions between modules or artifacts. As a +result, dependency checks - if necessary - have to be done outside hawkBit, i.e. on the device itself or before the +entity creation in hawkBit by the origin. + +--- + +## Provisioning Target Definition + +A Provisioning Target is a neutral definition that may be an actual real device (e.g. gateway, embedded sensor) or a +virtual device (e.g. vehicle, smart home). + +The definition in hawkBit might reflect the transactional behavior if necessary on the device side. A vehicle might be +updated device by device or as a whole. As a result one way of defining a vehicle in hawkBit could be to have one all +inclusive Software Module or one module per (sub-) device. + +A Target can have, next to its defined properties (e.g. controller ID, target type, name, description, security token), +a generic set of attributes and meta data, both in key:value format. Target attributes are owned and managed by the +device whereas target meta data are managed by the operator. If a target is defined to be of a certain target type, then +during the assignment of a distribution set, a compatibility check will be performed between the target type and +distribution set type. + +--- + +## Software Structure Definition + +The structure defines the model of the supported software by the provisioning target + +- Distribution Set Type:defines a package structure that is supported by certain devices +- Consists of Software Module Types both for + - Firmware - device can have only one module of that type (e.g. the operating system) + - Software - device can have multiple modules of that type (e.g. "Apps") + +Software Content Definition: + +- Distribution Set: can be deployed to a provisioning target +- Software Module: is a sub element of the distribution, e.g. OS, application, firmware X, firmware Y +- Artifact: binaries for a software module. Note: the decision which artifacts have to be downloaded are done on the + device side, e.g. Full package, signatures, binary deltas + +--- + +## Entity Relationships + +The public defined entities and their relation which are reflected by the Management API. + +--- + +## Deleting and Archiving Software Modules + +When a user deletes a Software Module, the update server cannot simply remove all the corresponding data. Because when +the Software Module is already assigned to a Distribution Set or was assigned to a Target in the past, the hawkBit +server has to make sure that remains a clean and full update history for every target. The history contains all +information (e.g. name, version) of the software, which was assigned to a specific Target. Obviously storing the binary +data of the artifacts is not necessary for the history purpose. + +The delete process which is performed, when there are historical connections to targets is called SoftDelete. This +process marks the Software Module as deleted and removes the artifact, but it won't delete the meta data, which +describes the SoftwareModule and the associated Artifacts. SoftwareModules, which are marked as delete won't be visible +for the user, when he is requesting all SoftwareModules. + +Just in case there are no connections to Distribution Sets and targets the server will perform a HardDelete. This +process deletes all stored data, including all meta information. + +> In case of a SoftDelete the unique constraints are still in place, i.e. you cannot create an entity with the same +> name/key. This constraint might be removed in future versions because of the impact on the user experience (i.e. he does +> not see the soft deleted module but cannot create a new one). diff --git a/docs/device-management-federation-api.md b/docs/device-management-federation-api.md new file mode 100644 index 000000000..4de27bec5 --- /dev/null +++ b/docs/device-management-federation-api.md @@ -0,0 +1,609 @@ +# Device Management Federation API + +The DMF API provides Java classes which allows that the message body can be deserialized at runtime into a Java object. +Also Java classes can be used to serialize Java objects into JSON bodies to send a message to hawkBit. +Currently, bodies of messages are based on JSON. + +## Basics + +There are three basic concepts of AMQP: + +- Exchanges - what you publish to. +- Queues - what you consume from. +- Bindings - configuration that maps an exchange to a queue. + +**Queues** are just a place for receiving messages. +Bindings determine how messages get put in this place +Queues can also be bound to multiple exchanges. + +**Exchanges** are just publish messages. +The user decides who can produce on an exchange and who can create bindings on that exchange for delivery to a specific +queue. + +hawkBit will create all necessary queues, exchanges and bindings for the user, making it easy to get started. +The exchange name for outgoing messages is **dmf.exchange**. + +The user has to set a `reply_to` header (see chapter below), in order to specify the exchange to which hawkBit should +reply to. + +The following chapter describes the message body, header and properties. + +Note: the DMF protocol was intended to be compatible to other use cases by design. As a result, DMF uses the term * +*thing** and not **target** but they are actually synonyms in this case. + +## Messages sent **to** hawkBit + +### THING_CREATED + +Message to register and update a provisioning target. + +| Header | Description | Type | Mandatory | +|---------|------------------------------------------------|------------------------------|-----------| +| type | Type of the message | Fixed string "THING_CREATED" | true | +| thingId | The ID of the registered provisioning target | String | true | +| tenant | The tenant this provisioning target belongs to | String | true | +| sender | Name of the message sender | String | false | + +| Message Properties | Description | Type | Mandatory | +|--------------------|---------------------------------|--------|-----------| +| content_type | The content type of the payload | String | true | +| reply_to | Exchange to reply to | String | true | + +Example headers and payload: + +| Header | MessageProperties | +|--------------------------------------------------------------------------------------|--------------------------------------------------------------------| +| type=THING\_CREATED
tenant=default
thingId=abc
sender=myClient | content\_type=application/json
reply_to=myExchangeToReplyTo | + +Payload Template (optional): + +```json +{ + "name": "String", + "type": "String", + "attributeUpdate": { + "attributes": { + "exampleKey1" : "exampleValue1", + "exampleKey2" : "exampleValue2" + }, + "mode": "String" + } +} +``` + +The "name" property specifies the name of the thing, which by default is the thing ID. This property is optional.
+
+The "type" property specifies name of a target type which should be assigned to the created/updated target. The +target type with the specified name should be created in advance, otherwise it can't be assigned to the target, +resulting in: + +* error is logged +* if the target does not exist then it is created without any target type assigned +* if it exists already then no changes to its target type assignment are made. + +If the "type" property is set to a blank string while updating an existing target then any eventual target type +assignment is removed from the target. This property is optional and if omitted then no changes to the target type +assignment are made.
+
+The "attributeUpdate" property provides the attributes of the thing, for details see UPDATE_ATTRIBUTES message. This +property is optional. + +### THING_REMOVED + +Message to request the deletion of a provisioning target. + +| Header | Description | Type | Mandatory | +|---------|------------------------------------------------|------------------------------|-----------| +| type | Type of the message | Fixed string "THING_REMOVED" | true | +| thingId | The ID of the registered provisioning target | String | true | +| tenant | The tenant this provisioning target belongs to | String | false | + +| Message Properties | Description | Type | Mandatory | +|--------------------|---------------------------------|--------|-----------| +| content_type | The content type of the payload | String | true | + +Example headers + +| Header | MessageProperties | +|--------------------------------------------------------------|--------------------------------| +| type=THING\_REMOVED
tenant=default
thingId=abc | content\_type=application/json | + +### UPDATE_ATTRIBUTES + +Message to update target attributes. This message can be send in response to a REQUEST_ATTRIBUTES_UPDATE event, sent by +hawkBit. + +| Header | Description | Type | Mandatory | +|---------|----------------------------------|----------------------------------|-----------| +| type | Type of the message | Fixed string "EVENT" | true | +| topic | Topic name identifying the event | Fixed string "UPDATE_ATTRIBUTES" | true | +| thingId | The ID of the registered thing | String | true | +| tenant | The tenant this thing belongs to | String | false | + +| Message Properties | Description | Type | Mandatory | +|--------------------|---------------------------------|--------|-----------| +| content_type | The content type of the payload | String | true | + +Example header and payload: + +| Header | MessageProperties | +|--------------------------------------------------------------------------------------|---------------------------------------| +| type=EVENT
tenant=default
thingId=abc
topic=UPDATE\_ATTRIBUTES | content\_type=application/json
| + +Payload Template: + +```json +{ + "attributes": { + "exampleKey1" : "exampleValue1", + "exampleKey2" : "exampleValue2" + }, + "mode": "String" +} +``` + +The "mode" property specifies the update mode that should be applied. This property is optional. +Possible [mode](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-dmf/hawkbit-dmf-api/src/main/java/org/eclipse/hawkbit/dmf/json/model/DmfUpdateMode.java) +values: + +| Value | Description | +|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| MERGE | The target attributes specified in the payload are merged into the existing attributes. This is the default mode that is applied if no "mode" property is specified in the payload. | +| REPLACE | The existing attributes are replaced with the target attributes specified in the payload. | +| REMOVE | The target attributes specified in the payload are removed from the existing attributes. | + +### UPDATE_ACTION_STATUS + +Message to send an action status event to hawkBit. + +| Header | Description | Type | Mandatory | +|--------|----------------------------------|-------------------------------------|-----------| +| type | Type of the message | Fixed string "EVENT" | true | +| topic | Topic name identifying the event | Fixed string "UPDATE_ACTION_STATUS" | true | +| tenant | The tenant this thing belongs to | String | false | + +| Message Properties | Description | Type | Mandatory | +|--------------------|---------------------------------|--------|-----------| +| content_type | The content type of the payload | String | true | + +Payload Template (the Java representation +is [ActionUpdateStatus](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-dmf/hawkbit-dmf-api/src/main/java/org/eclipse/hawkbit/dmf/json/model/DmfActionUpdateStatus.java)): + +```json +{ + "actionId": long, + "softwareModuleId": long, + "actionStatus":"String", + "message":["String"], + "timestamp": long +} +``` + +Possible [actionStatus](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-dmf/hawkbit-dmf-api/src/main/java/org/eclipse/hawkbit/dmf/json/model/DmfActionStatus.java) +values: + +| Value | Description | +|-----------------|-----------------------------------------| +| DOWNLOAD | Device is downloading | +| DOWNLOADED | Device completed download | +| RETRIEVED | Device has retrieved the artifact | +| RUNNING | Update is running | +| FINISHED | Update process finished successful | +| ERROR | Error during update process | +| WARNING | Warning during update process | +| CANCELED | Cancel update process successful | +| CANCEL_REJECTED | Cancel update process has been rejected | + +Example header and payload: + +| Header | MessageProperties | +|-----------------------------------------------------------------------|-------------------------------| +| type=EVENT
tenant=default
topic=UPDATE\_ACTION\_STATUS | content_type=application/json | + +```json +{ + "actionId":137, + "softwareModuleId":17, + "actionStatus":"DOWNLOAD", + "message":["The download has started"], + "timestamp": 1704070800000 +} +``` + +### PING + +hawkBit allows DMF clients to check the availability of the DMF service. For this scenario DMF specifies a PING message +that can be sent by the client: + +| Header | Description | Type | Mandatory | +|--------|--------------------------------|---------------------|-----------| +| type | Type of the message | Fixed string "PING" | true | +| tenant | The tenant the PING belongs to | String | false | + +| Message Properties | Description | Type | Mandatory | +|--------------------|-----------------------------------------------------------------------------|--------|-----------| +| correlationId | CorrelationId that allows the client to map a PING request to PING_RESPONSE | String | true | + +## Messages sent **by** hawkBit + +### CANCEL_DOWNLOAD + +Message to cancel an update task. + +| Header | Description | Type | Mandatory | +|---------|------------------------------------------------|--------------------------------|-----------| +| type | Type of the message | Fixed string "Event" | true | +| thingId | The ID of the registered provisioning target | String | true | +| topic | Topic name identifying the event | Fixed string "CANCEL_DOWNLOAD" | true | +| tenant | The tenant this provisioning target belongs to | String | false | + +| Message Properties | Description | Type | Mandatory | +|--------------------|---------------------------------|--------|-----------| +| content_type | The content type of the payload | String | true | + +Payload template: + +```json +{ + "actionId": long +} +``` + +Example Headers and Payload: + +| Header | MessageProperties | +|------------------------------------------------------------------------------------|-------------------------------| +| type=EVENT
tenant=default
thingId=abc
topic=CANCEL\_DOWNLOAD | content_type=application/json | + +```json +{ +"actionId":137 +} +``` + +After sending this message, an action status event with either actionStatus=CANCELED or actionStatus=CANCEL_REJECTED has +to be returned. + +Example header and payload when cancellation is successful: + +| Header | MessageProperties | +|-----------------------------------------------------------------------|-------------------------------| +| type=EVENT
tenant=default
topic=UPDATE\_ACTION\_STATUS | content_type=application/json | + +```json +{ + "actionId":137, + "softwareModuleId":17, + "actionStatus":"CANCELED", + "message":["The update was canceled."], + "timestamp": 1704070800000 +} +``` + +Example header and payload when cancellation is rejected: + +| Header | MessageProperties | +|-----------------------------------------------------------------------|-------------------------------| +| type=EVENT
tenant=default
topic=UPDATE\_ACTION\_STATUS | content_type=application/json | + +```json +{ + "actionId":137, + "softwareModuleId":17, + "actionStatus":"CANCEL_REJECTED", + "message":["The cancellation was not possible since the target sent an unexpected response."], + "timestamp": 1704070800000 +} +``` + +### DOWNLOAD_AND_INSTALL or DOWNLOAD + +Message sent by hawkBit to initialize an update or download task. Note: in case of a maintenance window configured but +not yet active the message will have the topic _DOWNLOAD_ instead of _DOWNLOAD_AND_INSTALL_. + +| Header | Description | Type | Mandatory | +|---------|------------------------------------------------|---------------------------------------------------|-----------| +| type | Type of the message | Fixed string "EVENT" | true | +| thingId | The ID of the registered provisioning target | String | true | +| topic | Topic name identifying the event | Fixed string "DOWNLOAD_AND_INSTALL" or "DOWNLOAD" | true | +| tenant | The tenant this provisioning target belongs to | String | false | + +| Message Properties | Description | Type | Mandatory | +|--------------------|---------------------------------|--------|-----------| +| content_type | The content type of the payload | String | true | + +Payload Template (the Java representation +is [DmfDownloadAndUpdateRequest](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-dmf/hawkbit-dmf-api/src/main/java/org/eclipse/hawkbit/dmf/json/model/DmfDownloadAndUpdateRequest.java)): + +```json +{ +"actionId": long, +"targetSecurityToken": "String", +"softwareModules":[ + { + "moduleId": long, + "moduleType":"String", + "moduleVersion":"String", + "artifacts":[ + { + "filename":"String", + "urls":{ + "HTTP":"String", + "HTTPS":"String" + }, + "hashes":{ + "md5":"String", + "sha1":"String" + }, + "size":long + }], + "metadata":[ + { + "key":"String", + "value":"String" + } + ] + }] +} +``` + +Example header and payload: + +| Header | MessageProperties | +|-------------------------------------------------------------------------------------------|-------------------------------| +| type=EVENT
tenant=default
thingId=abc
topic=DOWNLOAD\_AND\_INSTALL | content_type=application/json | + +```json +{ +"actionId":137, +"targetSecurityToken":"bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY", +"softwareModules":[ + { + "moduleId":7, + "moduleType":"firmware", + "moduleVersion":"7.7.7", + "artifacts":[ + { + "filename":"artifact.zip", + "urls":{ + "HTTP":"http://download-from-url.com", + "HTTPS":"https://download-from-url.com" + }, + "hashes":{ + "md5":"md5hash", + "sha1":"sha1hash" + }, + "size":512 + }], + "metadata":[ + { + "key":"installationType", + "value":"5784K#" + } + ] + }] +} +``` + +### MULTI_ACTION + +If `multi.assignments.enabled` is enabled, this message is sent instead of DOWNLOAD_AND_INSTALL, DOWNLOAD, or +CANCEL_DOWNLOAD +by hawkBit to initialize update, download, or cancel task(s). + +With weight, one can set the priority to the action. The higher the weight, the higher is the priority of an action. + +| Header | Description | Type | Mandatory | +|---------|------------------------------------------------|-----------------------------|-----------| +| type | Type of the message | Fixed string "EVENT" | true | +| thingId | The ID of the registered provisioning target | String | true | +| topic | Topic name identifying the event | Fixed string "MULTI_ACTION" | true | +| tenant | The tenant this provisioning target belongs to | String | false | + +| Message Properties | Description | Type | Mandatory | +|--------------------|---------------------------------|--------|-----------| +| content_type | The content type of the payload | String | true | + +Payload Template (the Java representation +is [DmfMultiActionRequest](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-dmf/hawkbit-dmf-api/src/main/java/org/eclipse/hawkbit/dmf/json/model/DmfMultiActionRequest.java)): + +```json +[{ +"topic": "String", +"weight": long, +"action": { + "actionId": long, + "targetSecurityToken": "String", + "softwareModules":[ + { + "moduleId": long, + "moduleType":"String", + "moduleVersion":"String", + "artifacts":[ + { + "filename":"String", + "urls":{ + "HTTP":"String", + "HTTPS":"String" + }, + "hashes":{ + "md5":"String", + "sha1":"String" + }, + "size":long + }], + "metadata":[ + { + "key":"String", + "value":"String" + } + ] + }] + } +}, +{ +"topic": "String", +"weight": long, +"action": { + "actionId": long, + "targetSecurityToken": "String", + "softwareModules":[ + { + "moduleId": long, + "moduleType":"String", + "moduleVersion":"String", + "artifacts":[ + { + "filename":"String", + "urls":{ + "HTTP":"String", + "HTTPS":"String" + }, + "hashes":{ + "md5":"String", + "sha1":"String" + }, + "size":long + }], + "metadata":[ + { + "key":"String", + "value":"String" + } + ] + }] + } +}] +``` + +Example header and payload: + +| Header | MessageProperties | +|----------------------------------------------------------------------------------|-------------------------------| +| type=EVENT
tenant=default
thingId=abc
topic=MULTI\_ACTION | content_type=application/json | + +```json +[{ +"topic": "DOWNLOAD_AND_INSTALL", +"weight": 600, +"action": { + "actionId":137, + "targetSecurityToken":"bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY", + "softwareModules":[ + { + "moduleId":7, + "moduleType":"firmware", + "moduleVersion":"7.7.7", + "artifacts":[ + { + "filename":"artifact.zip", + "urls":{ + "HTTP":"http://download-from-url.com", + "HTTPS":"https://download-from-url.com" + }, + "hashes":{ + "md5":"md5hash", + "sha1":"sha1hash" + }, + "size":512 + }], + "metadata":[ + { + "key":"installationType", + "value":"5784K#" + } + ] + }] + } +}, +{ +"topic": "DOWNLOAD", +"weight": 500, +"action": { + "actionId":138, + "targetSecurityToken":"bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY", + "softwareModules":[ + { + "moduleId":4, + "moduleType":"firmware", + "moduleVersion":"7.7.9", + "artifacts":[ + { + "filename":"artifact.zip", + "urls":{ + "HTTP":"http://download-from-url.com", + "HTTPS":"https://download-from-url.com" + }, + "hashes":{ + "md5":"md5hash", + "sha1":"sha1hash" + }, + "size":512 + }], + "metadata":[ + { + "key":"installationType", + "value":"5784K#" + } + ] + }] + } +}] +``` + +### THING_DELETED + +Message sent by hawkBit when a target has been deleted. + +| Header | Description | Type | Mandatory | +|---------|------------------------------------------------|------------------------------|-----------| +| type | Type of the message | Fixed string "THING_DELETED" | true | +| thingId | The ID of the registered provisioning target | String | true | +| tenant | The tenant this provisioning target belongs to | String | true | + +Example header: + +| Header | MessageProperties | +|--------------------------------------------------------------|-------------------| +| type=THING\_DELETED
tenant=default
thingId=abc | | + +### REQUEST_ATTRIBUTES_UPDATE + +Message sent by Eclipse hawkBit when a re-transmission of target attributes is requested. + +| Header | Description | Type | Mandatory | +|---------|------------------------------------------------|------------------------------------------|-----------| +| type | Type of the message | Fixed string "EVENT" | true | +| thingId | The ID of the registered provisioning target | String | true | +| topic | Topic name identifying the event | Fixed string "REQUEST_ATTRIBUTES_UPDATE" | true | +| tenant | The tenant this provisioning target belongs to | String | true | + +Example headers: + +| Header | MessageProperties | +|----------------------------------------------------------------------------------------------|-------------------| +| type=EVENT
tenant=default
thingId=abc
topic=REQUEST\_ATTRIBUTES\_UPDATE | | + +### PING_RESPONSE + +_hawkBit_ will respond to the PING message with a PING_RESPONSE type message that has the same correlationId as the +original PING message: + +| Header | Description | Type | Mandatory | +|--------|--------------------------------|------------------------------|-----------| +| type | Type of the message | Fixed string "PING_RESPONSE" | true | +| tenant | The tenant the PING belongs to | String | false | + +| Message Properties | Description | Type | Mandatory | +|--------------------|--------------------------------------------|--------|-----------| +| correlationId | CorrelationId of the original PING request | String | true | +| content_type | The content type of the payload | String | true | + +The PING_RESPONSE also contains a timestamp (i.e. the difference, measured in milliseconds, between the current time and +midnight, January 1, 1970 UTC) as plain text. It is not guaranteed that this timestamp is completely accurate. + +| Header | MessageProperties | +|-------------------------------------------|-------------------------| +| type=PING_RESPONSE
tenant=default | content_type=text/plain | + + diff --git a/docs/direct-device-integration-api.md b/docs/direct-device-integration-api.md new file mode 100644 index 000000000..6d50947c6 --- /dev/null +++ b/docs/direct-device-integration-api.md @@ -0,0 +1,55 @@ +# Direct Device Integration API + +The hawkBit [update server](management-api) provides REST resources which are consumed by the device to retrieve software update tasks. +This API is based on HTTP standards and a polling mechanism. + +--- + +> ℹ️ **Note**: In DDI the target is identified using a **controllerId**. +> Controller is used as a term for the actual service/client on the device. +> That allows users to have in some cases even multiple clients on the same target for different tasks, e.g. Firmware update and App management. + +--- + +### State Machine Mapping + +For historical reasons the DDI has a different state machine and status messages than the [Target State Machine](targetstate) of the hawkBit update server. + +This is kept in order to ensure that *DDI* stays compatible for devices out there in the field. +A future version “2” of *DDI* might change that. +*DDI* also defines more states than the update server, e.g. multiple DDI states are currently mapped by the *DDI* implementation to **RUNNING** state. +It is possible that in the future hawkBit will fully leverage these additional states. + +The *DDI* API allows the device to provide the following feedback messages: + +| **DDI `status.execution` type** | **Handling by update server** | **Mapped ActionStatus type** | +|--------------------------------|--------------------------------|-------------------------------| +| CANCELED | This is sent by the target as confirmation of a cancellation request by the update server. | CANCELED | +| REJECTED | This is sent by the target in case an update or cancellation is rejected, i.e. cannot be fulfilled at this point in time. Note: the target should send a CLOSED→ERROR if it believes it will not be able to proceed the action at all. | WARNING | +| CLOSED | Target completes the action either with [`status.result.finished`](../status-result-finished.md) SUCCESS or FAILURE as result. Note: DDI defines also a status NONE which will not be interpreted by the update server and handled like SUCCESS. | **ERROR** (DDI FAILURE) or **FINISHED** (DDI SUCCESS or NONE) | +| DOWNLOAD | This can be used by the target to inform that it is downloading artifacts of the action. | DOWNLOAD | +| DOWNLOADED | This can be used by the target to inform that it has downloaded artifacts of the action. | DOWNLOADED | +| PROCEEDING | This can be used by the target to inform that it is working on the action. | RUNNING | +| SCHEDULED | This can be used by the target to inform that it scheduled the action. | RUNNING | +| RESUMED | This can be used by the target to inform that it continued to work on the action. | RUNNING | + +--- + +See this [issue](https://github.com/eclipse-hawkbit/hawkbit/issues/xxx) for additional information, concerning the cancellation of updates. +To finally accept a cancellation, you must send a `closed` status.execution type. + +## REST Doc +
+ +
+ + diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 000000000..f1779211c --- /dev/null +++ b/docs/features.md @@ -0,0 +1,66 @@ +# Features + +--- + +## Device and Software Repository + +- Repository that holds the provisioning targets and assignable software distributions. +- Targets can be logically grouped by **Target Types**. +- Includes a full software update history for every device. +- Supports pre-commission devices in the repository and plug and play (device is created when it authenticates for the first time). + +--- + +## Update Management + +- Directly deploy a defined software distribution to a device (via Management API). +- Update handling is independent of device type, integration approach, or connectivity. +- Optional user consent flow: download and install updates only after the respective end user has confirmed it. +- Mass cancel distribution of an update by invalidating the distribution set. +- Use action status codes for easier analysis. + +--- + +## Artifact Content Delivery + +- Partial downloads supported. +- Download resume supported (RFC7233). +- Content management by RESTful API and UI. +- Authorization based on software assignment (a device can only download what was assigned to it). +- Delta artifact hosting supported. +- Artifact signature hosting supported. +- Plug-point for artifact encryption (allows encryption of artifacts on upload). + +--- + +## Rollout [Campaign] Management + +- Secure handling of large volumes of devices at rollout creation time. +- Flexible deployment group definition as part of a rollout. +- Monitoring of rollout progress. +- Emergency rollout shutdown in case of update failures. +- Manually trigger the next rollout group. + +--- + +## Interfaces + +### Management API +- RESTful API. +- Create/Read/Update/Delete operations for provisioning targets (devices) and repository content (software). +- Manage and monitor software update operations. +- Online API documentation. +- JSON payload with Hypermedia support. +- Supports filtering, sorting, and paging. + +### Direct Device Integration API +- RESTful HTTP-based API for direct device integration. +- JSON payload. +- Traffic optimized (content-based ETag generation, not modified). +- Feedback channel from device. +- TLS encryption. + +### Device Management Federation API +- Indirect device integration through a device management service or application into hawkBit. +- Optimized for high service-to-service throughput with AMQP messaging interface. +- Separate AMQP vHost per tenant for maximum security. diff --git a/docs/feign-client.md b/docs/feign-client.md new file mode 100644 index 000000000..4975320b3 --- /dev/null +++ b/docs/feign-client.md @@ -0,0 +1,69 @@ +# Feign Client + +In this guide we describe how to create a **Feign REST Client** based on a Spring Boot Application. + +--- + +### Create Feign REST Client + +hawkBit provides REST interfaces for **Management API** and **DDI API**. Using these interfaces you can create a Feign client with the help of the *Feign inheritance support*. +Our example modules demonstrate how to create Feign client resources. Here you can find the [Management API client resources](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-mgmt-api) and the [DDI client resources](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-ddi-api). +A small simulator application demonstrates how you can interact with hawkBit via the [Management API](http://www.eclipse.org/hawkbit/documentation/interfaces/management-api.html). + +--- + +### Example Management API Simulator + +In the following code section, you can see a Feign client resource example. +The interface extends the origin API interface to declare the `@FeignClient`. +The `@FeignClient` declares that a REST client with that interface should be created. + +This interface can be autowired and used as a normal Java interface: + +```java +@FeignClient(url = "${hawkbit.url:localhost:8080}/" + MgmtRestConstants.TARGET_V1_REQUEST_MAPPING) +public interface MgmtTargetClientResource extends MgmtTargetRestApi { +} + +public class CreateStartedRolloutExample { + + @Autowired + private MgmtTargetClientResource targetResource; + + public void run() { + + // create ten targets + targetResource.createTargets(new TargetBuilder().controllerId("00-FF-AA-0").name("00-FF-AA-0") + .description("Targets used for rollout example").buildAsList(10)); + } +} +``` + +Example projects: +- [hawkbit-example-mgmt-feign-client](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-mgmt-feign-client) +- [hawkbit-example-ddi-feign-client](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-ddi-feign-client) +- [hawkbit-example-mgmt-simulator](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-mgmt-simulator) + +--- + +### Feign Client Configuration + +At [`hawkbit-example-core-feign-client`](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-core-feign-client) there is a Spring configuration to auto configure some beans, which can be reused for your own Feign client: + +```java +@Configuration +@ConditionalOnClass(Feign.class) +@Import(FeignClientsConfiguration.class) +public class FeignClientConfiguration { + + @Bean + public ApplicationJsonRequestHeaderInterceptor jsonHeaderInterceptor() { + return new ApplicationJsonRequestHeaderInterceptor(); + } + + @Bean + public Contract feignContract() { + return new IgnoreMultipleConsumersProducersSpringMvcContract(); + } +} +``` diff --git a/docs/images/deploymnet-group-state-machine.png b/docs/images/deploymnet-group-state-machine.png new file mode 100644 index 000000000..32e39ee69 Binary files /dev/null and b/docs/images/deploymnet-group-state-machine.png differ diff --git a/docs/images/eclipse_foundation_logo.png b/docs/images/eclipse_foundation_logo.png new file mode 100644 index 000000000..fe2c278ef Binary files /dev/null and b/docs/images/eclipse_foundation_logo.png differ diff --git a/docs/images/eventing-within-cluster.png b/docs/images/eventing-within-cluster.png new file mode 100644 index 000000000..1baa538d1 Binary files /dev/null and b/docs/images/eventing-within-cluster.png differ diff --git a/docs/images/exampleReverseProxyArchitecture.png b/docs/images/exampleReverseProxyArchitecture.png new file mode 100644 index 000000000..dec5e6f30 Binary files /dev/null and b/docs/images/exampleReverseProxyArchitecture.png differ diff --git a/docs/images/hawkBit_overview.jpeg b/docs/images/hawkBit_overview.jpeg new file mode 100644 index 000000000..c16b20d88 Binary files /dev/null and b/docs/images/hawkBit_overview.jpeg differ diff --git a/docs/images/hawkbit_logo.png b/docs/images/hawkbit_logo.png new file mode 100644 index 000000000..3fe796127 Binary files /dev/null and b/docs/images/hawkbit_logo.png differ diff --git a/docs/images/overall_cluster.png b/docs/images/overall_cluster.png new file mode 100644 index 000000000..b18b8ee21 Binary files /dev/null and b/docs/images/overall_cluster.png differ diff --git a/docs/images/packagemodel.png b/docs/images/packagemodel.png new file mode 100644 index 000000000..f9c6f1775 Binary files /dev/null and b/docs/images/packagemodel.png differ diff --git a/docs/images/rollout-state-machine.png b/docs/images/rollout-state-machine.png new file mode 100644 index 000000000..80a3fe465 Binary files /dev/null and b/docs/images/rollout-state-machine.png differ diff --git a/docs/images/rollout.png b/docs/images/rollout.png new file mode 100644 index 000000000..984e12152 Binary files /dev/null and b/docs/images/rollout.png differ diff --git a/docs/images/targetStatusStates.png b/docs/images/targetStatusStates.png new file mode 100644 index 000000000..db14fef74 Binary files /dev/null and b/docs/images/targetStatusStates.png differ diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 000000000..748682fcf --- /dev/null +++ b/docs/index.html @@ -0,0 +1,234 @@ + + + + + + Document + + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/management-api.md b/docs/management-api.md new file mode 100644 index 000000000..087b727b5 --- /dev/null +++ b/docs/management-api.md @@ -0,0 +1,64 @@ +# Management API + +The Management API is a RESTful API that enables to perform Create/Read/Update/Delete operations for provisioning targets (i.e. devices) and repository content (i.e. software). +Based on the Management API you can manage and monitor software update operations via HTTP/HTTPS. The Management API supports JSON payload with hypermedia as well as filtering, sorting and paging. Furthermore the Management API provides permission based access control and standard roles as well as custom role creation. +The API is protected and needs authentication and authorization based on the security concept. + +--- + +### API Version +hawkBit provides an consistent Management API interface that guarantees backwards compatibility for future releases by version control. +The current version of the Management API is `version 1 (v1)` with the URI `http://localhost:8080/rest/v1/` + +### API Resources +**Supported HTTP-methods:** +- `GET` +- `POST` +- `PUT` +- `DELETE` + +### Headers +For all requests an `Authorization` header has to be set. +- Username: `username` +- Password: `password` +Also have a look to the Security chapter. +In addition, for `POST` and `PUT` requests the `Content-Type` header has to be set. Accepted content-types are. +- `application/json` +- `application/hal+json` + + +### Request Body +Besides the relevant data (`name`, `description`, `createdBy` etc.) of a resource entity, a resource entity also has URIs `_links` to linked resource entities. +A Distribution Set entity may have for example URIs to artifacts, Software Modules, Software Module Types and metadata. +```json +"_links": { + "artifacts": { + "href": "http://localhost:8080/rest/v1/softwaremodules/83/artifacts" + }, + "self": { + "href": "http://localhost:8080/rest/v1/softwaremodules/83" + }, + "type": { + "href": "http://localhost:8080/rest/v1/softwaremoduletypes/43" + }, + "metadata": { + "href": "http://localhost:8080/rest/v1/softwaremodules/83/metadata?offset=0&limit=50" + } +``` + + +## REST Doc +
+ +
+ + \ No newline at end of file diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 000000000..ab7a058d9 --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,171 @@ +# Quick Start + +--- + +## From Docker Image + +#### Overview +HawkBit Update Server default user has **admin/admin** as default credentials. +See below how the user can be changed. + +It supports two configurations: + +- **monolith** – `hawkbit-update-server` +- **micro-service** – `hawkbit-mgmt-server`, `hawkbit-ddi-server`, `hawkbit-dmf-server` + +--- + +#### A: Run hawkBit Update Server (Monolith) as Docker Container + +Start the hawkBit Update Server as a single container: + +```bash +$ docker run -p 8080:8080 hawkbit/hawkbit-update-server:latest +``` + +This will start hawkBit update server with an embedded H2 database for evaluation purposes. + +--- + +#### B: Run hawkBit Update Server (Monolith) with services as Docker Compose + +Start the hawkBit Update Server together with a PostgreSQL and RabbitMQ instance as containers: + +```bash +$ git clone https://github.com/eclipse-hawkbit/hawkbit.git +$ cd hawkbit/docker +$ docker-compose -f docker-compose-monolith-postgres.yml up -d +``` + +or with MySQL: + +```bash +$ git clone https://github.com/eclipse-hawkbit/hawkbit.git +$ cd hawkbit/docker +$ docker-compose -f docker-compose-monolith-mysql.yml up -d +``` + +If you want to start also the Simple UI, you can use, for PostgreSQL: + +```bash +$ git clone https://github.com/eclipse-hawkbit/hawkbit.git +$ cd hawkbit/docker +$ docker-compose -f docker-compose-monolith-with-simple-ui-postgres.yml up -d +``` + +or with MySQL: + +```bash +$ git clone https://github.com/eclipse-hawkbit/hawkbit.git +$ cd hawkbit/docker +$ docker-compose -f docker-compose-monolith-with-simple-ui-mysql.yml up -d +``` + +> **Note:** `-d` flag is used to run the containers in detached mode. +> If you want to see the logs, you can remove the flag. + +--- + +#### C: Run hawkBit Update Server (Micro-Service) with services as Docker Compose + +Start the hawkBit Update Server together with a PostgreSQL and RabbitMQ instance as containers: + +```bash +$ git clone https://github.com/eclipse-hawkbit/hawkbit.git +$ cd hawkbit/docker +$ docker-compose -f docker-compose-micro-services-postgres.yml up -d +``` + +or with MySQL: + +```bash +$ git clone https://github.com/eclipse-hawkbit/hawkbit.git +$ cd hawkbit/docker +$ docker-compose -f docker-compose-micro-services-mysql.yml up -d +``` + +If you want to start also the Simple UI, you can use, for PostgreSQL: + +```bash +$ git clone https://github.com/eclipse-hawkbit/hawkbit.git +$ cd hawkbit/docker +$ docker-compose -f docker-compose-micro-services-with-simple-ui-postgres.yml up -d +``` + +or with MySQL: + +```bash +$ git clone https://github.com/eclipse-hawkbit/hawkbit.git +$ cd hawkbit/docker +$ docker-compose -f docker-compose-micro-services-with-simple-ui-mysql.yml up -d +``` + +> **Note:** `-d` flag is used to run the containers in detached mode. +> If you want to see the logs, you can remove the flag. + +--- + +## From Sources + +#### 1: Clone and build hawkBit + +```bash +$ git clone https://github.com/eclipse-hawkbit/hawkbit.git +$ cd hawkbit +$ mvn clean install -DskipTests +``` + +--- + +#### 2: Start hawkBit   [Update Server](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-monolith/hawkbit-update-server) (Monolith) + +```bash +$ java -jar ./hawkbit-monolith/hawkbit-update-server/target/hawkbit-update-server-0-SNAPSHOT.jar +``` + +> **Note:** you could start it also in **microservices mode** by: + +```bash +$ java -jar ./hawkbit-mgmt/hawkbit-mgmt-server/target/hawkbit-mgmt-server-0-SNAPSHOT.jar +$ java -jar ./hawkbit-ddi/hawkbit-ddi-server/target/hawkbit-ddi-server-0-SNAPSHOT.jar +$ java -jar ./hawkbit-dmf/hawkbit-dmf-server/target/hawkbit-dmf-server-0-SNAPSHOT.jar +``` + +And (only if you want to use the DMF feature): + +```bash +$ java -jar ./hawkbit-monolith/hawkbit-update-server/target/hawkbit-update-server-0-SNAPSHOT.jar +``` + +You could also start the **Simple UI** by: + +```bash +$ java -jar ./hawkbit-simple-ui/target/hawkbit-simple-ui-0-SNAPSHOT.jar +``` + +--- + +## Configuration + +#### Change credentials + +As stated before, the default user is **admin/admin**. +It can be overridden by changing the [`TenantAwareUserProperties`](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-core/src/main/java/org/eclipse/hawkbit/tenancy/TenantAwareUserProperties.java) configuration using Spring. + +For instance, using a properties file like: + +```properties +# should remove the admin/admin user +hawkbit.security.user.admin.tenant=#{null} +hawkbit.security.user.admin.password=#{null} +hawkbit.security.user.admin.roles=#{null} + +# should add a hawkbit/isAwesome! user +hawkbit.security.user.hawkbit.tenant=DEFAULT +hawkbit.security.user.hawkbit.password={noop}isAwesome! +hawkbit.security.user.hawkbit.roles=TENANT_ADMIN +``` + +This will remove the default `admin/admin` user and add a user `hawkbit` with password `isAwesome!` and role `TENANT_ADMIN`. + +You can create multiple users with specified roles. diff --git a/docs/release-notes.md b/docs/release-notes.md new file mode 100644 index 000000000..db9fed6b3 --- /dev/null +++ b/docs/release-notes.md @@ -0,0 +1,12 @@ +# Release notes + +> Loading releases from GitHub… + +If this message stays for more than a few seconds, check your network connection or GitHub API rate limits. + +- Direct link to releases (fallback): https://github.com/eclipse-hawkbit/hawkbit/releases + + diff --git a/docs/rest-api/ddi.html b/docs/rest-api/ddi.html new file mode 100644 index 000000000..6a4a942f2 --- /dev/null +++ b/docs/rest-api/ddi.html @@ -0,0 +1,862 @@ + + + + + + hawkBit REST APIs + + + + + + + + + +
API docs by Redocly

hawkBit REST APIs (v1)

Download OpenAPI specification:Download

Eclipse hawkBit™ is a domain-independent back-end framework for rolling out software updates to constrained edge devices as well as more powerful controllers and gateways connected to IP based networking infrastructure.

+

DDI Root Controller

REST resource handling for root controller CRUD operations

+

Set offline assigned version

Allow to set current running version. +This method is EXPERIMENTAL and may change in future releases.

+
path Parameters
tenant
required
string
controllerId
required
string
Request Body schema:
required
name
required
string

Distribution Set name

+
version
required
string

Distribution set version

+

Responses

Request samples

Content type
{
  • "name": "linux",
  • "version": "1.2.3"
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Feedback channel for the config data action

The usual behaviour is that when a new device registers at the server it is requested to provide the meta +information that will allow the server to identify the device on a hardware level (e.g. hardware revision, +mac address, serial number etc.).

+
path Parameters
tenant
required
string
controllerId
required
string
Request Body schema:
required
required
object

Link which is provided whenever the provisioning target or device is supposed to push its configuration data (aka. "controller attributes") to the server. Only shown for the initial configuration, after a successful update action, or if requested explicitly (e.g. via the management UI).

+
mode
string
Enum: "merge" "replace" "remove"

Optional parameter to specify the update mode that should be applied when updating target attributes. Valid values are 'merge', 'replace', and 'remove'. Defaults to 'merge'.

+

Responses

Request samples

Content type
{
  • "mode": "merge",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Feedback channel for the DeploymentBase action

Feedback channel. It is up to the device how much intermediate feedback is provided. +However, the action will be kept open until the controller on the device reports a finished (either successful +or error).

+
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
Request Body schema:
required
required
object (DdiStatus)

Target action status

+
timestamp
integer <int64>

Timestamp (in milliseconds) when this status change occurred on Device.

+

Responses

Request samples

Content type
{
  • "status": {
    },
  • "timestamp": 1627997501890
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Feedback channel for actions waiting for confirmation

The device will use this resource to either confirm or deny an action which is waiting for confirmation. The +action will be transferred into the RUNNING state in case the device is confirming it. Afterwards it will be +exposed by the deploymentBase.

+
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
Request Body schema:
required
confirmation
required
string
Enum: "confirmed" "denied"

Action confirmation state

+
code
integer <int32>

(Optional) Individual status code

+
details
Array of strings

List of detailed message information

+

Responses

Request samples

Content type
{
  • "confirmation": "confirmed",
  • "code": 200,
  • "details": [
    ]
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Interface to deactivate auto-confirmation for a specific controller

The device can use this resource to deactivate auto-confirmation. All active actions will remain unchanged +while all future actions need to be confirmed, before processing with the deployment.

+
path Parameters
tenant
required
string
controllerId
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Interface to activate auto-confirmation for a specific device

The device can use this resource to activate auto-confirmation. As a result all current active as well as +future actions will automatically be confirmed by mentioning the initiator as triggered person. Actions will +be automatically confirmed, as long as auto-confirmation is active.

+
path Parameters
tenant
required
string
controllerId
required
string
Request Body schema:
initiator
string

Individual value (e.g. username) stored as initiator and automatically used as confirmed user in future actions

+
remark
string

Individual value to attach a remark which will be persisted when automatically confirming future actions

+

Responses

Request samples

Content type
{
  • "initiator": "exampleUser",
  • "remark": "exampleRemark"
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Feedback channel for cancel actions

It is up to the device how much intermediate feedback is provided. However, the action will be kept open +until the controller on the device reports a finished (either successful or error) or rejects the action, +e.g. the canceled actions have been started already.

+
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
Request Body schema:
required
required
object (DdiStatus)

Target action status

+
timestamp
integer <int64>

Timestamp (in milliseconds) when this status change occurred on Device.

+

Responses

Request samples

Content type
{
  • "status": {
    },
  • "timestamp": 1627997501890
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Root resource for an individual Target

This base resource can be regularly polled by the controller on the provisioning target or device in order to +retrieve actions that need to be executed. Those are provided as a list of links to give more detailed +information about the action. Links are only available for initial configuration, open actions, or the latest +installed action, respectively. The resource supports Etag based modification checks in order to save traffic.

+

Note: deployments have to be confirmed in order to move on to the next action. Cancellations have to be +confirmed or rejected.

+
path Parameters
tenant
required
string
controllerId
required
string

Responses

Response samples

Content type
{}

Return all artifacts of a given software module and target

Returns all artifacts that are assigned to the software module

+
path Parameters
tenant
required
string
controllerId
required
string
softwareModuleId
required
integer <int64>

Responses

Response samples

Content type
[]

Artifact download

Handles GET DdiArtifact download request. This could be full or partial (as specified by RFC7233 (Range Requests)) download request.

+
path Parameters
tenant
required
string
controllerId
required
string
softwareModuleId
required
integer <int64>
fileName
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

MD5 checksum download

Handles GET {@link DdiArtifact} MD5 checksum file download request.

+
path Parameters
tenant
required
string
controllerId
required
string
softwareModuleId
required
integer <int64>
fileName
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Previously installed action

Resource to receive information of the previous installation. Can be used to re-retrieve artifacts of +the already finished action, for example in case a re-installation is necessary. The response will be of +the same format as the deploymentBase operation, providing the previous action that has been finished +successfully. As the action is already finished, no further feedback is expected.

+

Keep in mind that the provided download links for the artifacts are generated dynamically by the update server. +Host, port and path are not guaranteed to be similar to the provided examples below but will be defined at +runtime.

+
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
query Parameters
actionHistory
integer <int32>
Default: 0

Responses

Response samples

Content type
{}

Resource for software module (Deployment Base)

Core resource for deployment operations. Contains all information necessary in order to execute the operation.

+

Keep in mind that the provided download links for the artifacts are generated dynamically by the update server. +Host, port and path and not guaranteed to be similar to the provided examples below but will be defined at +runtime.

+
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
query Parameters
c
integer <int32>
Default: -1
actionHistory
integer <int32>
Default: 0

(Optional) GET parameter to retrieve a given number of messages which are previously provided by the +device. Useful if the devices sent state information to the feedback channel and never stored them +locally.

+

Responses

Response samples

Content type
{}

Resource to request confirmation specific information for the controller

Core resource for confirmation related operations. While active actions awaiting confirmation will be +referenced, the current auto-confirmation status will be shown. In case auto-confirmation is active, details +like the initiator, remark and date of activation (as unix timestamp) will be provided. +Reference links to switch the auto-confirmation state are exposed as well.

+
path Parameters
tenant
required
string
controllerId
required
string

Responses

Response samples

Content type
{}

Confirmation status of an action

Resource to receive information about a pending confirmation. The response will be of the same format as the +deploymentBase operation. The controller should provide feedback about the confirmation first, before +processing the deployment.

+

Keep in mind that the provided download links for the artifacts are generated dynamically by the update server. +Host, port and path are not guaranteed to be similar to the provided examples below but will be defined at +runtime.

+
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
query Parameters
c
integer <int32>
Default: -1
actionHistory
integer <int32>
Default: 0

Responses

Response samples

Content type
{}

Cancel an action

The Hawkbit server might cancel an operation, e.g. an unfinished update has a successor. It is up to the +provisioning target to decide to accept the cancelation or reject it.

+
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>

Responses

Response samples

Content type
{
  • "id": "11",
  • "cancelAction": {
    }
}
+ + + + diff --git a/docs/rest-api/mgmt.html b/docs/rest-api/mgmt.html new file mode 100644 index 000000000..7fb936b78 --- /dev/null +++ b/docs/rest-api/mgmt.html @@ -0,0 +1,3917 @@ + + + + + + hawkBit REST APIs + + + + + + + + + +
API docs by Redocly

hawkBit REST APIs (v1)

Download OpenAPI specification:Download

Eclipse hawkBit™ is a domain-independent back-end framework for rolling out software updates to constrained edge devices as well as more powerful controllers and gateways connected to IP based networking infrastructure.

+

Distribution Sets

REST Resource handling for DistributionSet CRUD operations.

+

Return single Distribution Set

Handles the GET request of retrieving a single distribution set. Required permission: READ_REPOSITORY

+
path Parameters
distributionSetId
required
integer <int64>

Responses

Response samples

Content type
{
  • "createdBy": "bumlux",
  • "createdAt": 1682408574924,
  • "lastModifiedBy": "bumlux",
  • "lastModifiedAt": 1682408574925,
  • "name": "DS",
  • "description": "Updated Desc: 2LaONizh7WZp0on6XEOZI9AwEYIjj77YZskEmA2LVrKtAOXj9vvqACopEghLMqt6DIWpIahn6XM4jUlRZ1T5SZS2NWMuWHGoFIg1",
  • "version": "1.0",
  • "modules": [
    ],
  • "requiredMigrationStep": false,
  • "type": "test_default_ds_type",
  • "typeName": "OS (FW) mandatory, runtime (FW) and app (SW) optional",
  • "complete": true,
  • "deleted": false,
  • "valid": true,
  • "_links": {},
  • "id": 6
}

Update Distribution Set

Handles the UPDATE request for a single Distribution Set. Required permission: UPDATE_REPOSITORY

+
path Parameters
distributionSetId
required
integer <int64>
Request Body schema:
required
name
string

The name of the entity

+
description
string

The description of the entity

+
version
string

Package version

+
locked
boolean

Should be set only if change of locked state is requested. If put, the distribution set locked flag will be +set to the requested. Note: unlock (i.e. set this property to false) with extreme care! +In general once distribution set is locked it shall not be unlocked. Note that it could have been assigned / +deployed to targets.

+
requiredMigrationStep
boolean

True if DS is a required migration step for another DS. As a result the DS’s assignment will not be cancelled +when another DS is assigned (note: updatable only if DS is not yet assigned to a target)

+

Responses

Request samples

Content type
{
  • "name": "dsOne",
  • "description": "Description of the distribution set.",
  • "version": "1.0.0",
  • "locked": true,
  • "requiredMigrationStep": false
}

Response samples

Content type
{
  • "createdBy": "bumlux",
  • "createdAt": 1682408574924,
  • "lastModifiedBy": "bumlux",
  • "lastModifiedAt": 1682408574925,
  • "name": "DS",
  • "description": "Updated Desc: 2LaONizh7WZp0on6XEOZI9AwEYIjj77YZskEmA2LVrKtAOXj9vvqACopEghLMqt6DIWpIahn6XM4jUlRZ1T5SZS2NWMuWHGoFIg1",
  • "version": "1.0",
  • "modules": [
    ],
  • "requiredMigrationStep": false,
  • "type": "test_default_ds_type",
  • "typeName": "OS (FW) mandatory, runtime (FW) and app (SW) optional",
  • "complete": true,
  • "deleted": false,
  • "valid": true,
  • "_links": {},
  • "id": 6
}

Delete Distribution Set by Id

Handles the DELETE request for a single Distribution Set. Required permission: DELETE_REPOSITORY

+
path Parameters
distributionSetId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return single meta data value for a specific key of a Distribution Set

Get a single meta data value for a meta data key. Required permission: READ_REPOSITORY

+
path Parameters
distributionSetId
required
integer <int64>
metadataKey
required
string

Responses

Response samples

Content type
application/json
{
  • "key": "someKnownKey",
  • "value": "someKnownKeyValue"
}

Update single meta data value of a distribution set

Update a single meta data value for speficic key. Required permission: UPDATE_REPOSITORY

+
path Parameters
distributionSetId
required
integer <int64>
metadataKey
required
string
Request Body schema: application/json
required
value
string

Responses

Request samples

Content type
application/json
{
  • "value": "someValue"
}

Response samples

Content type
{
  • "key": "someKnownKey",
  • "value": "someKnownKeyValue"
}

Delete a single meta data entry from the distribution set

Delete a single meta data. Required permission: UPDATE_REPOSITORY

+
path Parameters
distributionSetId
required
integer <int64>
metadataKey
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all Distribution Sets

Handles the GET request of retrieving all distribution sets. Required permission: READ_REPOSITORY

+
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{
  • "content": [
    ],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Creates new Distribution Sets

Handles the POST request of creating new distribution sets within Hawkbit. The request body must always be a list of sets. Required permission: CREATE_REPOSITORY

+
Request Body schema:
required
Array
name
string

The name of the entity

+
description
string

The description of the entity

+
version
string

Package version

+
locked
boolean

Should be set only if change of locked state is requested. If put, the distribution set locked flag will be +set to the requested. Note: unlock (i.e. set this property to false) with extreme care! +In general once distribution set is locked it shall not be unlocked. Note that it could have been assigned / +deployed to targets.

+
requiredMigrationStep
boolean

True if DS is a required migration step for another DS. As a result the DS’s assignment will not be cancelled +when another DS is assigned (note: updatable only if DS is not yet assigned to a target)

+
Array of objects (MgmtSoftwareModuleAssignment)
type
string

The type of the distribution set

+

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[
  • {
    }
]

Return meta data for Distribution Set

Get a paged list of meta data for a distribution set. Required permission: READ_REPOSITORY

+
path Parameters
distributionSetId
required
integer <int64>
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{
  • "content": [
    ],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Create a list of meta data for a specific distribution set

Create a list of meta data entries Required permissions: READ_REPOSITORY and UPDATE_TARGET

+
path Parameters
distributionSetId
required
integer <int64>
Request Body schema:
required
Array
key
required
string

Metadata property key

+
value
string

Metadata property value

+

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[
  • {
    }
]

Invalidate a distribution set

Invalidate a distribution set. Once a distribution set is invalidated, it can not be valid again. An invalidated +distribution set cannot be assigned to targets anymore. The distribution set that is going to be invalidated +will be removed from all auto assignments. Furthermore, the user can choose to cancel all rollouts and (force) +cancel all actions connected to this distribution set. Required permission: UPDATE_REPOSITORY, UPDATE_TARGET

+
path Parameters
distributionSetId
required
integer <int64>
Request Body schema:
required
actionCancelationType
required
string
Enum: "soft" "force" "none"

Type of cancelation for actions referring to the given distribution set

+
cancelRollouts
boolean

Defines if rollouts referring to this distribution set should be canceled

+

Responses

Request samples

Content type
{
  • "actionCancelationType": "soft",
  • "cancelRollouts": true
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return assigned targets to a specific distribution set

Handles the GET request for retrieving assigned targets of a single distribution set. Required permissions: READ_REPOSITORY and READ_TARGET

+
path Parameters
distributionSetId
required
integer <int64>
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{}

Assigning multiple targets to a single distribution set

Handles the POST request for assigning multiple targets to a distribution set.The request body must always be a list of target IDs. Non-existing targets are silently ignored resulting in a valid response. Required permissions: READ_REPOSITORY and UPDATE_TARGET

+
path Parameters
distributionSetId
required
integer <int64>
query Parameters
offline
boolean
Request Body schema:
required
Array
id
required
string

The technical identifier of the entity

+
forcetime
integer <int64>

Forcetime in milliseconds

+
type
string
Enum: "soft" "forced" "timeforced" "downloadonly"

The type of the assignment

+
object (MgmtMaintenanceWindowRequestBody)

Separation of download and install by defining a maintenance window for the installation

+
weight
integer <int32>

Importance of the assignment

+
confirmationRequired
boolean

(Available with user consent flow active) Defines, if the confirmation is required for an action. Confirmation is required per default

+

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
{
  • "alreadyAssigned": 0,
  • "assignedActions": [
    ],
  • "_links": {
    },
  • "assigned": 0,
  • "total": 0
}

Return the assigned software modules of a specific distribution set

Handles the GET request of retrieving a single distribution set. Required permission: READ_REPOSITORY

+
path Parameters
distributionSetId
required
integer <int64>
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+

Responses

Response samples

Content type
{}

Assign a list of software modules to a distribution set

Handles the POST request for assigning multiple software modules to a distribution set.The request body must +always be a list of software module IDs. Required permissions: READ_REPOSITORY and UPDATE_REPOSITORY

+
path Parameters
distributionSetId
required
integer <int64>
Request Body schema:
required
Array
id
integer <int64>

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return Rollouts, Actions and Auto Assignments counts by Status for Distribution Set

Handles the GET request of retrieving Rollouts, Actions and Auto Assignments counts by Status for Distribution Set

+
path Parameters
distributionSetId
required
integer <int64>

Responses

Response samples

Content type
{
  • "actions": {
    },
  • "rollouts": {
    },
  • "totalAutoAssignments": 0
}

Return Rollouts count by status for Distribution Set

Handles the GET request of retrieving Rollouts count by Status for Distribution Set

+
path Parameters
distributionSetId
required
integer <int64>

Responses

Response samples

Content type
{
  • "actions": {
    },
  • "rollouts": {
    },
  • "totalAutoAssignments": 0
}

Return Auto Assignments count for Distribution Set

Handles the GET request of retrieving Auto Assignments count for Distribution Set

+
path Parameters
distributionSetId
required
integer <int64>

Responses

Response samples

Content type
{
  • "actions": {
    },
  • "rollouts": {
    },
  • "totalAutoAssignments": 0
}

Return Actions count by status for Distribution Set

Handles the GET request of retrieving Actions count by Status for Distribution Set

+
path Parameters
distributionSetId
required
integer <int64>

Responses

Response samples

Content type
{
  • "actions": {
    },
  • "rollouts": {
    },
  • "totalAutoAssignments": 0
}

Return installed targets to a specific distribution set

Handles the GET request for retrieving installed targets of a single distribution set. Required permissions: READ_REPOSITORY and READ_TARGET

+
path Parameters
distributionSetId
required
integer <int64>
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{}

Return target filter queries that have the given distribution set as auto assign DS

Handles the GET request for retrieving assigned target filter queries of a single distribution set. Required permissions: READ_REPOSITORY and READ_TARGET

+
path Parameters
distributionSetId
required
integer <int64>
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{
  • "content": [],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Delete the assignment of the software module from the distribution set

Delete an assignment. Required permission: UPDATE_REPOSITORY

+
path Parameters
distributionSetId
required
integer <int64>
softwareModuleId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Targets

REST API for Target CRUD operations.

+

Return target by id

Handles the GET request of retrieving a single target. Required Permission: READ_TARGET.

+
path Parameters
targetId
required
string

Responses

Response samples

Content type
{}

Update target by id

Handles the PUT request of updating a target. Required Permission: UPDATE_TARGET

+
path Parameters
targetId
required
string
Request Body schema:
required
name
required
string

The name of the entity

+
description
string

The description of the entity

+
controllerId
required
string

Controller ID

+
address
string

The last known address URI of the target. Includes information of the target is connected either directly (DDI) through HTTP or indirectly (DMF) through amqp

+
securityToken
string

Pre-Shared key that allows targets to authenticate at Direct Device Integration API if enabled in the tenant settings

+
requestAttributes
boolean

Request re-transmission of target attributes

+
targetType
integer <int64>

ID of the target type

+

Responses

Request samples

Content type
{
  • "name": "controllerName",
  • "description": "Example description of a target",
  • "controllerId": "123",
  • "address": "https://192.168.0.1",
  • "securityToken": "2345678DGGDGFTDzztgf",
  • "requestAttributes": true,
  • "targetType": 10
}

Response samples

Content type
{}

Delete target by id

Handles the DELETE request of deleting a single target. Required Permission: DELETE_TARGET

+
path Parameters
targetId
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return single metadata value for a specific key of a target

Get a single metadata value for a metadata key. Required permission: READ_REPOSITORY

+
path Parameters
targetId
required
string
metadataKey
required
string

Responses

Response samples

Content type
application/json
{
  • "key": "someKnownKey",
  • "value": "someKnownKeyValue"
}

Updates a single metadata value of a target

Update a single metadata value for speficic key. Required permission: UPDATE_REPOSITORY

+
path Parameters
targetId
required
string
metadataKey
required
string
Request Body schema: application/json
required
value
string

Responses

Request samples

Content type
application/json
{
  • "value": "someValue"
}

Response samples

Content type
{
  • "key": "someKnownKey",
  • "value": "someKnownKeyValue"
}

Deletes a single metadata entry from a target

Delete a single metadata. Required permission: UPDATE_REPOSITORY

+
path Parameters
targetId
required
string
metadataKey
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return action by id of a specific target

Handles the GET request of retrieving a specific action on a specific target. Required Permission: READ_TARGET

+
path Parameters
targetId
required
string
actionId
required
integer <int64>

Responses

Response samples

Content type
{}

Switch an action from soft to forced

Handles the PUT request to switch an action from soft to forced. Required Permission: UPDATE_TARGET.

+
path Parameters
targetId
required
string
actionId
required
integer <int64>
Request Body schema:
required
forceType
string
Enum: "soft" "forced" "timeforced" "downloadonly"

Responses

Request samples

Content type
{
  • "forceType": "soft"
}

Response samples

Content type
{}

Cancel action for a specific target

Cancels an active action, only active actions can be deleted. Required Permission: UPDATE_TARGET

+
path Parameters
targetId
required
string
actionId
required
integer <int64>
query Parameters
force
boolean
Default: false

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Controls (confirm/deny) actions waiting for confirmation

Either confirm or deny an action which is waiting for confirmation. +The action will be transferred into the RUNNING state in case confirming it. +The action will remain in WAITING_FOR_CONFIRMATION state in case denying it. +Required Permission: READ_REPOSITORY AND UPDATE_TARGET

+
path Parameters
targetId
required
string
actionId
required
integer <int64>
Request Body schema:
required
confirmation
required
string
Enum: "confirmed" "denied"

Action confirmation state

+
code
integer <int32>

(Optional) Individual status code

+
details
Array of strings

List of detailed message information

+

Responses

Request samples

Content type
{
  • "confirmation": "confirmed",
  • "code": 200,
  • "details": [
    ]
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all targets

Handles the GET request of retrieving all targets. Required permission: READ_TARGET

+
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{}

Create target(s)

Handles the POST request of creating new targets. The request body must always be a list of targets. Required Permission: CREATE_TARGET

+
Request Body schema:
required
Array
name
required
string

The name of the entity

+
description
string

The description of the entity

+
controllerId
required
string

Controller ID

+
address
string

The last known address URI of the target. Includes information of the target is connected either directly (DDI) through HTTP or indirectly (DMF) through amqp

+
securityToken
string

Pre-Shared key that allows targets to authenticate at Direct Device Integration API if enabled in the tenant settings

+
requestAttributes
boolean

Request re-transmission of target attributes

+
targetType
integer <int64>

ID of the target type

+

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[]

Assign target type to a target

Assign or update the target type of a target. Required permission: UPDATE_TARGET

+
path Parameters
targetId
required
string
Request Body schema:
required
id
integer <int64>

Responses

Request samples

Content type
{
  • "id": 108
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Unassign target type from target.

Remove the target type from a target. The target type will be set to null. Required permission: UPDATE_TARGET

+
path Parameters
targetId
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return metadata for specific target

Get a paged list of metadata for a target. Required permission: READ_REPOSITORY

+
path Parameters
targetId
required
string
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{
  • "content": [
    ],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Create a list of metadata for a specific target

Create a list of metadata entries Required permissions: READ_REPOSITORY and UPDATE_TARGET

+
path Parameters
targetId
required
string
Request Body schema:
required
Array
key
required
string

Metadata property key

+
value
string

Metadata property value

+

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[
  • {
    }
]

Deactivate auto-confirm on a specific target

Handles the POST request to deactivate auto-confirmation for a specific target. All active actions will remain unchanged while all future actions need to be confirmed, before processing with the deployment. Required Permission: UPDATE_TARGET

+
path Parameters
targetId
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Activate auto-confirm on a specific target

Handles the POST request to activate auto-confirmation for a specific target. As a result all current active as well as future actions will automatically be confirmed by mentioning the initiator as triggered person. Actions will be automatically confirmed, as long as auto-confirmation is active. Required Permission: UPDATE_TARGET

+
path Parameters
targetId
required
string
Request Body schema: application/json
initiator
string

(Optional) Initiator set on activation

+
remark
string

(Optional) Remark set on activation

+

Responses

Request samples

Content type
application/json
{
  • "initiator": "custom_initiator_value",
  • "remark": "custom_remark"
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return the assigned distribution set of a specific target

Handles the GET request of retrieving the assigned distribution set of an specific target. Required Permission: READ_TARGET

+
path Parameters
targetId
required
string

Responses

Response samples

Content type
{
  • "createdBy": "bumlux",
  • "createdAt": 1682408574924,
  • "lastModifiedBy": "bumlux",
  • "lastModifiedAt": 1682408574925,
  • "name": "DS",
  • "description": "Updated Desc: 2LaONizh7WZp0on6XEOZI9AwEYIjj77YZskEmA2LVrKtAOXj9vvqACopEghLMqt6DIWpIahn6XM4jUlRZ1T5SZS2NWMuWHGoFIg1",
  • "version": "1.0",
  • "modules": [
    ],
  • "requiredMigrationStep": false,
  • "type": "test_default_ds_type",
  • "typeName": "OS (FW) mandatory, runtime (FW) and app (SW) optional",
  • "complete": true,
  • "deleted": false,
  • "valid": true,
  • "_links": {},
  • "id": 6
}

Assigns a distribution set to a specific target

Handles the POST request for assigning a distribution set to a specific target. Required Permission: READ_REPOSITORY and UPDATE_TARGET

+
path Parameters
targetId
required
string
query Parameters
offline
boolean

Offline update (set param to true) that is only reported but not managed by the service, e.g. +defaults set in factory, manual updates or migrations from other update systems. A completed action +is added to the history of the target(s). Target is set to IN_SYNC state as both assigned and +installed DS are set. Note: only executed if the target has currently no running update

+
Request Body schema:
required
Array
id
required
integer <int64>
forcetime
integer <int64>

Forcetime in milliseconds

+
weight
integer <int32>

Importance of the assignment

+
confirmationRequired
boolean

(Available with user consent flow active) Specifies if the confirmation by the device +is required for this action

+
type
string
Enum: "soft" "forced" "timeforced" "downloadonly"

The type of the assignment

+
object (MgmtMaintenanceWindowRequestBody)

Separation of download and install by defining a maintenance window for the installation

+

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
{
  • "alreadyAssigned": 0,
  • "assignedActions": [
    ],
  • "_links": {
    },
  • "assigned": 0,
  • "total": 0
}

Return tags for specific target

Get a paged list of tags for a target. Required permission: READ_REPOSITORY

+
path Parameters
targetId
required
string

Responses

Response samples

Content type
[]

Return installed distribution set of a specific target

Handles the GET request of retrieving the installed distribution set of an specific target. Required Permission: READ_TARGET

+
path Parameters
targetId
required
string

Responses

Response samples

Content type
{
  • "createdBy": "bumlux",
  • "createdAt": 1682408574924,
  • "lastModifiedBy": "bumlux",
  • "lastModifiedAt": 1682408574925,
  • "name": "DS",
  • "description": "Updated Desc: 2LaONizh7WZp0on6XEOZI9AwEYIjj77YZskEmA2LVrKtAOXj9vvqACopEghLMqt6DIWpIahn6XM4jUlRZ1T5SZS2NWMuWHGoFIg1",
  • "version": "1.0",
  • "modules": [
    ],
  • "requiredMigrationStep": false,
  • "type": "test_default_ds_type",
  • "typeName": "OS (FW) mandatory, runtime (FW) and app (SW) optional",
  • "complete": true,
  • "deleted": false,
  • "valid": true,
  • "_links": {},
  • "id": 6
}

Return the current auto-confitm state for a specific target

Handles the GET request to check the current auto-confirmation state of a target. Required Permission: READ_TARGET

+
path Parameters
targetId
required
string

Responses

Response samples

Content type
{}

Return attributes of a specific target

Handles the GET request of retrieving the attributes of a specific target. Reponse is a key/value list. Required Permission: READ_TARGET

+
path Parameters
targetId
required
string

Responses

Response samples

Content type
{
  • "property1": "string",
  • "property2": "string"
}

Return actions for a specific target

Handles the GET request of retrieving the full action history of a specific target. Required Permission: READ_TARGET

+
path Parameters
targetId
required
string
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{}

Return status of a specific action on a specific target

Handles the GET request of retrieving a specific action on a specific target. Required Permission: READ_TARGET

+
path Parameters
targetId
required
string
actionId
required
integer <int64>
query Parameters
offset
integer <int32>
Default: 0
limit
integer <int32>
Default: 50
sort
string

Responses

Response samples

Content type
{
  • "content": [
    ],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Actions

REST API providing (read-only) access to actions.

+

Return all actions

Handles the GET request of retrieving all actions.

+
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+
representation
string
Default: "compact"

The representation mode. Can be "full" or "compact". Defaults to "compact"

+

Responses

Response samples

Content type
{}

Return action by id

Handles the GET request of retrieving a single action by actionId.

+
path Parameters
actionId
required
integer <int64>

Responses

Response samples

Content type
{}

Basic Authentication

API for basic auth user validation.

+

validateBasicAuth

Responses

Response samples

Content type
{
  • "tenant": "string",
  • "username": "string"
}

Software Module Types

REST API for SoftwareModuleTypes CRUD operations.

+

Return single Software Module Type

Handles the GET request of retrieving a single software module type. Required Permission: READ_REPOSITORY

+
path Parameters
softwareModuleTypeId
required
integer <int64>

Responses

Response samples

Content type
{
  • "createdBy": "system",
  • "createdAt": 1682408579390,
  • "lastModifiedBy": "bumlux",
  • "lastModifiedAt": 1682408579394,
  • "name": "Application",
  • "description": "Updated description.",
  • "key": "application",
  • "maxAssignments": 2147483647,
  • "deleted": false,
  • "_links": {},
  • "id": 4
}

Update Software Module Type

Handles the PUT request for a single software module type. Required Permission: UPDATE_REPOSITORY

+
path Parameters
softwareModuleTypeId
required
integer <int64>
Request Body schema:
required
description
string
colour
string

Responses

Request samples

Content type
{
  • "description": "Example description",
  • "colour": "rgb(0,0,255"
}

Response samples

Content type
{
  • "createdBy": "system",
  • "createdAt": 1682408579390,
  • "lastModifiedBy": "bumlux",
  • "lastModifiedAt": 1682408579394,
  • "name": "Application",
  • "description": "Updated description.",
  • "key": "application",
  • "maxAssignments": 2147483647,
  • "deleted": false,
  • "_links": {},
  • "id": 4
}

Delete Software Module Type by Id

Handles the DELETE request for a single software module type. Required Permission: DELETE_REPOSITORY

+
path Parameters
softwareModuleTypeId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all Software Module Types

Handles the GET request of retrieving all software module types. Required Permission: READ_REPOSITORY

+
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{
  • "content": [
    ],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Creates new Software Module Types

Handles the POST request of creating new software module types. The request body must always be a list of module types. Required Permission: CREATE_REPOSITORY

+
Request Body schema:
required
Array
description
string
colour
string
name
required
string
key
required
string
maxAssignments
integer <int32>

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[
  • {
    }
]

Rollouts

REST API for Rollout CRUD operations.

+

Return single Rollout

Handles the GET request of retrieving a single rollout. Required Permission: READ_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>

Responses

Response samples

Content type
{}

Update Rollout

Handles the UPDATE request for a single Rollout. Required permission: UPDATE_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>
Request Body schema:
required
name
required
string
description
string
object (Links)

Responses

Request samples

Content type
{
  • "name": "exampleRollout",
  • "description": "Rollout for all named targets"
}

Response samples

Content type
{}

Delete a Rollout

Handles the DELETE request of deleting a rollout. Required Permission: DELETE_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all Rollouts

Handles the GET request of retrieving all rollouts. Required Permission: READ_ROLLOUT

+
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+
representation
string
Default: "compact"

Responses

Response samples

Content type
{}

Create a new Rollout

Handles the POST request of creating new rollout. Required Permission: CREATE_ROLLOUT

+
Request Body schema:
required
name
required
string
description
string
object (MgmtRolloutCondition)

The error condition which takes in place to evaluate if a rollout group encounter errors

+
object (MgmtRolloutSuccessAction)

The success action which takes in place to execute in case the success action is fulfilled

+
object (MgmtRolloutCondition)

The error condition which takes in place to evaluate if a rollout group encounter errors

+
object (MgmtRolloutErrorAction)

The error action which is executed if the error condition is fulfilled

+
targetFilterQuery
string

Target filter query language expression

+
distributionSetId
integer <int64>

The ID of distribution set of this rollout

+
amountGroups
integer <int32>

The amount of groups the rollout should split targets into

+
forcetime
integer <int64>

Force time in milliseconds

+
startAt
integer <int64>

Start at timestamp of Rollout

+
weight
integer <int32>

Weight of the resulting Actions

+
dynamic
boolean
object (MgmtDynamicRolloutGroupTemplate)

Template for dynamic groups (only if dynamic flag is true)

+
confirmationRequired
boolean

(Available with user consent flow active) If the confirmation is required for this rollout. Value will be used +if confirmation options are missing in the rollout group definitions. Confirmation is required per default

+
type
string
Enum: "soft" "forced" "timeforced" "downloadonly"

The type of this rollout

+
Array of objects (MgmtRolloutGroup)

The list of group definitions

+
object (Links)

Responses

Request samples

Content type
{
  • "distributionSetId": 6,
  • "targetFilterQuery": "id==targets-*",
  • "description": "Rollout for all named targets",
  • "amountGroups": 5,
  • "type": "forced",
  • "successCondition": {
    },
  • "successAction": {
    },
  • "name": "exampleRollout",
  • "forcetime": 1682408571791,
  • "errorAction": {
    },
  • "confirmationRequired": false,
  • "errorCondition": {
    },
  • "startAt": 1682408570791
}

Response samples

Content type
{}

Force trigger processing next group of a Rollout

Handles the POST request of triggering the next group of a rollout. Required Permission: UPDATE_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Start a Rollout

Handles the POST request of starting a created rollout. Required Permission: HANDLE_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Retry a rollout

Handles the POST request of retrying a rollout. Required Permission: CREATE_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>

Responses

Response samples

Content type
{}

Resume a Rollout

Handles the POST request of resuming a paused rollout. Required Permission: HANDLE_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Pause a Rollout

Handles the POST request of pausing a running rollout. Required Permission: HANDLE_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Deny a Rollout

Handles the POST request of denying a created rollout. Only possible if approval workflow is enabled in system configuration and rollout is in state WAITING_FOR_APPROVAL. Required Permission: APPROVE_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>
query Parameters
remark
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Approve a Rollout

Handles the POST request of approving a created rollout. Only possible if approval workflow is enabled in system configuration and rollout is in state WAITING_FOR_APPROVAL. Required Permission: APPROVE_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>
query Parameters
remark
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all rollout groups referred to a Rollout

Handles the GET request of retrieving all deploy groups of a specific rollout. Required Permission: READ_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+
representation
string
Default: "compact"

Responses

Response samples

Content type
{
  • "content": [
    ],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Return single rollout group

Handles the GET request of a single deploy group of a specific rollout. Required Permission: READ_ROLLOUT

+
path Parameters
rolloutId
required
integer <int64>
groupId
required
integer <int64>

Responses

Response samples

Content type
{
  • "createdBy": "bumlux",
  • "createdAt": 1682408569768,
  • "lastModifiedBy": "bumlux",
  • "lastModifiedAt": 1682408569795,
  • "name": "group-1",
  • "description": "group-1",
  • "successCondition": {
    },
  • "successAction": {
    },
  • "errorCondition": {
    },
  • "errorAction": {
    },
  • "targetFilterQuery": "",
  • "targetPercentage": 20,
  • "confirmationRequired": false,
  • "status": "ready",
  • "totalTargets": 4,
  • "totalTargetsPerStatus": {
    },
  • "_links": {},
  • "id": 78
}

Return all targets related to a specific rollout group

Handles the GET request of retrieving all targets of a single deploy group of a specific rollout. Required Permissions: READ_ROLLOUT, READ_TARGET.

+
path Parameters
rolloutId
required
integer <int64>
groupId
required
integer <int64>
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{}

Target Types

REST API for Target Type CRUD operations.

+

Return target type by id

Handles the GET request of retrieving a single target type

+
path Parameters
targetTypeId
required
integer <int64>

Responses

Response samples

Content type
{}

Update target type by id

Handles the PUT request for a single target type. Required Permission: UPDATE_TARGET

+
path Parameters
targetTypeId
required
integer <int64>
Request Body schema:
required
name
required
string

The name of the entity

+
description
string

The description of the entity

+
colour
string

The colour of the entity

+

Responses

Request samples

Content type
{
  • "name": "updatedTypeName",
  • "description": "an updated description",
  • "colour": "#aaafff"
}

Response samples

Content type
{}

Delete target type by id

Handles the DELETE request for a single target type. Required Permission: DELETE_TARGET

+
path Parameters
targetTypeId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all target types

Handles the GET request of retrieving all target types.

+
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{
  • "content": [],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Create target types

Handles the POST request for creating new target types. The request body must always be a list of types. Required Permission: CREATE_TARGET

+
Request Body schema:
required
Array
name
required
string

The name of the entity

+
description
string

The description of the entity

+
colour
string

The colour of the entity

+
key
string

Target type key

+
Array of objects (MgmtDistributionSetTypeAssignment)

Array of distribution set types that are compatible to that target type

+

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[]

Return list of compatible distribution set types

Handles the GET request of retrieving the list of compatible distribution set types in that target type. Required Permission: READ_TARGET, READ_REPOSITORY

+
path Parameters
targetTypeId
required
integer <int64>

Responses

Response samples

Content type
[]

Adding compatibility of a distribution set type to a target type

Handles the POST request for adding compatible distribution set types to a target type. Required Permission: UPDATE_TARGET and READ_REPOSITORY

+
path Parameters
targetTypeId
required
integer <int64>
Request Body schema:
required
Array
id
integer <int64>

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Remove compatibility of distribution set type from the target type

Handles the DELETE request for removing a distribution set type from a single target type. Required Permission: UPDATE_TARGET and READ_REPOSITORY

+
path Parameters
targetTypeId
required
integer <int64>
distributionSetTypeId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Software Modules

REST API for SoftwareModule and related Artifact CRUD operations.

+

Return Software Module by id

Handles the GET request of retrieving a single softwaremodule. Required Permission: READ_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>

Responses

Response samples

Content type
{}

Update Software Module

Handles the PUT request for a single softwaremodule within Hawkbit. Required Permission: UPDATE_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>
Request Body schema:
required
description
string
vendor
string
locked
boolean

Should be set only if change of locked state is requested. If put, the software module locked flag will be +set to the requested. Note: unlock (i.e. set this property to false) with extreme care! +In general once software module is locked it shall not be unlocked. Note that it could have been assigned / +deployed to targets.

+

Responses

Request samples

Content type
{
  • "description": "SM Description",
  • "vendor": "SM Vendor Name",
  • "locked": true
}

Response samples

Content type
{}

Delete Software Module by Id

Handles the DELETE request for a single softwaremodule within Hawkbit. Required Permission: DELETE_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return single metadata value for a specific key of a Software Module

Get a single metadata value for a metadata key. Required Permission: READ_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>
metadataKey
required
string

Responses

Response samples

Content type
{
  • "key": "someKnownKey",
  • "value": "someKnownValue",
  • "targetVisible": false
}

Update a single metadata value of a Software Module

Update a single metadata value for speficic key. Required Permission: UPDATE_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>
metadataKey
required
string
Request Body schema: application/json
required
value
string
targetVisible
boolean

Responses

Request samples

Content type
application/json
{
  • "value": "newValue",
  • "targetVisible": true
}

Response samples

Content type
{
  • "key": "someKnownKey",
  • "value": "someKnownValue",
  • "targetVisible": false
}

Delete single metadata entry from the software module

Delete a single metadata. Required Permission: UPDATE_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>
metadataKey
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all Software modules

Handles the GET request of retrieving all softwaremodules. Required Permission: READ_REPOSITORY

+
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{}

Create Software Module(s)

Handles the POST request of creating new software modules. The request body must always be a list of modules. Required Permission: CREATE_REPOSITORY

+
Request Body schema:
required
Array
name
required
string
version
required
string
type
required
string
description
string
vendor
string
encrypted
boolean

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[]

Return metadata for a Software Module

Get a paged list of metadata for a software module. Required Permission: READ_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{
  • "content": [
    ],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Creates a list of metadata for a specific Software Module

Create a list of metadata entries Required Permission: UPDATE_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>
Request Body schema:
required
Array
key
required
string

Metadata property key

+
value
string

Metadata property value

+
targetVisible
boolean

Metadata property is visible to targets as part of software update action

+

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[
  • {
    }
]

Return all metadata of artifacts assigned to a software module

Handles the GET request of retrieving all metadata of artifacts assigned to a software module. Required Permission: READ_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>
query Parameters
representation
string
Default: "compact"
useartifacturlhandler
boolean

Responses

Response samples

Content type
[]

Upload artifact

Handles POST request for artifact upload. Required Permission: CREATE_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>
query Parameters
filename
string
md5sum
string
sha1sum
string
sha256sum
string
Request Body schema: multipart/form-data
file
required
string <binary>

Responses

Response samples

Content type
{}

Return single Artifact metadata

Handles the GET request of retrieving a single Artifact metadata request. Required Permission: READ_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>
artifactId
required
integer <int64>
query Parameters
useartifacturlhandler
boolean

Responses

Response samples

Content type
{}

Delete artifact by Id

Handles the DELETE request for a single Artifact assigned to a SoftwareModule. Required Permission: DELETE_REPOSITORY

+
path Parameters
softwareModuleId
required
integer <int64>
artifactId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Target Tags

REST API for Target Tag CRUD operations.

+

Return target tag by id

Handles the GET request of retrieving a single target tag.

+
path Parameters
targetTagId
required
integer <int64>

Responses

Response samples

Content type
{}

Update target tag by id

Handles the PUT request of updating a target tag.

+
path Parameters
targetTagId
required
integer <int64>
Request Body schema:
required
name
string

The name of the entity

+
description
string

The description of the entity

+
colour
string

The colour of the entity

+

Responses

Request samples

Content type
{
  • "name": "Example name",
  • "description": "Example description",
  • "colour": "rgb(0,255,0)"
}

Response samples

Content type
{}

Delete target tag by id

Handles the DELETE request of deleting a single target tag.

+
path Parameters
targetTagId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return assigned targets for tag

Handles the GET request of retrieving a list of assigned targets.

+
path Parameters
targetTagId
required
integer <int64>
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{}

Assign target(s) to given tagId

Handles the POST request of target assignment. Already assigned target will be ignored.

+
path Parameters
targetTagId
required
integer <int64>
query Parameters
onNotFoundPolicy
string
Default: "FAIL"
Enum: "FAIL" "ON_WHAT_FOUND_AND_FAIL" "ON_WHAT_FOUND_AND_SUCCESS"
Request Body schema:
required
Array
string

List of controller ids to be assigned

+

Responses

Request samples

Content type
[
  • "controllerId1",
  • "controllerId2"
]

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Unassign targets from a given tagId

Handles the DELETE request to unassign the given targets.

+
path Parameters
targetTagId
required
integer <int64>
query Parameters
onNotFoundPolicy
string
Default: "FAIL"
Enum: "FAIL" "ON_WHAT_FOUND_AND_FAIL" "ON_WHAT_FOUND_AND_SUCCESS"
Request Body schema:
required
Array
string

List of controller ids to be unassigned

+

Responses

Request samples

Content type
[
  • "controllerId1",
  • "controllerId2"
]

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all target tags

Handles the GET request of retrieving all target tags.

+
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{
  • "content": [],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Create target tag(s)

Handles the POST request of creating new target tag. The request body must always be a list of target tags.

+
Request Body schema:
required
Array
name
string

The name of the entity

+
description
string

The description of the entity

+
colour
string

The colour of the entity

+

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[]

Assign target(s) to given tagId

Handles the POST request of target assignment. Already assigned target will be ignored.

+
path Parameters
targetTagId
required
integer <int64>
controllerId
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Unassign target from a given tagId

Handles the DELETE request to unassign the given target.

+
path Parameters
targetTagId
required
integer <int64>
controllerId
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Target Filter Queries

REST API for Target Filter Queries CRUD operations.

+

Return target filter query by id

Handles the GET request of retrieving a single target filter query. Required permission: READ_TARGET

+
path Parameters
filterId
required
integer <int64>

Responses

Response samples

Content type
{}

Updates target filter query by id

Handles the PUT request of updating a target filter query. Required permission: UPDATE_TARGET

+
path Parameters
filterId
required
integer <int64>
Request Body schema:
required
name
required
string
query
required
string

Responses

Request samples

Content type
{
  • "name": "filterName",
  • "query": "controllerId==example-target-*"
}

Response samples

Content type
{}

Delete target filter by id

Handles the DELETE request of deleting a target filter query. Required permission: DELETE_TARGET

+
path Parameters
filterId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all target filter queries

Handles the GET request of retrieving all target filter queries. Required permission: READ_TARGET

+
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+
representation
string
Default: "compact"

Responses

Response samples

Content type
{
  • "content": [],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Create target filter

Handles the POST request to create a new target filter query. Required permission: CREATE_TARGET

+
Request Body schema:
required
name
required
string
query
required
string

Responses

Request samples

Content type
{
  • "name": "filterName",
  • "query": "controllerId==example-target-*"
}

Response samples

Content type
{}

Return distribution set for auto assignment of a specific target filter

Handles the GET request of retrieving the auto assign distribution set. Required permission: READ_TARGET

+
path Parameters
filterId
required
integer <int64>

Responses

Response samples

Content type
{
  • "createdBy": "bumlux",
  • "createdAt": 1682408574924,
  • "lastModifiedBy": "bumlux",
  • "lastModifiedAt": 1682408574925,
  • "name": "DS",
  • "description": "Updated Desc: 2LaONizh7WZp0on6XEOZI9AwEYIjj77YZskEmA2LVrKtAOXj9vvqACopEghLMqt6DIWpIahn6XM4jUlRZ1T5SZS2NWMuWHGoFIg1",
  • "version": "1.0",
  • "modules": [
    ],
  • "requiredMigrationStep": false,
  • "type": "test_default_ds_type",
  • "typeName": "OS (FW) mandatory, runtime (FW) and app (SW) optional",
  • "complete": true,
  • "deleted": false,
  • "valid": true,
  • "_links": {},
  • "id": 6
}

Set auto assignment of distribution set for a target filter query

Handles the POST request of setting the auto assign distribution set for a target filter query. Required permissions: UPDATE_TARGET and READ_REPOSITORY

+
path Parameters
filterId
required
integer <int64>
Request Body schema:
required
id
integer <int64>
type
string
Enum: "soft" "forced" "timeforced" "downloadonly"
weight
integer <int32>
confirmationRequired
boolean

Responses

Request samples

Content type
{
  • "id": 108,
  • "type": "soft",
  • "weight": 0,
  • "confirmationRequired": true
}

Response samples

Content type
{}

Remove Distribution Set for auto assignment of a target filter

Removes the auto assign distribution set from the target filter query. Required permission: UPDATE_TARGET

+
path Parameters
filterId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Download artifact

API to download artifacts.

+

downloadArtifact_1

path Parameters
softwareModuleId
required
integer <int64>
artifactId
required
integer <int64>

Responses

Distribution Set Tags

REST Resource handling for DistributionSetTag CRUD operations.

+

Return single Distribution Set Tag

Handles the GET request of retrieving a single distribution set tag.

+
path Parameters
distributionsetTagId
required
integer <int64>

Responses

Response samples

Content type
{}

Update Distribution Set Tag

Handles the PUT request of updating a distribution set tag.

+
path Parameters
distributionsetTagId
required
integer <int64>
Request Body schema:
required
name
string

The name of the entity

+
description
string

The description of the entity

+
colour
string

The colour of the entity

+

Responses

Request samples

Content type
{
  • "name": "Example name",
  • "description": "Example description",
  • "colour": "rgb(0,255,0)"
}

Response samples

Content type
{}

Delete a single distribution set tag

Handles the DELETE request of deleting a single distribution set tag.

+
path Parameters
distributionsetTagId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all assigned distribution sets by given tag Id

Handles the GET request of retrieving a list of assigned distributions.

+
path Parameters
distributionsetTagId
required
integer <int64>
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{
  • "content": [
    ],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

assignDistributionSetsPut

path Parameters
distributionsetTagId
required
integer <int64>
Request Body schema:
required
Array
integer <int64>

Responses

Request samples

Content type
[
  • 0
]

Assign distribution sets to the given tag id

Handles the POST request of distribution assignment. Already assigned distribution will be ignored.

+
path Parameters
distributionsetTagId
required
integer <int64>
Request Body schema:
required
Array
integer <int64>

Responses

Request samples

Content type
[
  • 0
]

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Unassign multiple distribution sets from the given tag id

Handles the DELETE request of unassign the given distribution.

+
path Parameters
distributionsetTagId
required
integer <int64>
Request Body schema: application/json
required
Array
integer <int64>

Responses

Request samples

Content type
application/json
[
  • 0
]

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all Distribution Set Tags

Handles the GET request of retrieving all distribution set tags.

+
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{
  • "content": [],
  • "total": 0,
  • "size": 0,
  • "_links": {
    }
}

Creates new Distribution Set Tags

Handles the POST request of creating new distribution set tag. The request body must always be a list of distribution set tags.

+
Request Body schema:
required
Array
name
string

The name of the entity

+
description
string

The description of the entity

+
colour
string

The colour of the entity

+

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[]

Assign distribution set to the given tag id

Handles the POST request of distribution assignment. Already assigned distribution will be ignored.

+
path Parameters
distributionsetTagId
required
integer <int64>
distributionsetId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Unassign one distribution set from the given tag id

Handles the DELETE request of unassign the given distribution.

+
path Parameters
distributionsetTagId
required
integer <int64>
distributionsetId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Distribution Set Types

REST Resource handling for DistributionSetType CRUD operations.

+

Return single Distribution Set Type

Handles the GET request of retrieving a single distribution set type. Required Permission: READ_REPOSITORY

+
path Parameters
distributionSetTypeId
required
integer <int64>

Responses

Response samples

Content type
{}

Update Distribution Set Type

Handles the PUT request for a single distribution set type. Required Permission: UPDATE_REPOSITORY

+
path Parameters
distributionSetTypeId
required
integer <int64>
Request Body schema:
required
description
string

The description of the entity

+
colour
string

The colour of the entity

+

Responses

Request samples

Content type
{
  • "description": "Example description",
  • "colour": "rgb(86,37,99)"
}

Response samples

Content type
{}

Delete Distribution Set Type by Id

Handles the DELETE request for a single distribution set type. Required Permission: DELETE_REPOSITORY

+
path Parameters
distributionSetTypeId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return all Distribution Set Types

Handles the GET request of retrieving all distribution set types. Required Permission: READ_REPOSITORY

+
query Parameters
offset
integer <int32>
Default: 0

The paging offset (default is 0)

+
limit
integer <int32>
Default: 50

The maximum number of entries in a page (default is 50)

+
sort
string

The query parameter sort allows to define the sort order for the result of a query. A sort criteria +consists of the name of a field and the sort direction (ASC for ascending and DESC descending). +The sequence of the sort criteria (multiple can be used) defines the sort order of the entities +in the result.

+
q
string

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for +available fields.

+

Responses

Response samples

Content type
{}

Create new distribution set types

Handles the POST request for creating new distribution set types. The request body must always be a list of types. Required Permission: CREATE_REPOSITORY

+
Request Body schema:
required
Array
description
string

The description of the entity

+
colour
string

The colour of the entity

+
name
required
string

The name of the entity

+
key
required
string

Functional key of the distribution set type

+
Array of objects (MgmtSoftwareModuleTypeAssignment)

Mandatory module type IDs

+
Array of objects (MgmtSoftwareModuleTypeAssignment)

Optional module type IDs

+

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[]

Return optional Software Module Types in a Distribution Set Type

Handles the GET request of retrieving the list of optional software module types in that distribution set type. Required Permission: READ_REPOSITORY

+
path Parameters
distributionSetTypeId
required
integer <int64>

Responses

Response samples

Content type
[
  • {
    }
]

Add optional Software Module Type to a Distribution Set Type

Handles the POST request for adding an optional software module type to a distribution set type.Note that a DS type cannot be changed after it has been used by a DS. Required Permission: UPDATE_REPOSITORY and READ_REPOSITORY

+
path Parameters
distributionSetTypeId
required
integer <int64>
Request Body schema:
required
id
integer <int64>

Responses

Request samples

Content type
{
  • "id": 108
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return mandatory Software Module Types in a Distribution Set Type

Handles the GET request of retrieving the list of mandatory software module types in that distribution set type. Required Permission: READ_REPOSITORY

+
path Parameters
distributionSetTypeId
required
integer <int64>

Responses

Response samples

Content type
[
  • {
    }
]

Add mandatory Software Module Type to a Distribution Set Type

Handles the POST request for adding a mandatory software module type to a distribution set type.Note that a DS type cannot be changed after it has been used by a DS. Required Permission: UPDATE_REPOSITORY and READ_REPOSITORY

+
path Parameters
distributionSetTypeId
required
integer <int64>
Request Body schema:
required
id
integer <int64>

Responses

Request samples

Content type
{
  • "id": 108
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return single optional Software Module Type in a Distribution Set Type

Handles the GET request of retrieving the single optional software module type in that distribution set type. Required Permission: READ_REPOSITORY

+
path Parameters
distributionSetTypeId
required
integer <int64>
softwareModuleTypeId
required
integer <int64>

Responses

Response samples

Content type
{
  • "createdBy": "system",
  • "createdAt": 1682408579390,
  • "lastModifiedBy": "bumlux",
  • "lastModifiedAt": 1682408579394,
  • "name": "Application",
  • "description": "Updated description.",
  • "key": "application",
  • "maxAssignments": 2147483647,
  • "deleted": false,
  • "_links": {},
  • "id": 4
}

Delete an optional module from a Distribution Set Type

Handles DELETE request for removing an optional module from the distribution set type. Note that a DS type cannot be changed after it has been used by a DS. Required Permission: UPDATE_REPOSITORY and READ_REPOSITORY

+
path Parameters
distributionSetTypeId
required
integer <int64>
softwareModuleTypeId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Return single mandatory Software Module Type in a Distribution Set Type

Handles the GET request of retrieving the single mandatory software module type in that distribution set type. Required Permission: READ_REPOSITORY

+
path Parameters
distributionSetTypeId
required
integer <int64>
softwareModuleTypeId
required
integer <int64>

Responses

Response samples

Content type
{
  • "createdBy": "system",
  • "createdAt": 1682408579390,
  • "lastModifiedBy": "bumlux",
  • "lastModifiedAt": 1682408579394,
  • "name": "Application",
  • "description": "Updated description.",
  • "key": "application",
  • "maxAssignments": 2147483647,
  • "deleted": false,
  • "_links": {},
  • "id": 4
}

Delete a mandatory module from a Distribution Set Type

Handles the DELETE request for removing a software module type from a single distribution set type. Required Permission: DELETE_REPOSITORY

+
path Parameters
distributionSetTypeId
required
integer <int64>
softwareModuleTypeId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

System Configuration

REST API for handling tenant specific configuration operations.

+

Return all tenant specific configuration values

The GET request returns a list of all possible configuration keys for the tenant. Required Permission: READ_TENANT_CONFIGURATION

+

Responses

Response samples

Content type
{}

Batch update of tenant configuration.

The PUT request updates the whole configuration for the tenant. Required Permission: TENANT_CONFIGURATION

+
Request Body schema:
required
property name*
additional property
object

Responses

Request samples

Content type
{
  • "property1": { },
  • "property2": { }
}

Response samples

Content type
[]

Return a tenant specific configuration value

The GET request returns the configuration value of a specific configuration key for the tenant. Required Permission: READ_TENANT_CONFIGURATION

+
path Parameters
keyName
required
string

Responses

Response samples

Content type
{}

Update a tenant specific configuration value.

The PUT request changes a configuration value of a specific configuration key for the tenant. Required Permission: TENANT_CONFIGURATION

+
path Parameters
keyName
required
string
Request Body schema:
required
value
required
object

Current value of of configuration parameter

+

Responses

Request samples

Content type
{
  • "value": "exampleToken"
}

Response samples

Content type
{}

Delete a tenant specific configuration value

The DELETE request removes a tenant specific configuration value for the tenant. Afterwards the global default value is used. Required Permission: TENANT_CONFIGURATION

+
path Parameters
keyName
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}
+ + + + diff --git a/docs/rollout-management.md b/docs/rollout-management.md new file mode 100644 index 000000000..93b1ee2a5 --- /dev/null +++ b/docs/rollout-management.md @@ -0,0 +1,97 @@ +# Rollout management +Software update operations in large scale IoT scenarios with hundreds of thousands of devices require special handling. + +That includes: + +- _Technical Scalability_ by means of horizontal scale of the hawkBit server cluster in the cloud. +- _Global_ artifact _content delivery_ capacities. +- _Functional Scalability_ by means of: + - Secure handling of large volumes of devices at rollout creation time. + - Monitoring of the rollout progress. + - Emergency rollout shutdown in case of problems on to many devices. + +- Reporting capabilities for a complete understanding of the rollout progress at each point in time. + +Eclipse hawkBit sees these capabilities under the term Rollout Management. + +The following capabilities are currently supported by the _Rollout Management_: + +- Create, update and start of rollouts. + - Selection of targets as input for the rollout based on _target filter_ functionality. + - Selection of a _DistributionSet_. + - Auto-splitting of the input target list into a defined number deployment groups. +- Approval workflow + - Has to be enabled explicitly in configuration. + - Enables a workflow that requires a user with adequate permissions to review any new or updated rollout before it + can be started. + - Allows integration with 3rd party workflow engines. + +- Cascading start of the deployment groups based on installation status of the previous group. +- Emergency shutdown of the rollout in case a group exceeds the defined error threshold. +- Rollout progress monitoring for the entire rollout and the individual groups. + +--- + +## Cascading Deployment Group Execution + +The cascading execution of the deployment groups is based on two thresholds that can be defined by the rollout creator. + +- success condition by means of percentage of successfully installed targets in the current groups triggers. +- error condition by means of absolute or percentage of failed installations which triggers an emergency shutdown of the + entire rollout. + +--- + +## Rollout state machine + +### State Machine on Rollout + +

+ Clustering Diagram +

+ +### State Machine on Rollout Deployment Group +

+ Clustering Diagram +

+ +--- + +## Multi-Assignments (beta) + +One of the main paradigms of Eclipse hawkBit is, that a Distribution Set represents the currently installed software of +a device. Hence, a device can have only one Distribution Set assigned/installed at a time. With _Multi-Assignments_ +enabled, this paradigm shifts. Multi-Assignments allows to assign multiple Distribution Sets to a device simultaneously, +without cancelling each other. As a consequence, an operator can trigger multiple campaigns addressing the same devices +in parallel. + +### Action weight + +To differentiate between important and less important updates a property called _weight_ is used. When multi-assignments +is enabled every action has a weight value between (and including) 0 and 1000. The higher the weight the more important +is the assignment represented by the action. Also when defining a _rollout_ or an _auto-assignment_ and +multi-assignments is enabled a weight value has to be provided. This value is passed to the actions created during the +execution of these _rollouts_ and _auto-assignments_. If no weight was provided the highest value of 1000 is used +instead. + +### Consequences + +While this feature provides more flexibility to the user and enables new use-cases, there are also some consequences one +should be aware of: + +**Critical** + +* This feature is in beta and may change unannounced. +* For now, this feature is **opt-in only**. Once activated, it cannot be deactivated. + +**Minor** + +* While on DMF-API a MULTI_ACTION request is sent, DDI-API only exposes the next action which has the highest priority + in the list of open actions(according to their weight property). +* All information regarding the currently assigned or installed Distribution Set does only respect the last assignment, + as well as the last successfully installed Distribution set. This also affects: + * Pinning a target or Distribution Set in Deployment View. + * Statistics about installed or assigned Distribution Sets. +* Auto close running actions, when a new Distribution Set is assigned (`repository.actions.autoclose.enabled`) is + deactivated. +* Marking a Distribution Set to be a *Required Migration Step* is deactivated. diff --git a/docs/run-hawkbit.md b/docs/run-hawkbit.md new file mode 100644 index 000000000..ff1be5bea --- /dev/null +++ b/docs/run-hawkbit.md @@ -0,0 +1,103 @@ +# Run hawkBit + +In this guide we describe how to run a full featured hawkBit setup based on a production ready infrastructure. +It is based on the hawkBit example modules and update server. + +The update server can in fact be run stand alone. However, only with an embedded H2, no Device Management Federation API and no artifact storage. + +--- + +### System Architecture + +This guide describes a target architecture that is more like one that you will expect in a production system: + +- [hawkBit](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-monolith/hawkbit-update-server) Update Server +- [MariaDB](https://mariadb.org/) for the repository +- [RabbitMQ](https://www.rabbitmq.com/) for DMF communication + +For testing and demonstration purposes we will also use: + +- hawkBit [Device Simulator](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-device-simulator) +- hawkBit [Management API example client](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-mgmt-feign-client) + +--- + +### Prerequisites + +- You have a working hawkBit [core build](https://github.com/eclipse-hawkbit/hawkbit). +- You have a working hawkBit [examples build](https://github.com/eclipse-hawkbit/hawkbit-examples). +- Adapt hawkBit Update Server and Device Simulator to your environment. + +As mentioned you can create your own application with hawkBit inside or adapt the existing example app. +The second option will be shown here. + +--- + +### Configure MariaDB/MySQL connection settings + +For this you can either edit the existing `application.properties` or [create a new profile](http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-external-config-profile-specific-properties): + +```properties +spring.jpa.database: MYSQL +spring.datasource.url: jdbc:mariadb://localhost:3306/YOUR_SCHEMA +spring.datasource.username: YOUR_USER +spring.datasource.password: YOUR_PWD +spring.datasource.driverClassName: org.mariadb.jdbc.Driver +``` + +> **Note:** On Ubuntu 18.04 with MariaDB 10.1 installed from the default repository via `apt install`, +> the `COLLATE` option of database has to be changed manually to `latin1`. +> For recent versions of MariaDB running on Ubuntu this is not required. (cf. [issue](https://github.com/eclipse-hawkbit/hawkbit/issues/963)) + +--- + +### Configure RabbitMQ (optional) + +For update server and device simulator. +Defaults are already provided for a standard Rabbit installation. Otherwise configure the following in `application.properties` of the two services: + +```properties +spring.rabbitmq.username: guest +spring.rabbitmq.password: guest +spring.rabbitmq.virtualHost: / +spring.rabbitmq.host: localhost +spring.rabbitmq.port: 5672 +``` + +--- + +### Adapt hostname of example scenario   [creation script](https://github.com/eclipse-hawkbit/hawkbit-examples/blob/master/hawkbit-example-mgmt-simulator/src/main/resources/application.properties) + +Should only be necessary if your system does not run on `localhost` or uses a different port than the example app. + +Adapt `application.properties` in this case: + +```properties +hawkbit.url: localhost:8080 +``` + +or provide the parameter on command line: + +```properties +hawkbit-example-mgmt-simulator-##VERSION##.jar --hawkbit.url=YOUR_HOST:PORT +``` + +--- + +### Compile & Run + +#### Compile & Run your “production ready” app +See [update server](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-monolith/hawkbit-update-server) + +#### Compile & Run example scenario creation script (optional) +This has to be done before the device simulator is started. hawkBit creates the mandatory tenant metadata with first login into either Management API (which is done by this client). + +However, this is not done by DMF which is in fact used by the device simulator, i.e. without calling Management API first hawkBit would drop all DMF messages as the tenant is unknown. + +#### Compile & Run device simulator (optional) +See [device simulator](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-device-simulator) + +--- + +Enjoy hawkBit with a real database, artifact storage and all interfaces available. + diff --git a/docs/targetstate.md b/docs/targetstate.md new file mode 100644 index 000000000..fbc0ec73f --- /dev/null +++ b/docs/targetstate.md @@ -0,0 +1,21 @@ +# Target state + +A target has a current state which reflects the provisioning status of the device at this point in time. State changes +are driven either by the update server by means of starting an update or by the controller on the provisioning target +that gives feedback to the update server, e.g. "I am here", "I am working on a provisioning", "I have finished a +provisioning". + +## Defined states + +| State | Description | +|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UNKNOWN | Set by default for a pre-commissioned target until first status update received from the target. Is the initial starting point for targets created by UI or management API. | +| IN_SYNC | Assigned _Distribution Set_ is installed. | +| PENDING | Installation of assigned _Distribution Set_ is not yet confirmed. | +| ERROR | Installation of assigned _Distribution Set_ has failed. | +| REGISTERED | Target registered at the update server but no _Distribution Set_ assigned. Is the initial starting point for plug-and-play devices. | + +## Transitions +

+ Clustering Diagram +

diff --git a/docs/what-is-hawkbit.md b/docs/what-is-hawkbit.md new file mode 100644 index 000000000..4594a2241 --- /dev/null +++ b/docs/what-is-hawkbit.md @@ -0,0 +1,58 @@ +# What is hawkBit? + +Eclipse **hawkBit™** is a domain-independent back-end framework for rolling out software updates to constrained edge devices as well as more powerful controllers and gateways connected to IP-based networking infrastructure. + +

+ eclipse foundation logo +

+ +--- + +## Why Software Updates in IoT? + +Having software update capabilities ensures a secure IoT by means that it gives IoT projects a fighting chance against Pandora’s box that they opened the moment their devices got connected. From that moment on devices are at the forefront of IT security threats many embedded software developers historically never had to face. Shipping for instance a Linux powered device connected to the Internet without any security updates ever applied during its lifetime is kind of a suicidal act these days. + +A more charming argument for software update is that it enables agile development for hardware and hardware-near development. Concepts like a **minimum viable product** can be applied for devices as not all features need to be ready at manufacturing time. Changes on the cloud side of the IoT project can be applied to the devices at runtime as well. + +Sometimes **software update is a business model on its own** as it makes devices much more attractive to the customer if they are updatable, i.e. they do not only buy a product because of its current feature set but also make a bet on its future capabilities. In addition, new revenue streams may arise from the fact that feature extensions can potentially be monetized (e.g. Apps) without the need to design, manufacture and ship a new device revision. + +--- + +## Why hawkBit? + +Updating software (components) on constrained edge devices as well as more powerful controllers and gateways is, as mentioned before, a common requirement in most IoT scenarios. + +At the time being, this process is usually handled by the IoT solution itself, sometimes backed by a full-fledged device management system. We believe that this approach generates unnecessary duplicate work in the IoT space, in particular when considering the challenges of implementing a **safe and reliable remote software update process**: the software update process must never fail and also must never be compromised. At one hand, it can be used to fix almost any issue/problem on the device, but at the same time it also poses the greatest security threat if misused to introduce malicious code to the device. + +In addition, we believe the software update process to be relatively independent from particular application domains when seen from the back-end (cloud) perspective. Updating the software for an entire car may differ from updating the firmware of a single sensor with regard to the connectivity of the device to the cloud and also to the complexity of the software package update process on the device. However, the process of rolling out the software — e.g. uploading an artifact to the repository, assigning it to eligible devices, managing the rollout campaign for a large number of devices, orchestrating content delivery networks to distribute the package, monitoring and reporting the progress of the rollout and, last but not least, requirements regarding security and reliability — are quite similar. + +Software update itself is often seen as a **sub-process of general device management**. In fact, most device management systems include functionality for triggering groups of devices to perform an update, usually accompanied by an artifact repository and basic reporting and monitoring capabilities. This is true for both systems specifically targeting IoT as well as systems originating from the mobile area. + +Existing device management systems usually lack the capability to **efficiently organize rollouts at IoT scale**, e.g.: + +- splitting the rollout into sub-groups +- cascading them +- automatically stopping the rollout after a defined error threshold + +They are also usually restricted to a single device management protocol, either a proprietary one or one of the existing standard protocols like **LWM2M, OMA-DM or TR-069**. Even if they support more than one such protocol, they are often a result of the device management protocol they started with and restricted in their adoption capabilities to others. + +At the same time the wide functional scope of a full-fledged device management system introduces unnecessary (and unwanted) complexity to many IoT projects. This is particularly true for IoT solutions working with constrained devices where requirements regarding generic device management are often very limited — but a secure & reliable software update process is still mandatory. + +**As a result, we have the need for a domain-independent solution that** + +- works for the majority of IoT projects +- goes beyond the pure update and handles more complex rollout strategies needed by large-scale IoT projects +- at the same time is focused on software updates in the IoT space +- and that is able to work on its own for simple scenarios while having the capability to integrate with existing device management systems and protocols + +--- + +## Cloud Ready + +- **Technical Scalability:** connect millions of devices and ship terabytes of software on a global scale. +- **Functional Scalability:** rollouts with hundreds of thousands of individual devices in it. +- **Reliability:** software update as the last line of defense against device faults and vulnerabilities. +- **Managed device complexity:** device topologies inside each individual provisioning target. +- **Integration flexibility:** connect and integrate through various (non-)standardized device management protocols directly or through federated device managements. + +---