lingwei.kong/hawkbit
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

Introduce new, Hugo templates based, website (#713)

Browse Source 
* Add new hugo-based website for hawkBit

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Fix broken links + wordings
- , i.e. -> i.e,
- , e.g. -> e.g.,
- hawkbit -> hawkBit
- don't -> do not
- isn't -> is not

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Remove old documentation and add maven integration

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Add Intellij files to ignore

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Update README

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Update Copyright header
* exclude website artifacts

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Harmonize usage of i.e. and e.g.

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Add remark for windows user

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Fix indention

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Introduce review findings

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Change image in 'run hawkbit' guide

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>
This commit is contained in:
Jeroen Laverman
2018-08-01 11:01:02 +02:00
committed by Dominic Schabel
parent fa751c397b
commit f96876afe0
145 changed files with 1543 additions and 5832 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/content/apis/ddi_api.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: Direct Device Integration API
parent: APIs
weight: 82
---
This API is based on HTTP standards and based on a polling mechanism.
The hawkBit [update server](https://github.com/eclipse/hawkbit) provides REST resources which are consumed by the device to retrieve software update tasks.
{{% 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.
{{% /note %}}
## State Machine Mapping
For historical reasons the DDI has a different state machine and status messages than the [Target State Machine](../../concepts/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 send by the target as confirmation of a cancellation request by the update server. | CANCELED
REJECTED | This is send by the target in case an update of a 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` 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)
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 on the action. | RUNNING
RESUMED | This can be used by the target to inform that it continued to work on the action. | RUNNING
<iframe width="100%" height="800px" frameborder="0" src="../../rest-api/rootcontroller-api-guide/"></iframe>

301
docs/content/apis/dmf_api.md Normal file
View File

@@ -0,0 +1,301 @@
---
title: Device Management Federation API
parent: API
weight: 83
---
Currently bodies of messages are based on JSON. 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.
<!--more-->
## 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 queue name for incoming messages is **sp_direct_queue**. Unless a ``reply_to`` header is set, hawkBit will reply on the **sp.direct.exchange** which is bound to the **sp_direct_queue**.
The user can set a ``reply_to`` header (see chapter below), to change the default sender exchange.
The following chapter describes the message body, header and properties.
Note: the DMF protocol was intended to be open for other non update use cases by design (e.g. [Eclipse Hono](https://github.com/eclipse/hono). As a result, DMF uses the term **thing** and not **target** but they are actually synonyms in this case.
## Messages sent to hawkBit
All messages have to be sent to the exchange **dmf.exchange**.
### Message to register a thing
| Message Header | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| type | Type of the message | Fixed string "THING_CREATED " | true
| thingId | The ID of the registered thing | String | true
| sender | Name of the message sender | String | false
| tenant | The tenant this thing belongs to | String | false
| Message Properties | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| content_type | The content type of the payload | String | true
| reply_to | Exchange to reply to. The default is sp.direct.exchange which is bound to the sp_direct_queue | String | false
**Example Header**
| Headers | MessageProperties
|---------------------------------------|---------------------------------
| type=THING\_CREATED <br /> tenant=tenant123 <br /> thingId=abc <br /> sender=Lwm2m | content\_type=application/json <br /> reply_to (optional) =sp.connector.replyTo
### Message to update target attributes
| Message Header | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| type | Type of the message | Fixed string "EVENT" | true
| topic | Topic to handle events different | 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**
| Headers | MessageProperties
|---------------------------------------|---------------------------------
| type=EVENT <br /> tenant=tenant123 <br /> thingId=abc <br /> topic=UPDATE\_ATTRIBUTES | content\_type=application/json <br />
Payload Template
```json
{
"attributes": {
"exampleKey1" : "exampleValue1",
"exampleKey2" : "exampleValue2"
}
}
```
### Message to send an action status event to hawkBit
The Java representation is ActionUpdateStatus:
| Header | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|--------------
| type | Type of the message | Fixed string "EVENT" | true
| topic | Topic to handle events different | 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
```json
{
"actionId": long,
"softwareModuleId": long,
"actionStatus":"String",
"message":["String"]
}
```
Possible actionStatus
| Header | Description
|-----------------|------------------------------------
| DOWNLOAD | Device is downloading
| RETRIEVED | Device management service has retrieved something
| 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**
| Headers | MessageProperties
|---------------------------------------|---------------------------------
| type=EVENT <br /> tenant=tenant123 <br /> topic=UPDATE\_ACTION\_STATUS | content_type=application/json
```json
{
"actionId":137,
"softwareModuleId":17,
"actionStatus":"DOWNLOAD",
"message":["The download has started"]
}
```
### 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 thing | String | true
| topic | Topic to handle events different | Fixed string "CANCEL_DOWNLOAD" | 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
```json
{
"actionId": long
}
```
**Example Header and payload**
| Headers | MessageProperties
|---------------------------------------|---------------------------------
| type=EVENT <br /> tenant=tenant123 <br /> thingId=abc <br /> topic=CANCEL\_DOWNLOAD | content_type=application/json
```json
{
"actionId":137
}
```
After this message has been sent, an action status event with either actionStatus=CANCELED or actionStatus=CANCEL_REJECTED has to be returned.
**Example Header and Payload when cancellation is successful**
| Headers | MessageProperties
|---------------------------------------|---------------------------------
| type=EVENT <br /> tenant=tenant123 <br /> topic=UPDATE\_ACTION\_STATUS | content_type=application/json
```json
{
"actionId":137,
"softwareModuleId":17,
"actionStatus":"CANCELED",
"message":["The update was canceled."]
}
```
**Example Header and Payload when cancellation was rejected**
| Headers | MessageProperties
|---------------------------------------|---------------------------------
| type=EVENT <br /> tenant=tenant123 <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."]
}
```
## Messages sent by hawkBit
All messages from hawkBit will be sent to the **sp_direct_queue** or the one specified in the ``reply_to`` property.
### Message sent by hawkBit to initialize an update task
| Header | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| type | Type of the message | Fixed string "EVENT" | true
| thingId | The ID of the registered thing | String | true
| topic | Topic to handle events different | Fixed string "DOWNLOAD_AND_INSTALL" | 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
The Java representation is DownloadAndUpdateRequest:
Payload Template
```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**
| Headers | MessageProperties
|---------------------------------------|---------------------------------
| type=EVENT <br /> tenant=tenant123 <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#"
}
]
}]
}
```

78
docs/content/apis/management_api.md Normal file
View File

@@ -0,0 +1,78 @@
---
title: Management API
parent: API
weight: 81
---
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).
<!--more-->
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 are:
- GET
- POST
- PUT
- DELETE
Available Management APIs resources are:
- [Targets](/hawkbit/apis/mgmt/targets/)
- [Distribution sets](/hawkbit/apis/mgmt/distributionsets/)
- [Distribution set types](/hawkbit/apis/mgmt/distributionsettypes/)
- [Software modules](/hawkbit/apis/mgmt/softwaremodules/)
- [Software module types](/hawkbit/apis/mgmt/softwaremoduletypes/)
- [Target tag](/hawkbit/apis/mgmt/targettag/)
- [Distribution set tag](/hawkbit/apis/mgmt/distributionsettag/)
- [Rollouts](/hawkbit/apis/mgmt/rollouts/)
- [Target filters](/hawkbit/apis/mgmt/targetfilters/)
- [System configuration](/hawkbit/apis/mgmt/tenant/)
## Headers
For all requests an `Authorization` header has to be set.
* Username: `Tenant\username`
* Password: `password`
Also have a look to the [Security](../../concepts/authentication/) 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"
}
```

0
docs/content/apis/mgmt/_index.md Normal file
View File

7
docs/content/apis/mgmt/distributionsets.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Distribution Sets API
parent: Management API
weight: -101
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/distributionsets-api-guide/"></iframe>

7
docs/content/apis/mgmt/distributionsettag.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Distribution Set Tag API
parent: Management API
weight: -105
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/distributionsettag-api-guide/"></iframe>

7
docs/content/apis/mgmt/distributionsettypes.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Distribution Set Types API
parent: Management API
weight: -102
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/distributionsettypes-api-guide/"></iframe>

7
docs/content/apis/mgmt/rollouts.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Rollouts API
parent: Management API
weight: -106
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/rollout-api-guide/"></iframe>

7
docs/content/apis/mgmt/softwaremodules.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Software Modules API
parent: Management API
weight: -103
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/softwaremodules-api-guide/"></iframe>

7
docs/content/apis/mgmt/softwaremoduletypes.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Software Module Types API
parent: Management API
weight: -100
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/softwaremoduletypes-api-guide/"></iframe>

7
docs/content/apis/mgmt/targetfilters.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Target Filters API
parent: Management API
weight: -107
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/targetfilters-api-guide/"></iframe>

7
docs/content/apis/mgmt/targets.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Targets API
parent: Management API
weight: -100
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/targets-api-guide/"></iframe>

7
docs/content/apis/mgmt/targettag.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Target Tag API
parent: Management API
weight: -104
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/targettag-api-guide/"></iframe>

7
docs/content/apis/mgmt/tenant.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: System Configuration API
parent: Management API
weight: -108
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/tenant-api-guide/"></iframe>

7
docs/content/architecture.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Architecture
weight: 60
---
Overview of hawkBit modules and used 3rd party technology:
![](../images/architecture/architecture.png)

35
docs/content/community.md Executable file
View File

@@ -0,0 +1,35 @@
---
title: Community
weight: 90
---
## Presentations
Here you can find links to arbitrary material covering Eclipse hawkBit which has been presented at events, conferences and meet-ups.
- 09/23/2015 - Eclipse IoT Working Group meeting - [slides](https://docs.bosch-iot-rollouts.com/slides/hawkBitProposal20150923.html)
- 04/11/2015 - EclipseCon Europe 2015 - [slides](https://docs.bosch-iot-rollouts.com/slides/eclipseCon2015.html)
- 03/09/2016 - EclipseCon North America 2016 - [slides](https://docs.bosch-iot-rollouts.com/slides/eclipseConNA2016.html)
- 05/16/2016 - Eclipse Virtual IoT Meetup - [video](https://www.youtube.com/watch?v=g-dhKMaaanE) - [slides](https://docs.bosch-iot-rollouts.com/slides/virtualIoTMeetup2016.html)
- 03/20/2017 - Eclipse IoT Day SanJose, CA - [video](https://www.youtube.com/watch?v=x5OfBgnYW44) - [slides](https://docs.bosch-iot-rollouts.com/slides/iotDaySanJose2017.pdf)
- 09/12/2017 - Eclipse IoT Day ThingMonk 2017 - [video](https://www.youtube.com/watch?v=7hK-kiQjKGA)
- 01/10/2018 - Eclipse Virtual IoT Meetup - [video](https://www.youtube.com/watch?v=8vcLXs9lc-4) - [slides](https://docs.bosch-iot-rollouts.com/slides/hawkBitIntroduction.html)
## Articles
- 10/27/2015 - Why software provisioning goes open source - [article](http://blog.bosch-si.com/categories/technology/2015/10/software-provisioning-goes-open-source-find/)
- 05/25/2016 - jaxenter: Eclipse hawkBit - [english](https://jaxenter.com/eclipse-hawkbit-126445.html) - [german](https://jaxenter.de/eclipse-hawkbit-46372)
- 09/27/2016 - Eclipse Newsletter - 'IoT is the new black' - [article](http://www.eclipse.org/community/eclipse_newsletter/2016/september/article2.php)
## Chat
Questions? Problems? Searching for a quick response from the team behind hawkBit and from the hawkBit community, join the [Gitter Chat](https://gitter.im/eclipse/hawkbit).
## Mailing List
A great way to stay up to date with hawkBit activity is to subscribe to the Mailing list provided by Eclipse. Sign up for the mailing list [here](https://dev.eclipse.org/mailman/listinfo/hawkbit-dev).
## Issue Tracker
Issues and bugs related to hawkBit are tracked with the Github Issue tracking system. If you find any issues, please report them [here](https://github.com/eclipse/hawkbit/issues).
## Contributing
An overview of the contribution process is [here](https://wiki.eclipse.org/Development_Resources/Contributing_via_Git). Checkout the [Contribution Guidelines](https://github.com/eclipse/hawkbit/blob/master/CONTRIBUTING.md) on the Eclipse hawkBit GitHub Repository.

73
docs/content/concepts/authentication.md Normal file
View File

@@ -0,0 +1,73 @@
---
title: Authentication
parent: Concepts
weight: 51
---
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.
- _Management UI_ by **users**.
<!--more-->
## 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_.
```
GET /SPDEMO/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](../../apis/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 API](../../apis/management_api/) or in the [Management UI](../../ui) in the target details.
Note: needs to be enabled in your hawkBit installation **and** in the tenant configuration. That allows both the operator as well as the individual customer (if run in a multi-tenant setup) to enable this access method. See [DdiSecurityProperties](https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java) for system wide enablement.
The additional activation for the individual tenant:
![Enable Target Token](../../images/security/targetToken.png)
#### 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.
```
GET /SPDEMO/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 **and** in the tenant configuration. That allows both the operator as well as the individual customer (if run in a multi-tenant setup) to enable this access method. See [DdiSecurityProperties](https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java) for system wide enablement.
The additional activation for the individual tenant:
![Enable Gateway Token](../../images/security/gatewayToken.png)
#### Anonymous access
Here we offer general anonymous access for all targets (see [DdiSecurityProperties](https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java)) which we consider not really sufficient for a production system but it might come in handy to get a project started in the beginning.
However, anonymous download on the other side might be interesting even in production for scenarios where the artifact itself is already encrypted.
The activation for the individual tenant:
![Enable Anonymous Download](../../images/security/anonymousDownload.png)
## 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
## Management UI
- Login Dialog

62
docs/content/concepts/authorization.md Normal file
View File

@@ -0,0 +1,62 @@
---
title: Authorization
parent: Concepts
weight: 52
---
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/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/im/authentication/SpPermission.java).
<!--more-->
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. Check out [Spring security documentation](http://projects.spring.io/spring-security/) for further information. In hawkBit [SecurityAutoConfiguration](https://github.com/eclipse/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.
## 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
### Delivered Permissions
- READ_/UPDATE_/CREATE_/DELETE_TARGETS 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
- READ_TARGET_SECURITY_TOKEN
- Permission to read the target security token. The security token is security concerned and should be protected.
- DOWNLOAD_REPOSITORY_ARTIFACT
- Permission to download artifacts of an software module (Note: READ_REPOSITORY allows only to read the metadata).
- TENANT_CONFIGURATION
- Permission to administrate the tenant settings.
- ROLLOUT_MANAGEMENT
- Permission to provision targets through rollouts.
### 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_TARGET, READ_REPOSITORY
Assign _DS_ to a _target_ | READ_REPOSITORY, UPDATE_TARGET
Assign DS to target through a _Rollout_, i.e. _Rollout_ creation and start | READ_REPOSITORY, UPDATE_TARGET, ROLLOUT_MANAGEMENT
Read _Rollout_ status including its _deployment groups_ | ROLLOUT_MANAGEMENT
Checks _targets_ inside _Rollout deployment group_ | READ_TARGET, ROLLOUT_MANAGEMENT
## 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.

49
docs/content/concepts/datamodel.md Normal file
View File

@@ -0,0 +1,49 @@
---
title: Data Model
parent: Concepts
weight: 53
---
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.
## 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.
{{% note %}}
In case of 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).
{{% /note %}}

49
docs/content/concepts/rollout-management.md Normal file
View File

@@ -0,0 +1,49 @@
---
title: Rollout Management
parent: Concepts
weight: 54
---
Software update operations in large scale IoT scenarios with hundreds of thousands of devices require special handling.
<!--more-->
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
![](../../images/rolloutstatediagram.png)
### State Machine on Rollout Deployment Group
![](../../images/rolloutgroupstatediagram.png)

21
docs/content/concepts/targetstate.md Normal file
View File

@@ -0,0 +1,21 @@
---
title: Target State Machine
parent: Concepts
weight: 55
---
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".
<!--more-->
## 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
![](../../images/architecture/targetStatusStates.png)

63
docs/content/features.md Normal file
View File

@@ -0,0 +1,63 @@
---
title: Features
weight: 40
---
## Device and software repository
- Repository that holds the provisioning targets and assignable software distributions.
- That includes a full software update history for every device.
- Support for pre-commission devices in the repository and plug and play, i.e. device is created if it is authenticated for the first time.
## Update Management
- Directly deploy a defined software distribution to a device (by Management UI or API).
- Update handling is independent of the device type, integration approach or connectivity.
## Management UI
- Create/Read/Update/Delete operations for provisioning targets (i.e. devices) and repository content (i.e. software).
- Manage and monitor software update operations.
- Optimized for professional users, e.g. administrators, developers and 2nd/3rd level support staff.
- Ease of use drag-and-drop paradigm.
- Flexible grouping of data.
- Flexible filters for data browsing.
- Responsive to resolution.
- Lazy loading of data.
- All information on one page.
- Optional integration with Bosch IoT Permissions service for full multi user support with fine granular permission based authorization.
## Artifact Content Delivery
- Partial downloads supported.
- Download resume supported (RFC7233).
- Content management by RESTful API and UI (see above).
- Authorization based on software assignment, i.e. a device can only download what has been assigned to it in the first place.
- Delta artifact hosting supported.
- Artifact signature hosting supported.
## 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 the rollout progress.
- Emergency rollout shutdown in case of update failures.
## Interfaces
### Management API
- RESTful API
- Create/Read/Update/Delete operations for provisioning targets (i.e. devices) and repository content (i.e. 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](https://www.rabbitmq.com/amqp-0-9-1-reference.html) messaging interface.
- Separate AMQP vHost per tenant for maximum security.

57
docs/content/gettingstarted.md Executable file
View File

@@ -0,0 +1,57 @@
---
title: Getting Started
weight: 20
---
## From Docker Image
### Update server only
```sh
$ docker run -d -p 8080:8080 hawkbit/hawkbit-update-server
```
### Updates server + MySql + RabbitMq
```sh
$ git clone https://github.com/eclipse/hawkbit.git
$ cd hawkbit/hawkbit-runtime/hawkbit-update-server/docker
$ docker-compose up -d
```
## From Sources
### Clone and build hawkBit
```sh
$ git clone https://github.com/eclipse/hawkbit.git
$ cd hawkbit
$ mvn clean install
```
### Start hawkBit
[update server](https://github.com/eclipse/hawkbit/tree/master/hawkbit-runtime/hawkbit-update-server)
```sh
$ java -jar ./hawkbit-runtime/hawkbit-update-server/target/hawkbit-update-server-#version#-SNAPSHOT.jar
```
### Build hawkBit examples
```sh
$ git clone https://github.com/eclipse/hawkbit-examples.git
$ cd hawkbit-examples
$ mvn clean install
```
### Start hawkBit device simulator
[Device Simulator](https://github.com/eclipse/hawkbit-examples/tree/master/hawkbit-device-simulator)
```sh
$ java -jar ./hawkbit-device-simulator/target/hawkbit-device-simulator-#version#.jar
```
### Generate Getting Started data
[Example Management API Client](https://github.com/eclipse/hawkbit-examples/tree/master/hawkbit-example-mgmt-simulator)
```sh
$ java -jar ./hawkbit-example-mgmt-simulator/target/hawkbit-example-mgmt-simulator-#version#.jar
```

48
docs/content/guides/clustering.md Normal file
View File

@@ -0,0 +1,48 @@
---
title: Clustering
parent: Guides
weight: 33
---
hawkBit is able to run in a cluster with some constraints. This guide provides insights in the basic concepts and how to setup your own cluster. You can find additional information in the [hawkBit runtimes's README](https://github.com/eclipse/hawkbit/blob/master/hawkbit-runtime/hawkbit-update-server/README.md).
<!--more-->
## Big picture
![](../../images/overall_cluster.png)
## 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](http://docs.spring.io/spring-cloud-stream/docs/current/reference/htmlsingle/#_binders) available. The _hawkbit Update Server_ uses RabbitMQ binder. Every node gets his 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:
![](../../images/eventing-within-cluster.png)
Via the ServiceMatcher you can check whether an event happened locally at one node or on a different node.
`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/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
### UI sessions
As of today hawkBit is not storing user sessions in a shared, cluster wide cache. Session is only bound to the node where the login took place. If this node is going down for whatever reason, the session is lost and the user is forced to login again.
In case that's not an option, you can help yourself by introducing a shared session cache based on e.g. Redis.
Furthermore hawkBit is not supporting session stickiness out of the box either. However most of the well known load balancer out there can solve this issue.
### Caching of download IDs
The downloadId is generated and stored in the DownloadIdCache. It is used for downloading an artifact.
In hawkBit exists an interface called "[DownloadIdCache](https://github.com/eclipse/hawkbit/blob/master/hawkbit-core/src/main/java/org/eclipse/hawkbit/cache/DownloadIdCache.java)" and one implementation of it: "DefaultDownloadIdCache". This default implementation can't be used within a cluster. Its containing data is only available inside one node and can't be shared with other nodes. E.g. the downloadId which is stored in this cache after authentication on node A can only be used for downloading the artifact by node A.
In a cluster-capable environment this fact can lead to issues as it could happen, that the downloadId is stored on node A and node B would like to download the artifact by means of the downloadId which is not available on node B. To solve this issue you can use a cluster-shared cache e.g. Redis or create a new cluster-aware implementation of the interface "DownloadIdCache".
### Denial-of-Service (DoS) filter
hawkBit owns the feature of guarding itself from DoS attacks, a [DoS filter](https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DosFilter.java). It reduces the maximum number of requests per seconds 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 seconds 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.

50
docs/content/guides/customtheme.md Normal file
View File

@@ -0,0 +1,50 @@
---
title: Custom Theme
parent: Guides
weight: 34
---
This guide provides details about using and creating themes that control the visual look of Eclipse hawkBit Management UI. Theme customization is done using Sass, which is an extension of CSS (Cascading Style Sheets).
<!--more-->
The mechanism described below is the rather simple case by customizing the theme by means of configuring a set of variables as defined by the hawkBit default theme. A full customization be means of copying the hawkBit theme and customize it completely is not described here but of course possible.
## Example App
An example application with customized theme can be found [here](https://github.com/eclipse/hawkbit-examples/tree/master/hawkbit-custom-theme-example).
## Overview
Vaadin separates the appearance of the user interface from its logic using themes. Themes can include Sass or CSS style sheets, custom HTML layouts, and any necessary graphics.
Theme resources can also be accessed from application code as ThemeResource objects. Custom themes are placed under the src/main/resources/VAADIN/themes/ folder of the application.
This location is fixed -- the VAADIN folder contains static resources that are served by the Vaadin servlet. The servlet augments the files stored in the folder by resources found from corresponding VAADIN folders contained in JARs in the class path.The base theme and all the corresponding custom themes are placed under the above mentioned folder.
If a new custom theme has to be created, it should always be placed under the src/main/resources/VAADIN/themes/ folder.
Every custom theme should always refer the base theme and customization can be done by the use of variables mentioned in the XXXXvariable.scss. For details of the creation of the custom theme please refer the next section.
## Procedure to create a theme
- Create a new folder **"XXXtheme"** (significant to the new theme) under src/main/resources/VAADIN/themes/ folder.
- Create a folder named as **"customstyles"**.
- Create a **XXXvariables.scss** file under **customstyles** folder, putting all the variables inside the same file. For more details about the variables we recommend to take a look at the [hawkBit defaults](https://github.com/eclipse/hawkbit/blob/master/hawkbit-ui/src/main/resources/VAADIN/themes/hawkbit/customstyles/hawkbitvariables.scss).
- Create **styles.scss** file under the **"XXXtheme"** folder.
- Any images should be placed under the sub folder **"images"** folder.
- Within the **_styles.scss_** file, import **XXXvariables.scss** and the base theme (hawkBit theme as mentioned in previous chapter **Overview** . Please find below the syntax:
```css
@import "../hawkbit/customstyles/hawkbitvariables";
@import "customstyles/examplevariables";
@import "../hawkbit/hawkbittheme";
@import "addons";
.exampletheme {
@include addons;
@include hawkbittheme;
}
```
- Finally the structure should be as in the [example app](https://github.com/eclipse/hawkbit-examples/tree/master/hawkbit-custom-theme-example/src/main/resources/VAADIN).
## Procedure to add a custom footer
- Any footer can be added by creating "footer.html" in **src/main/resources --> VAADIN -- themes --> {XXXtheme} --> layouts** folder. An example can be found [here](https://github.com/eclipse/hawkbit/blob/master/hawkbit-ui/src/main/resources/VAADIN/themes/hawkbit/layouts/footer.html).

62
docs/content/guides/feignclient.md Normal file
View File

@@ -0,0 +1,62 @@
---
title: Feign Client
parent: Guides
weight: 32
---
In this guide we describe how to create a [Feign](https://github.com/Netflix/feign) Rest Client based on a [Spring Boot](http://projects.spring.io/spring-boot/) Application.
<!--more-->
## Create Feign REST Client
hawkBit provides REST interfaces for [Management API](https://github.com/eclipse/hawkbit/tree/master/hawkbit-ddi-api) and [DDI API](https://github.com/eclipse/hawkbit/tree/master/hawkbit-ddi-api). Using this interfaces you can create a feign client with the help of the [feign inheritance support](http://projects.spring.io/spring-cloud/spring-cloud.html#spring-cloud-feign-inheritance).
Our [example](https://github.com/eclipse/hawkbit-examples) modules demonstrate how to create [Feign](https://github.com/Netflix/feign) client resources. Here you can find the [Management API client resources](hhttps://github.com/eclipse/hawkbit-examples/tree/master/hawkbit-example-mgmt-feign-client) and the [DDI client resources](https://github.com/eclipse/hawkbit-examples/tree/master/hawkbit-example-ddi-feign-client).
A small [simulator application](https://github.com/eclipse/hawkbit-examples/tree/master/hawkbit-example-mgmt-simulator) demonstrates how you can interact with the hawkBit via the [Management API
](http://www.eclipse.org/hawkbit/documentation/interfaces/management-api.html).
## Example Management API simulator
In the follow code section, you can a see a feign client resource example. The interface extend the origin api interface to declare the `@FeignClient`. The `@FeignClient`declares that a REST client with that interface should be created.
```Java
@FeignClient(url = "${hawkbit.url:localhost:8080}/" + MgmtRestConstants.TARGET_V1_REQUEST_MAPPING)
public interface MgmtTargetClientResource extends MgmtTargetRestApi {
}
```
This interface can be autowired and use as a normal java interface:
```Java
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));
}
```
At [hawkbit-example-core-feign-client](https://github.com/eclipse/hawkbit-examples/tree/master/hawkbit-example-core-feign-client) is a spring configuration to auto configure some beans, which can be reused for a 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();
}
}
```

96
docs/content/guides/runhawkbit.md Normal file
View File

@@ -0,0 +1,96 @@
---
title: Run hawkBit
parent: Guides
weight: 31
---
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.
<!--more-->
{{% note %}}
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.
{{% /note %}}
## System Architecture
This guide describes a target architecture that is more like one that you will expect in a production system.
- hawkBit [Update Server](https://github.com/eclipse/hawkbit/tree/master/hawkbit-runtime/hawkbit-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-examples/tree/master/hawkbit-device-simulator).
- [hawkBit Management API example client](https://github.com/eclipse/hawkbit-examples/tree/master/hawkbit-mgmt-api-client).
## Prerequisites
- You have a working [hawkBit core build](https://github.com/eclipse/hawkbit).
- You have a working [hawkBit examples build](https://github.com/eclipse/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.
### Set MariaDB dependency to compile in the [update server POM](https://github.com/eclipse/hawkbit/blob/master/hawkbit-runtime/hawkbit-update-server/pom.xml)
```xml
<dependency>
<groupId>org.mariadb.jdbc</groupId>
<artifactId>mariadb-java-client</artifactId>
<scope>compile</scope>
</dependency>
```
### 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).
```
spring.jpa.database=MYSQL
spring.datasource.url=jdbc:mysql://localhost:3306/YOUR_SCHEMA
spring.datasource.username=YOUR_USER
spring.datasource.password=YOUR_PWD
spring.datasource.driverClassName=org.mariadb.jdbc.Driver
```
### Configure RabbitMQ connection settings for update server and device simulator (optional).
We provide already defaults that should work with a standard Rabbit installation. Otherwise configure the following in the `application.properties` of the two services:
```
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-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:
```
hawkbit.url=localhost:8080
```
or provide the parameter on command line:
```
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/tree/master/hawkbit-runtime/hawkbit-update-server)
### Compile & Run example scenario [creation script](https://github.com/eclipse/hawkbit-examples/tree/master/hawkbit-example-mgmt-simulator) (optional).
This has to be done before the device simulator is started. hawkBit creates the mandatory tenant metadata with first login into either _Management UI_ or 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-examples/tree/master/hawkbit-device-simulator)
# Enjoy hawkBit with a real database, artifact storage and all [interfaces](../../apis/) available.
![](../../images/hawkbit_ui.png)

113
docs/content/news/2018-07-26-first-release.md Normal file
View File

@@ -0,0 +1,113 @@
---
title: Eclipse hawkBit 0.2.0 - First Release
weight: -200
---
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. It is part of the Eclipse IoT
since 2015 and with version _0.2.0_ a first release is available.
In this article, we want to give an overview of the latest highlights of hawkBit and let you know how you can get
started in seconds.
## Finally, it is here!
After being around in the Eclipse IoT realm for quite some time now, we are more than happy to announce our first release:
[_Eclipse hawkBit 0.2.0_](https://projects.eclipse.org/projects/iot.hawkbit/releases/0.2.0). The release can be found on [Maven Central](https://mvnrepository.com/artifact/org.eclipse.hawkbit)
and [Docker Hub](https://hub.docker.com/r/hawkbit/hawkbit-update-server/). It includes the following core features:
* Device and Software Repository
* Update Management
* Artifact Content Delivery
* Rollout Management
The features are accessible via the following interfaces:
* Management UI
* Management API
* Direct Device Integration (DDI) API
* Device Management Federation (DMF) API
![hawkBit Overview](../../images/hawkBit_overview.jpeg)
## What's new?
Whenever there is a new release, the first question that comes to mind is: What's new? Since this is our first release,
one could argue that everything is new. However, most of the features are already well-established. This holds true, for
example, for our APIs or the Rollout Management. Nevertheless, there have been some recent updates to hawkBit, which we
do not want to leave unmentioned:
### Streamlined UI
The probably most noticeable change has been the removal of the two buttons (`Drop here to delete` and `Actions`) at the
bottom of the _Deployment_, _Distributions_, and _Upload_ view. This is a major usability improvement! For example,
deleting an item required (1) dragging an item onto the delete button, (2) opening the delete pop-up, and (3) confirming
the deletion. Now, an item can be easily removed by clicking on its remove icon and confirming the action. Moreover,
multiple (or all `CTRL` + `A`) items can be selected and removed at once using the same mechanism. This is not only
faster and more intuitive, it also saves a lot of display real estate which can now be used to focus on what is important.
We hope you like this change as much as we do! _(Requires: hawkBit > 0.2.2)_
![Screenshot of improved UI](../../images/hawkbit_ui.png)
### MS SQL Server
Eclipse hawkBit supports a range of different SQL databases. Up to now, these have been the internal H2 database (which can be
used for testing, development, or trial) and MySQL/MariaDB for production-grade usage. This list is now extended by
Microsoft's SQL Server which is also available in production grade, as well as, IBM's DB2 for testing and development.
### Open Sourced REST docs
A huge benefit for the community is the recently open sourced REST docs of hawkBit. This has been an [open request](https://github.com/eclipse/hawkbit/issues/480)
for some time, which we were happy to meet. The documentation is generated using [Spring REST docs](https://spring.io/projects/spring-restdocs), based on unit-tests. These tests, with the respective documentation, are now available in the [code base](https://github.com/eclipse/hawkbit/pull/688).
Furthermore, the API documentation will be hosted on our new [website](https://www.eclipse.org/hawkbit/) (coming soon).
### Docker Images
In order to enable interested parties to get started with hawkBit conveniently, we decided to provide the
[Update Server as a Docker image](https://hub.docker.com/r/hawkbit/hawkbit-update-server/) on Docker Hub. The image comes
in two flavors: The default image uses the internal H2 database, while the images with a `-mysql` suffix contain the MySQL
driver to allow connecting a MySQL database. In addition to the Docker image, the hawkBit repository contains a
[docker-compose.yml](https://github.com/eclipse/hawkbit/blob/master/hawkbit-runtime/hawkbit-update-server/docker/docker-compose.yml)
that not only starts the Update Server, but further includes a MySQL database and a RabbitMQ message broker so you're
able to use Device Management Federation (DMF) as well.
To start the hawkBit Update Server image, open a terminal and run:
```
$ docker run -d -p 8080:8080 hawkbit/hawkbit-update-server
```
{{% note %}}
_Note: This requires a running [Docker deamon](https://docs.docker.com/install/) on your system._
{{% /note %}}
Now, browse to [http://localhost:8080](http://localhost:8080) and log-in with `admin:admin`. There you go!
## Community Updates
Although features and functionality play a major role in the hawkBit project, there is also some interesting news from
the community. As of July 2018, there have been:
* Pull Requests: 587
* Forks: 54
* Stars: 137
* Contributors: 25
* Gitter Chat members: 119
### New Project Lead and Committers
We are happy to announce that the hawkBit project got a new project lead. In addition to
[Kai Zimmermann](https://projects.eclipse.org/user/6364), project lead from the first hour,
[Jeroen Laverman](https://projects.eclipse.org/user/10982) joined the lead to support him in this responsibility.
Moreover, with [Stefan Behl](https://projects.eclipse.org/user/10842) and Jeroen Laverman, two new committers are aboard.
## What's next?
Looking ahead, there are two major topics that we want to tackle next: First, there is the migration of our UI from Vaadin
7 to Vaadin 8, since Vaadin announced the end-of-life for our current version. Another big topic will be the update
to Spring Boot 2. On the community side, we are in the final stage of updating our [website](https://www.eclipse.org/hawkbit/)
with a new design, so make sure you stop by in a couple of days to check it out. Finally, the hawkBit team will be
present at EclipseCon Europe 2018, so if you are interested in meeting us, that is the place to be.

0
docs/content/news/_index.md Normal file
View File

32
docs/content/release-notes.md Executable file
View File

@@ -0,0 +1,32 @@
---
title: Release Notes
weight: 100
---
## 0.2.1
**Release Date:** Friday, July 6, 2018 <br />
[Tag](https://github.com/eclipse/hawkbit/releases/tag/0.2.1) /
[Release](https://github.com/eclipse/hawkbit/milestone/9?closed=1)
## 0.2.0
First Eclipse hawkBit release including:
* **Core features:**
* Device and Software Repository
* Update Management Management UI/Console
* Artifact Content Delivery
* Rollout/Campaign Management
* **Interfaces:**
* Management API
* Direct Device Integration (DDI) API
* Device Management Federation (DMF) API
**Release Date:** Friday, June 15, 2018 <br />
[Tag](https://github.com/eclipse/hawkbit/releases/tag/0.2.0) /
[Release](https://github.com/eclipse/hawkbit/milestone/1?closed=1) /
[Eclipse](https://projects.eclipse.org/projects/iot.hawkbit/releases/0.2.0)

0
docs/content/rest-api/_index.md Normal file
View File

141
docs/content/ui.md Normal file
View File

@@ -0,0 +1,141 @@
---
title: Management UI
weight: 70
---
The hawkBit Management UI provides several views for the different use cases:
- _Deployment Management_ view for target administration and manual deployment.
- _Distribution Management_ view software repository metadata management.
- _Artifact Management_ view to manage the artifacts.
- _Target Filter Management_ view to manage target filters that can be used both in Deployment and Rollout Management views.
- _Rollout Management_ for large scale rollout orchestration.
## Deployment Management
### Purpose
Target status overview, target management and manual deployments.
### Feature explained
- Target Status: check status of all targets.
- Target list allows filters based on:
- Assigned/installed _DistributionSet_ (drag and drop a set on the filter icon on the top of the list)
- Target update status: click 1-X status to reduce the list of targets that have one of them.
- Target tag: click 1-X tags to reduce the list to targets that have one of them.
- Name, description: use search button on the top of the list.
- _DistributionSet_ list allows filters based on:
- _DistributionSet_ tag: click 1-X tags to reduce the list of sets that have one of them.
- Name, description: use search button on the top of the list.
- Start roll out by drag and drop targets on a DS.
- Target list supports CTRL-A for "select all".
- Delete sets, tags or targets by dragging them on delete icon.
- Select _Target_ to see _Action_ History.
- Bulk target upload: create bulk targets by upload.
Hints for bulk upload:
- Expected file type : csv.
- Expected file format : Each line with two values (ControllerID,Target Name). ControllerID is mandatory.
- Example:
```
Controller_id_1,targetName1
Controller_id_2,targetName2
```
![Deployment Management view](../images/ui/deployment_mgmt.png)
## Distribution Management
### Purpose
Distribution Set view to manage software repository metadata, i.e. Distribution Sets, their Software Modules and the respective types.
### Features explained
- Browse, create, delete and update Distribution Sets.
- Browse, create, delete and update Distribution Set Types.
- Browse, create, delete and update Software Modules.
- Browse, create, delete and update Software Module Types.
- Assign Software Modules to Distribution Sets.
![Distribution Management view](../images/ui/distribution_mgmt.png)
## Artifact Management
### Purpose
Software artifact management, both metadata (i.e. Software Modules) and artifacts themselves.
### Features explained
- Browse, create, delete and update Software Modules.
- Browse, create, delete and update Software Module Types.
- Upload and delete software artifacts for a module.
![Artifact Management view](../images/ui/artifact_mgmt.png)
## Rollout Management
### Purpose
Software rollout in large scale, rollout status overview and rollout management.
### Features explained
- Create, update, copy and delete of rollouts.
- Start, pause and resume of rollouts.
- Progress monitoring for the entire rollout and the individual groups.
- Drill down to see the groups in a rollout and targets in each group.
- Rollout attributes:
- Selection of targets as input for the rollout based on _target filter_
- Selection of _distribution set_
- Auto-splitting of the input target list based on _group number_ defined
- _Trigger threshold_ to define the percentage of installation to be completed , to trigger the start of next group
- _Error threshold_ defines the percentage of error tolerance of a group before calling for a emergency shutdown of a rollout
![Rollout Management view](../images/ui/rollout_mgmt.png)
![Rollout Management view](../images/ui/rollout_groups.png)
{{% note %}}
Deletion of targets which are in a rollout, changes the rollout statistics.
{{% /note %}}
## Target Filter Management
### Purpose
Custom target filter overview and filter management.
### Features explained
- Custom target filter allows user to filter targets by defining custom query.
- Displays custom target filter list and user can search any particular filter.
- Create, update and delete features are supported for target filters.
### How to Filter
The basic syntax to filter is: `field<basic_operator>value <composite_operator> field<basic_operator>value <...>`
- `field`: is the name of the resource field.
- `value`: is the value of the target field
- `<basic_operator>`: Are operators to do simple queries. Supported basic operators are:
- `==` : equal
- `!=` : not equal
- Use `=IN=` for 'in' parameter.(Example: name=IN=(target1,target2).
- `<composite_operator>`: Are operators to join simple queries: Supported composite operators are:
- `and`
- `or`
- Use `=IN=` for 'in' parameter.(Example: name=IN=(target1,target2).
- Use `*` for wildcard matches.
### Examples
Custom query | Description
------------------------------------------------------------------------------------------ | -----------------------------------------------------------------------------------------------------------------------------------------------------
updatestatus==error | Gives all targets in ‘error’ state.
controllerId!=192.168.2.42 | Gives all targets that do not have the controllerId 192.168.2.42.
name==\*CCU\* | Gives all targets which contain the term ‘CCU’ in there name.
name==\*CCU\* or description==\*CCU\* | Gives all targets that either have the term ‘CCU’ in their name or their description.
name==\*SHC\* and description==\*SHC\* | Gives all targets that have the term SHC in their name and their description.
name==CCU* and updatestatus==pending | Gives all targets with their name starting with ‘CCU’ and which are in ‘pending’ state.
(assignedds.name==‘ECU-DS’ and description==test) or updatestatus!=error | Gives all targets which are either assigned to ‘ECU-DS’ and have description equals to ‘test’ or which are not in error status.
(updatestatus!=In\_sync or updatestatus!=error) and name==\*SHC1\* | Gives all targets that do not have the update status In\_sync or error and that contains the term SHC1 in their name.
(updatestatus!=error or updatestatus!=pending) and (name==\*CCU\* or description==\*CCU\*) | Gives all targets that either have the term ‘CCU’ in their name or their description and that either have the _update status_ not in state error or pending.
![Target Filter Management view](../images/ui/target_filter.png)

43
docs/content/whatishawkbit.md Executable file
View File

@@ -0,0 +1,43 @@
---
title: What is hawkBit?
weight: 10
---
Eclipse hawkBit&trade; is an 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.
![](../images/hawkbit_logo.png)
## 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 updateable, i.e. they do not only buy a product because of its current feature set but make also 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 as, at the one hand, it can be used to fix almost any issue/problem on the device but at the same time also poses the greatest security threat if mis-used 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 roll out campaign for a large number of devices, orchestrating content delivery networks to distribute the package, monitoring and reporting the progress of the roll-out 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 roll outs at IoT scale**, e.g. splitting the roll out into sub groups, cascading them, automatically stopping the roll out after a defined error threshold etc. 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 only 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
* that goes beyond the pure update and handles more complex **roll out strategies** needed by large scale IoT projects.
* that 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.