From 87107ef724c093e30d327575fcd9b8f5487f5d4e Mon Sep 17 00:00:00 2001 From: Avgustin Marinov Date: Thu, 14 Sep 2023 15:40:09 +0300 Subject: [PATCH] Documentations fixes & epl 2.0 news (#1429) Signed-off-by: Marinov Avgustin --- docs/README.md | 7 +- docs/content/concepts/authentication.md | 104 +-- docs/content/news/2023-09-21-epl2.0.md | 19 + docs/install-theme.bat | 2 +- .../static/news/2018-07-26-first-release.html | 653 ------------------ 5 files changed, 83 insertions(+), 702 deletions(-) create mode 100644 docs/content/news/2023-09-21-epl2.0.md delete mode 100644 docs/static/news/2018-07-26-first-release.html diff --git a/docs/README.md b/docs/README.md index 66bb970ea..16b66d957 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,12 +11,11 @@ theme. Compiling the documentation is not included within the regular Maven buil The following Maven targets are available in order to build and serve the documentation: * `mvn install`: _i._ Copies the generated REST docs to `content/rest-api/` and _ii._ downloads the required Hugo theme -* `mvn site`: Serve the documentation on [localhost:1313/hawkbit/](localhost:1313/hawkbit/) +* `mvn site`: Serve the documentation on [localhost:1313/hawkbit/](http://localhost:1313/hawkbit/) + + _Note_: the local port could be different. Please, look at the _mvn site_ command output. * `mvn clean`: Delete generated artifacts (REST docs, Hugo theme) -_Note: Currently, **only** Unix/macOS is supported! For Windows, use the hugo commands in CMD._ - - ## Generate /public folder In order to generate the `/public` folder, which can be put on a web-server, run the following command: diff --git a/docs/content/concepts/authentication.md b/docs/content/concepts/authentication.md index 99952256b..2fc7bdae9 100644 --- a/docs/content/concepts/authentication.md +++ b/docs/content/concepts/authentication.md @@ -64,26 +64,59 @@ The activation for the individual tenant: ### Certificate Authentication by Reverse Proxy -hawkBit offers a certificate-based authentication mechanism, referred to as Mutual TLS, which eliminates the need to share a security token with the server. To implement this, you'll require a reverse proxy deployed before the hawkBit server to handle authentication. This process involves obtaining certificates for both the client and the reverse proxy and configuring hawkBit accordingly. +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 for these components, which is not covered in this description. Once you have acquired certificates for both the client and the Hawkbit server, whether from the same or different Certificate Authorities (CAs), you'll need to place these certificates in their respective locations. +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 SSL Issuer(s) hash of the presented client certificate shall be set for the tenant. For that, in Hawkbit's UI section, under system configuration, you shall enable 'Allow targets to authenticate via a certificate by an reverse proxy' and set the hash of the client certificate issuer(s) (as a comma separated list). + +![Example Reverse Proxy Settings](../../images/security/exampleReverseProxySettings.png) + +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 has the server.crt, server.key and client_ca.crt - -Here is an example diagram that shows all the communication between the hawkBit, reverse proxy and client. +- 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 ![Example Reverse Proxy Architecture](../../images/security/exampleReverseProxyArchitecture.png) -#### Example Nginx Reverse Proxy Configurations -After placing your certificates, 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: +#### Example - Nginx Reverse Proxy Configurations -`hawkbit.dev.example.com/default/controller/` +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. -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. +1. Hawkbit Configurations + + There are also some configurations that you need update when you deployed your hawkbit service. + + You need to add the given download settings 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. Don't forget to replace "hostname" with your actual hostname. + +``` +hawkbit.artifact.url.protocols.download-http.rel=download-http +hawkbit.artifact.url.protocols.download-http.hostname=hawkbit.dev.example +hawkbit.artifact.url.protocols.download-http.protocol=https +hawkbit.artifact.url.protocols.download-http.supports=DMF,DDI +hawkbit.artifact.url.protocols.download-http.ref={protocol}://{hostnameRequest}/{tenant}/controller/v1/{controllerId}/softwaremodules/{softwareModuleId}/artifacts/{artifactFileName} +``` + +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 @@ -157,15 +190,8 @@ server { } } ``` -To authenticate the request to Hawkbit itself, the common name and issuer hash of the presented client certificate are required. The issuer hash of a certificate is the hash of the certificate that signed the client certificate, which in our case is the CA. - -You can use the following command to get the issuer hash: - -`openssl x509 -in client_certificate.crt -issuer_hash -noout` - -However, in the Nginx configuration, obtaining the issuer hash is not possible without addons. Therefore, this header is manually entered as Hawkbit. You can enter 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. - -When deploying Nginx, you will need a `.yml` file. Here's an example `docker-compose.yml` file for Nginx Docker. + +4. To deploy Nginx, you could use a `.yml` file. Here's an example `docker-compose.yml` file for Nginx Docker. ```yml version: '3' @@ -191,7 +217,10 @@ services: ``` `/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. -#### Swupdate Suricatta Configurations +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. @@ -212,37 +241,24 @@ 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. -`journalctl --follow -u swupdate` - -#### Hawkbit Configurations - -There are also some configurations that you need update when you deployed your hawkbit service. - -You need to add the given download settings 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. Don't forget to replace "hostname" with your actual hostname. - -``` -hawkbit.artifact.url.protocols.download-http.rel=download-http -hawkbit.artifact.url.protocols.download-http.hostname=hawkbit.dev.example -hawkbit.artifact.url.protocols.download-http.protocol=https -hawkbit.artifact.url.protocols.download-http.supports=DMF,DDI -hawkbit.artifact.url.protocols.download-http.ref={protocol}://{hostnameRequest}/{tenant}/controller/v1/{controllerId}/softwaremodules/{softwareModuleId}/artifacts/{artifactFileName} +```shell +journalctl --follow -u swupdate ``` -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 issuer hash as "Hawkbit". This can be whetever you have configured in the nginx configuration in `proxy_set_header X-Ssl-Issuer-Hash-1` +  +##### Testing -![Example Reverse Proxy Settings](../../images/security/exampleReverseProxySettings.png) +You can test the communication by using the Curl command below to see if you successfully implemented mutual TLS: -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. - -#### Testing - -You can test the communication by using the Curl command below to see if you successfully implemented Mutual TLS: - -`curl -L -v --cert client.crt --key client.key --cacert server_ca.crt https://hawkbit.dev.example.com/default/controller/v1/{device-id}` +```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` +``` +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. diff --git a/docs/content/news/2023-09-21-epl2.0.md b/docs/content/news/2023-09-21-epl2.0.md new file mode 100644 index 000000000..8bd0f53c9 --- /dev/null +++ b/docs/content/news/2023-09-21-epl2.0.md @@ -0,0 +1,19 @@ +--- +title: Eclipse hawkBit upgrade to Eclipse Public License - v 2.0 +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. + +In this article, we want to give an overview of the latest highlights of hawkBit license changes. + +## hawkBit license upgraded to Eclipse Public License - v 2.0 + +Based on the issues +[Switch to EPL 2.0 License](https://github.com/eclipse/hawkbit/issues/1393) and +[Update hawkBit's license to EPL 2.0](https://github.com/eclipse/hawkbit/issues/1008) +the hawkBit license is upgraded from [Eclipse Public License - Version 1.0](http://www.eclipse.org/org/documents/epl-v10.php) to +[Eclipse Public License - v 2.0](https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt). + diff --git a/docs/install-theme.bat b/docs/install-theme.bat index aa700728a..ba95d44e9 100644 --- a/docs/install-theme.bat +++ b/docs/install-theme.bat @@ -28,4 +28,4 @@ if not exist %HUGO_THEMES%\ ( echo [INFO] echo [INFO] Launch the documentation locally by running 'mvn site' (or 'hugo server' in the docs directory), -echo [INFO] and browse to 'http://localhost:1313/hawkbit/'. \ No newline at end of file +echo [INFO] and browse to 'http://localhost:{port}/hawkbit/'. \ No newline at end of file diff --git a/docs/static/news/2018-07-26-first-release.html b/docs/static/news/2018-07-26-first-release.html deleted file mode 100644 index 097c508a7..000000000 --- a/docs/static/news/2018-07-26-first-release.html +++ /dev/null @@ -1,653 +0,0 @@ - - - - - - - - - - - - Eclipse hawkBit 0.2.0 - First Release - Eclipse hawkBit - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
-
- - - - - -
- -
- -
-
- - -
- -
-
-

Eclipse hawkBit 0.2.0 - First Release

- - - -

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. The release can be found on Maven Central -and Docker Hub. 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

- -

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

- -

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 -for some time, which we were happy to meet. The documentation is generated using Spring REST docs, based on unit-tests. These tests, with the respective documentation, are now available in the code base. - Furthermore, the API documentation will be hosted on our new website (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 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 -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: This requires a running Docker deamon on your system.

-
- -

Now, browse to 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, project lead from the first hour, -Jeroen Laverman joined the lead to support him in this responsibility. -Moreover, with Stefan Behl 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 -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.

- - - - - - -
-
- -
-
-
-
-
-
-
-
-
- - - - - - - - - - - - -