Merge pull request #2744 from bosch-io/feature/migrate-hawkbit-documentation
Migrate hawkBit documentation to GitHub Pages.
This commit is contained in:
Denislav Prinov
0
docs/.nojekyll
Normal file
0
docs/.nojekyll
Normal file
58
docs/README.md
Normal file
58
docs/README.md
Normal file
@@ -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.
|
||||
|
||||
<p align="center">
|
||||
<img src="images/hawkBit_overview.jpeg" alt="eclipse foundation logo" width="1200">
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
<div style="display: flex; align-items: flex-start;">
|
||||
|
||||
<div style="flex: 1; padding-right: 20px;">
|
||||
|
||||
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.
|
||||
|
||||
</div>
|
||||
|
||||
<div style="flex: 1;">
|
||||
|
||||
<img src="images/rollout.png" alt="Rollout Diagram" width="700"/>
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Package Model
|
||||
|
||||
<div style="display: flex; align-items: flex-start;">
|
||||
|
||||
<div style="flex: 1;">
|
||||
|
||||
<img src="images/packagemodel.png" alt="Package Model Diagram" width="600"/>
|
||||
|
||||
</div>
|
||||
|
||||
<div style="flex: 1; padding-left: 20px;">
|
||||
|
||||
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.
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
17
docs/_coverpage.md
Normal file
17
docs/_coverpage.md
Normal file
@@ -0,0 +1,17 @@
|
||||
|
||||
<img src="images/hawkbit_logo.png" alt="hawkBit logo" width="420">
|
||||
|
||||
<!--# Documentation-->
|
||||
|
||||
# Open‑source software update server for IoT devices.
|
||||
|
||||
[](https://sonarcloud.io/summary/new_code?id=eclipse-hawkbit_hawkbit)
|
||||
[](https://search.maven.org/search?q=g:org.eclipse.hawkbit)
|
||||
[](https://www.openhub.net/p/hawkbit)
|
||||
[](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)
|
||||
|
||||
|
||||
46
docs/_sidebar.md
Normal file
46
docs/_sidebar.md
Normal file
@@ -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)
|
||||
|
||||
<hr class="sidebar-sep" />
|
||||
|
||||
- [](https://sonarcloud.io/summary/new_code?id=eclipse-hawkbit_hawkbit)
|
||||
- [](https://search.maven.org/search?q=g:org.eclipse.hawkbit)
|
||||
<!--- [](https://www.openhub.net/p/hawkbit)-->
|
||||
|
||||
<!--
|
||||
- [](https://hub.docker.com/r/hawkbit/hawkbit-update-server)
|
||||
- [](https://hub.docker.com/r/hawkbit/hawkbit-update-server)
|
||||
- [](https://hub.docker.com/search?q=hawkbit%2Fhawkbit-update-server&type=image)
|
||||
-->
|
||||
|
||||
- [](https://gitter.im/eclipse/hawkbit?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
|
||||
- [](https://opensource.org/licenses/EPL-2.0)
|
||||
|
||||
<hr class="sidebar-sep" />
|
||||
|
||||
<p align="center">
|
||||
<img src="images/eclipse_foundation_logo.png" alt="eclipse foundation logo" width="180">
|
||||
</p>
|
||||
295
docs/authentication.md
Normal file
295
docs/authentication.md
Normal file
@@ -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
|
||||
|
||||
<p align="center">
|
||||
<img src="images/exampleReverseProxyArchitecture.png" alt="eclipse foundation logo" width="1400">
|
||||
</p>
|
||||
|
||||
#### 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>[^,]+) $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
|
||||
117
docs/authorization.md
Normal file
117
docs/authorization.md
Normal file
@@ -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/<client id>/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.
|
||||
65
docs/clustering.md
Normal file
65
docs/clustering.md
Normal file
@@ -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
|
||||
<p align="center">
|
||||
<img src="images/overall_cluster.png" alt="Clustering Diagram" width="1100"/>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
<p align="center">
|
||||
<img src="images/eventing-within-cluster.png" alt="Clustering Diagram" width="1100"/>
|
||||
</p>
|
||||
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).
|
||||
|
||||
73
docs/datamodel.md
Normal file
73
docs/datamodel.md
Normal file
@@ -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.
|
||||
<!--more-->
|
||||
|
||||
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).
|
||||
609
docs/device-management-federation-api.md
Normal file
609
docs/device-management-federation-api.md
Normal file
@@ -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 <br /> tenant=default <br /> thingId=abc <br /> sender=myClient | content\_type=application/json <br /> 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.<br />
|
||||
<br />
|
||||
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.<br />
|
||||
<br />
|
||||
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 <br /> tenant=default <br /> 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 <br /> tenant=default <br /> thingId=abc <br /> topic=UPDATE\_ATTRIBUTES | content\_type=application/json <br /> |
|
||||
|
||||
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 <br /> tenant=default <br /> 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 <br /> tenant=default <br /> thingId=abc <br /> 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 <br /> tenant=default <br /> 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 <br /> tenant=default <br /> 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 <br /> tenant=default <br /> thingId=abc <br /> 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 <br /> tenant=default <br /> thingId=abc <br /> 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 <br /> tenant=default <br /> 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 <br /> tenant=default <br /> thingId=abc <br /> 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 <br /> tenant=default | content_type=text/plain |
|
||||
|
||||
|
||||
55
docs/direct-device-integration-api.md
Normal file
55
docs/direct-device-integration-api.md
Normal file
@@ -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
|
||||
<div style="text-align: right; margin-bottom: 8px;">
|
||||
<button onclick="window.open('../rest-api/ddi.html', '_blank')"
|
||||
style="padding:8px 16px; border-radius:6px; border:1px solid #007bff;
|
||||
background:#007bff; color:#fff; cursor:pointer;">
|
||||
Open in new window
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<iframe
|
||||
src="../rest-api/ddi.html"
|
||||
width="100%"
|
||||
height="1080px"
|
||||
style="border: 1px solid #000000; border-radius: 16px;">
|
||||
</iframe>
|
||||
66
docs/features.md
Normal file
66
docs/features.md
Normal file
@@ -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.
|
||||
69
docs/feign-client.md
Normal file
69
docs/feign-client.md
Normal file
@@ -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();
|
||||
}
|
||||
}
|
||||
```
|
||||
BIN
docs/images/deploymnet-group-state-machine.png
Normal file
BIN
docs/images/deploymnet-group-state-machine.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
BIN
docs/images/eclipse_foundation_logo.png
Normal file
BIN
docs/images/eclipse_foundation_logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
BIN
docs/images/eventing-within-cluster.png
Normal file
BIN
docs/images/eventing-within-cluster.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
BIN
docs/images/exampleReverseProxyArchitecture.png
Normal file
BIN
docs/images/exampleReverseProxyArchitecture.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 916 KiB |
BIN
docs/images/hawkBit_overview.jpeg
Normal file
BIN
docs/images/hawkBit_overview.jpeg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 206 KiB |
BIN
docs/images/hawkbit_logo.png
Normal file
BIN
docs/images/hawkbit_logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 118 KiB |
BIN
docs/images/overall_cluster.png
Normal file
BIN
docs/images/overall_cluster.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
BIN
docs/images/packagemodel.png
Normal file
BIN
docs/images/packagemodel.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
BIN
docs/images/rollout-state-machine.png
Normal file
BIN
docs/images/rollout-state-machine.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 57 KiB |
BIN
docs/images/rollout.png
Normal file
BIN
docs/images/rollout.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
BIN
docs/images/targetStatusStates.png
Normal file
BIN
docs/images/targetStatusStates.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
244
docs/index.html
Normal file
244
docs/index.html
Normal file
@@ -0,0 +1,244 @@
|
||||
<!--
|
||||
Copyright (c) 2025 Contributors to the Eclipse Foundation
|
||||
|
||||
This program and the accompanying materials are made
|
||||
available under the terms of the Eclipse Public License 2.0
|
||||
which is available at https://www.eclipse.org/legal/epl-2.0/
|
||||
|
||||
SPDX-License-Identifier: EPL-2.0
|
||||
-->
|
||||
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Document</title>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
|
||||
<meta name="description" content="Description">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div id="app"></div>
|
||||
<script>
|
||||
window.$docsify = {
|
||||
copyCode: {
|
||||
buttonText: 'Copy',
|
||||
errorText: 'Error',
|
||||
successText: 'Copied',
|
||||
},
|
||||
name: '<span>hawkBit</span>',
|
||||
// repo: 'eclipse-hawkbit/hawkbit',
|
||||
themeColor: '#0ea5ea',
|
||||
coverpage: true,
|
||||
auto2top: true,
|
||||
loadSidebar: true,
|
||||
subMaxLevel: 2,
|
||||
maxLevel: 2,
|
||||
sidebarDisplayLevel: 1,
|
||||
|
||||
search: {
|
||||
placeholder: 'Type to search',
|
||||
noData: 'No results!',
|
||||
paths: 'auto',
|
||||
depth: 3
|
||||
}
|
||||
}
|
||||
</script>
|
||||
<!-- Docsify v4 -->
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-clike.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-markdown.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-properties.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-nginx.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-ini.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-http.min.js"></script>
|
||||
<!-- Latest v2.x.x -->
|
||||
<script src="https://unpkg.com/docsify-copy-code@2"></script>
|
||||
</body>
|
||||
|
||||
<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.6/dist/purify.min.js"></script>
|
||||
|
||||
<style>
|
||||
.sidebar .sidebar-sep {
|
||||
margin: 12px 0;
|
||||
border: 0;
|
||||
height: 1px;
|
||||
background: #0ea5ea;
|
||||
}
|
||||
</style>
|
||||
|
||||
<style>
|
||||
.rn-list { display:grid; gap:1rem; }
|
||||
.rn-card {
|
||||
border:1px solid rgba(0,0,0,.08);
|
||||
border-radius:12px;
|
||||
padding:16px;
|
||||
background: var(--docsearch-modal-background, #fff);
|
||||
}
|
||||
.rn-header { display:flex; align-items:baseline; gap:.5rem; justify-content:space-between; }
|
||||
.rn-title { margin:0; font-size:1.1rem; font-weight:600; } /* ← no real <h*> */
|
||||
.rn-badge { font-size:.75rem; padding:.1rem .4rem; border-radius:4px; border:1px solid rgba(0,0,0,.15); }
|
||||
.rn-date { font-size:1rem; opacity:.75; }
|
||||
|
||||
.rn-search {
|
||||
display:block;
|
||||
width:100%;
|
||||
max-width:520px;
|
||||
padding:.6rem .8rem;
|
||||
margin:0 0 1rem 0;
|
||||
border:1px solid rgba(0,0,0,.15);
|
||||
border-radius:10px;
|
||||
outline:none;
|
||||
box-sizing:border-box;
|
||||
}
|
||||
.rn-search:focus {
|
||||
border-color: rgba(64,128,255,.5);
|
||||
box-shadow:0 0 0 3px rgba(64,128,255,.15);
|
||||
}
|
||||
|
||||
.rn-body { font-size:.95rem; line-height:1.6; }
|
||||
.rn-body p { margin:.45rem 0; }
|
||||
.rn-body ul, .rn-body ol { margin:.4rem 0 .6rem 1.2rem; }
|
||||
.rn-body a { text-decoration:none; border-bottom:1px dotted currentColor; }
|
||||
.rn-body code {
|
||||
background:rgba(0,0,0,.06);
|
||||
padding:.1rem .3rem;
|
||||
border-radius:.3rem;
|
||||
font-size:.9em;
|
||||
}
|
||||
.rn-h { margin:.35rem 0 .15rem; font-weight:600; } /* “fake headings” inside cards */
|
||||
.rn-h1 { font-size:1rem; }
|
||||
.rn-h2 { font-size:1rem; }
|
||||
.rn-h3 { font-size:.98rem; }
|
||||
|
||||
.rn-actions { margin-top:.6rem; }
|
||||
.rn-btn {
|
||||
display:inline-block;
|
||||
padding:.5rem .8rem;
|
||||
border-radius:8px;
|
||||
border:1px solid rgba(0,0,0,.15);
|
||||
text-decoration:none;
|
||||
}
|
||||
|
||||
/* Scope details styling to release cards only */
|
||||
.rn-card details summary { cursor:pointer; font-weight:600; margin:.25rem 0; }
|
||||
</style>
|
||||
|
||||
<script>
|
||||
(function () {
|
||||
// --- settings ---
|
||||
const owner = 'eclipse-hawkbit';
|
||||
const repo = 'hawkbit';
|
||||
const targetFile = 'markdown/release-notes.md';
|
||||
const perPage = 100;
|
||||
|
||||
// Compile markdown BUT render headings as <p class="rn-h rn-h{level}"><strong>..</strong></p>
|
||||
// so Docsify won't see <h1..h6> and won't add them to the sidebar.
|
||||
function compileMd(md) {
|
||||
const renderer = new marked.Renderer();
|
||||
renderer.heading = (text, level) =>
|
||||
`<p class="rn-h rn-h${level}"><strong>${text}</strong></p>`;
|
||||
const html = marked.parse(md || '', { renderer });
|
||||
return DOMPurify.sanitize(html, { USE_PROFILES: { html: true }});
|
||||
}
|
||||
|
||||
// Follow GitHub API pagination via Link header
|
||||
async function fetchAllReleases(page = 1, acc = []) {
|
||||
const url = `https://api.github.com/repos/${owner}/${repo}/releases?per_page=${perPage}&page=${page}`;
|
||||
const res = await fetch(url, { headers: { 'Accept': 'application/vnd.github+json' } });
|
||||
if (!res.ok) throw new Error('GitHub API error: ' + res.status);
|
||||
const list = await res.json();
|
||||
const link = res.headers.get('Link') || '';
|
||||
const next = /<([^>]+)>;\s*rel="next"/.exec(link);
|
||||
const all = acc.concat(list);
|
||||
return next ? fetchAllReleases(page + 1, all) : all;
|
||||
}
|
||||
|
||||
function renderCard(r, prevTag) {
|
||||
const name = r.name || r.tag_name;
|
||||
const date = r.published_at ? new Date(r.published_at).toISOString().slice(0,10) : '';
|
||||
const pre = r.prerelease ? '<span class="rn-badge">pre-release</span>' : '';
|
||||
const bodyHtml = compileMd(r.body || '');
|
||||
const compareBtn = prevTag
|
||||
? `<a class="rn-btn" href="https://github.com/${owner}/${repo}/compare/${encodeURIComponent(prevTag)}...${encodeURIComponent(r.tag_name)}" target="_blank" rel="noopener">Compare</a>`
|
||||
: '';
|
||||
|
||||
return `
|
||||
<div class="rn-card">
|
||||
<div class="rn-header">
|
||||
<div class="rn-title">${name}</div>
|
||||
<div>${pre} <span class="rn-date">${date}</span></div>
|
||||
</div>
|
||||
<details>
|
||||
<summary>View release notes</summary>
|
||||
<div class="rn-body">${bodyHtml || '<p>No summary provided.</p>'}</div>
|
||||
</details>
|
||||
<div class="rn-actions">
|
||||
<a class="rn-btn" href="${r.html_url}" target="_blank" rel="noopener">Open on GitHub</a>
|
||||
${compareBtn}
|
||||
</div>
|
||||
</div>
|
||||
`;
|
||||
}
|
||||
|
||||
function mountUI(root, releases) {
|
||||
releases.sort((a,b) => new Date(b.published_at||b.created_at) - new Date(a.published_at||a.created_at));
|
||||
root.innerHTML = `
|
||||
<input class="rn-search" id="rn-search" placeholder="Filter releases (e.g. 0.4, prerelease, 2024)" />
|
||||
<div class="rn-list">
|
||||
${releases.map((r, i) => renderCard(r, i < releases.length - 1 ? releases[i + 1].tag_name : null)).join('')}
|
||||
</div>
|
||||
`;
|
||||
const input = root.querySelector('#rn-search');
|
||||
const cards = Array.from(root.querySelectorAll('.rn-card'));
|
||||
input.addEventListener('input', () => {
|
||||
const q = input.value.toLowerCase();
|
||||
cards.forEach(c => { c.style.display = c.textContent.toLowerCase().includes(q) ? '' : 'none'; });
|
||||
});
|
||||
}
|
||||
|
||||
// ---- docsify plugin ----
|
||||
function plugin(hook, vm) {
|
||||
hook.afterEach(function (html, next) {
|
||||
const isRN = vm.route.file === targetFile || vm.route.path.toLowerCase().includes('release-notes');
|
||||
if (!isRN) return next(html);
|
||||
next('<div id="release-notes-root"><p>Loading releases…</p></div>');
|
||||
});
|
||||
|
||||
hook.doneEach(async function () {
|
||||
const isRN =
|
||||
(vm.route.file || '').toLowerCase() === targetFile.toLowerCase() ||
|
||||
vm.route.path.toLowerCase().includes('release-notes');
|
||||
if (!isRN) return;
|
||||
|
||||
const root = Docsify.dom.find('#release-notes-root');
|
||||
if (!root) return;
|
||||
|
||||
try {
|
||||
const releases = await fetchAllReleases();
|
||||
mountUI(root, releases);
|
||||
} catch (e) {
|
||||
console.error(e);
|
||||
root.innerHTML = `
|
||||
<p>Couldn’t load releases from GitHub right now.</p>
|
||||
<p><a class="rn-btn" href="https://github.com/${owner}/${repo}/releases" target="_blank" rel="noopener">
|
||||
Open on GitHub ↗
|
||||
</a></p>`;
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
window.$docsify = window.$docsify || {};
|
||||
window.$docsify.plugins = [].concat(plugin, window.$docsify.plugins || []);
|
||||
})();
|
||||
</script>
|
||||
|
||||
</html>
|
||||
64
docs/management-api.md
Normal file
64
docs/management-api.md
Normal file
@@ -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
|
||||
<div style="text-align: right; margin-bottom: 8px;">
|
||||
<button onclick="window.open('../rest-api/mgmt.html', '_blank')"
|
||||
style="padding:8px 16px; border-radius:6px; border:1px solid #007bff;
|
||||
background:#007bff; color:#fff; cursor:pointer;">
|
||||
Open in new window
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<iframe
|
||||
src="../rest-api/mgmt.html"
|
||||
width="100%"
|
||||
height="1080px"
|
||||
style="border: 1px solid #000000; border-radius: 16px;">
|
||||
</iframe>
|
||||
171
docs/quick-start.md
Normal file
171
docs/quick-start.md
Normal file
@@ -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.
|
||||
12
docs/release-notes.md
Normal file
12
docs/release-notes.md
Normal file
@@ -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
|
||||
|
||||
<!--
|
||||
This page is populated by the Docsify plugin you added to index.html.
|
||||
The plugin replaces this content at runtime and renders cards for each release.
|
||||
-->
|
||||
872
docs/rest-api/ddi.html
Normal file
872
docs/rest-api/ddi.html
Normal file
File diff suppressed because one or more lines are too long
3927
docs/rest-api/mgmt.html
Normal file
3927
docs/rest-api/mgmt.html
Normal file
File diff suppressed because one or more lines are too long
97
docs/rollout-management.md
Normal file
97
docs/rollout-management.md
Normal file
@@ -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
|
||||
|
||||
<p align="center">
|
||||
<img src="images/rollout-state-machine.png" alt="Clustering Diagram" width="1200"/>
|
||||
</p>
|
||||
|
||||
### State Machine on Rollout Deployment Group
|
||||
<p align="center">
|
||||
<img src="images/deploymnet-group-state-machine.png" alt="Clustering Diagram" width="1200"/>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
103
docs/run-hawkbit.md
Normal file
103
docs/run-hawkbit.md
Normal file
@@ -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.
|
||||
|
||||
21
docs/targetstate.md
Normal file
21
docs/targetstate.md
Normal file
@@ -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
|
||||
<p align="center">
|
||||
<img src="images/targetStatusStates.png" alt="Clustering Diagram" width="1100"/>
|
||||
</p>
|
||||
58
docs/what-is-hawkbit.md
Normal file
58
docs/what-is-hawkbit.md
Normal file
@@ -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.
|
||||
|
||||
<p align="center">
|
||||
<img src="images/hawkbit_logo.png" alt="eclipse foundation logo" width="800">
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
---
|
||||
3
pom.xml
3
pom.xml
@@ -598,6 +598,9 @@
|
||||
<exclude>docker/**</exclude>
|
||||
<exclude>licenses/LICENSE*</exclude>
|
||||
<exclude>**/*.sql</exclude>
|
||||
<exclude>docs/**</exclude>
|
||||
<exclude>/docs/rest-api/**</exclude>
|
||||
<exclude>/docs/images/**</exclude>
|
||||
<exclude>**/application-local.properties</exclude>
|
||||
<exclude>eclipse_codeformatter.xml</exclude>
|
||||
<exclude>intellij_codeformatter.xml</exclude>
|
||||
|
||||
Reference in New Issue
Block a user