Part 1
요약·해설
Freedom-K64F를 기준으로 hawkBit server, signed image, Software Module·Distribution·Deployment와 TLS client 설정을 단계별로 다룹니다.
HTTP DDI · Polling/Manual
MCUboot signed images
Module → Distribution → Target
HTTP 8080 · HTTPS 8443
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
5A63A52FA7F2743C168513CB2681F81E9CCADAE806D212A1AEA32EA4A1E633B7
.. zephyr:code-sample:: hawkbit-api
:name: Eclipse hawkBit Direct Device Integration API
:relevant-api: hawkbit
Update a device using Eclipse hawkBit DDI API.
Overview
********
The Eclipse hawkBit update server provides REST resources which are consumed by the
device to retrieve software update tasks. This API is based on HTTP standards
and a polling mechanism.
This sample shows how to use hawkBit DDI API in both a polling and manual
update mode.
Polling mode run automatically on a predefined period, probing the server
for updates and installing them without requiring user intervention. You can
access the sample source code for this hawkbit_polling.
Manual mode requires the user to call the server probe and then, if there is
an available update, it will install the update. You can access the sample
source code for this mode hawkbit_manual
Caveats
*******
* The Zephyr port of hawkBit is configured to run on a
:ref:`Freedom-K64F <frdm_k64f>` MCU by default. The application should
build and run for other platforms with support internet connection. Some
platforms need some modification. Overlay files would be needed to support
BLE 6lowpan, 802.15.4 or OpenThread configurations as well as the
understanding that most other connectivity options would require an edge
gateway of some sort (Border Router, etc).
* The MCUboot bootloader is required for hawkBit to function properly.
More information about the Device Firmware Upgrade subsystem and MCUboot
can be found in :ref:`mcuboot`.
Building and Running
********************
The below steps describe how to build and run the hawkBit sample in
Zephyr. Where examples are given, it is assumed the sample is being build for
the Freedom-K64F Development Kit (``BOARD=frdm_k64f``).
Step 1: Build MCUboot
=====================
Build MCUboot by following the instructions in the :ref:`mcuboot` documentation
page.
Step 2: Flash MCUboot
=====================
Flash the resulting image file to the 0x0 address of the flash memory. This can
be done by,
.. code-block:: console
west flash
Step 3: Start the hawkBit Docker
================================
By default, the hawkbit application is set to run on http at port:8080.
.. code-block:: console
sudo docker run -p 8080:8080 hawkbit/hawkbit-update-server:latest \
--hawkbit.dmf.rabbitmq.enabled=false \
--hawkbit.server.ddi.security.authentication.anonymous.enabled=true
This will start the hawkbit server on the host system.Opening your browser to
the server URL, ``<your-ip-address>:8080``, and logging into the server using
``admin`` as the login and password by default.
Step 4: Build hawkBit
=====================
hawkBit can be built for the :ref:`Freedom-K64F <frdm_k64f>` as follows:
.. zephyr-app-commands::
:zephyr-app: samples/subsys/mgmt/hawkbit
:board: frdm_k64f
:conf: "prj.conf"
:goals: build
If you want to build it with the ability to set the hawkBit server address
and port during runtime, you can use the following command:
.. zephyr-app-commands::
:zephyr-app: samples/subsys/mgmt/hawkbit
:board: frdm_k64f
:conf: "prj.conf overlay-runtime.conf"
:goals: build
.. _hawkbit_sample_sign:
The firmware will be signed automatically by the build system with the
``root-rsa-2048.pem`` key. The key is located in the MCUboot repository.
Step 5: Flash the first image
=============================
Upload the :file:`zephyr.signed.confirmed.bin` file to image slot-0
of your board.
.. code-block:: console
west flash --bin-file build/zephyr/zephyr.signed.confirmed.bin
Once the image is flashed and booted, the sample will print the image build
time to the console. After it connects to the internet, in hawkbit server UI,
you should see the ``frdm_k64f`` show up in the Targets pane. It's time to
upload a firmware binary to the server, and update it using this UI.
Step 6: Building and signing the test image
===========================================
The easiest way to test the functionality of hawkBit is to repeat step 4 to
build the sample again, so that the build time will be different.
This time you need the file :file:`zephyr.signed.bin` from the build directory.
Upload the signed image to the server. Click Upload icon in left pane of UI and
create a new Software Module with type Apps (``name:hawkbit,version:1.0.1``).
Then upload the signed image to the server with Upload file Icon.
Click on distribution icon in the left pane of UI and create a new Distribution
with type Apps only (``name:frdm_k64f_update,version:1.0.1``). Assign the
hawkBit software module to the created distribution. Click on Deployment
icon in the left pane of UI and assign the ``frdm_k64f_update`` distribution to
the target ``frdm_k64f``.
Step 7: Run the update
======================
Back in the terminal session that you used for debugging the board, type the
following command:
.. code-block:: console
hawkbit run
And then wait. The board will ping the server, check if there are any new
updates, and then download the update you've just created. If everything goes
fine the message ``Update installed`` will be printed on the terminal.
Your board will reboot automatically and then start with the new image. After rebooting, the
board will print a different image build time then automatically ping the server
again and the message ``Image is already updated`` will be printed on the terminal.
Step 8: Clone and build hawkbit with https
==========================================
Below steps clone and build the hawkbit with self-signed certificate
to support https.
.. code-block:: console
git clone https://github.com/eclipse/hawkbit.git
cd hawkbit/hawkbit-runtime/hawkbit-update-server/src/main/resources
* Generate the private key
.. code-block:: console
openssl genrsa -des3 -out server.key 2048
* Generate the CSR
.. code-block:: console
openssl req -new -key server.key -out server.csr
Once you run the command, it will prompt you to enter your Country,
State, City, Company name and enter the Command Name field with
``<your-ip-address>``.
* Generate the self-signed x509 certificate suitable to use on web server.
.. code-block:: console
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
* Generate pem file from generated server.key and server.crt
.. code-block:: console
cat server.key > server.pem
cat server.crt >> server.pem
* Generate .pkcs12 file
.. code-block:: console
openssl pkcs12 -export -in server.pem -out keystore.pkcs12
* Following command imports a .p12 into pkcs12 Java keystore
.. code-block:: console
keytool -importkeystore -srckeystore keystore.pkcs12 -srcstoretype pkcs12 \
-destkeystore hb-pass.jks -deststoretype pkcs12 \
-alias 1 -deststorepass <password_of_p12>
* Edit the hawkbit application.properties file
.. code-block:: console
vi application.properties
Change authentication security from false to true.
.. code-block:: console
hawkbit.server.ddi.security.authentication.anonymous.enabled=true
* Enter the https details at last
.. code-block:: console
server.hostname=localhost
server.port=8443
hawkbit.artifact.url.protocols.download-http.protocol=https
hawkbit.artifact.url.protocols.download-http.port=8443
security.require-ssl=true
server.use-forward-headers=true
server.ssl.key-store= <hb-pass.jks file location>
server.ssl.key-store-type=JKS
server.ssl.key-password= <password_of_key>
server.ssl.key-store-password= <password_of_key_store>
server.ssl.protocol=TLS
server.ssl.enabled-protocols=TLSv1.2
server.ssl.ciphers=TLS_RSA_WITH_AES_256_CBC_SHA256,
TLS_RSA_WITH_AES_256_CBC_SHA
* Start Compile
.. code-block:: console
cd ~/hawkbit
mvn clean install -DskipTests=true
* Once the build is successful, run hawkbit
.. code-block:: console
java -jar ./hawkbit-runtime/hawkbit-update-server/target/ \
hawkbit-update-server-#version#-SNAPSHOT.jar
Step 9: Build hawkBit HTTPS
===========================
* Convert the server.pem file to self_sign.der and place the der file in
hawkbit/src directory
``hawkBit https`` can be built for the :ref:`Freedom-K64F <frdm_k64f>` as follows:
.. zephyr-app-commands::
:zephyr-app: samples/subsys/mgmt/hawkbit
:board: frdm_k64f
:conf: "prj.conf overlay-tls.conf"
:goals: build
Repeat the steps from 5 to 7, to update the device over https.
Part 3
한국어 전문 번역
개요
Eclipse hawkBit update server는 device가 software update task를 가져갈 수 있도록 REST resource를 제공합니다. 이 Direct Device Integration(DDI) API는 HTTP 표준과 polling mechanism을 기반으로 합니다.
이 sample은 hawkBit DDI API를 polling mode와 manual update mode 두 방식으로 사용하는 방법을 보여 줍니다.
Polling mode는 미리 정한 주기마다 자동으로 실행되어 server에 update가 있는지 질의하고, 사용자 개입 없이 설치합니다. 이 동작은 sample의 hawkbit_polling source에서 확인할 수 있습니다.
Manual mode에서는 사용자가 server probe를 직접 호출해야 합니다. 사용 가능한 update가 있으면 이어서 설치하며, 해당 흐름은 hawkbit_manual source에서 확인할 수 있습니다.
주의 사항
- Zephyr의 hawkBit port는 기본적으로 Freedom-K64F(
frdm_k64f) MCU에서 실행하도록 설정되어 있습니다. Internet connection을 지원하는 다른 platform에서도 build하고 실행할 수 있지만 일부 platform은 수정이 필요합니다. BLE 6LoWPAN, IEEE 802.15.4 또는 OpenThread 구성에는 overlay file이 필요하며, 그 밖의 여러 연결 방식에는 Border Router 같은 edge gateway가 필요할 수 있습니다. - hawkBit가 올바르게 동작하려면 MCUboot bootloader가 필요합니다. Image slot 전환과 검증을 담당하는 Device Firmware Upgrade subsystem 및 MCUboot 절차를 먼저 준비해야 합니다.
빌드 및 실행
다음 단계는 Zephyr에서 hawkBit sample을 build하고 실행하는 전체 절차입니다. 별도 표기가 없는 example은 Freedom-K64F Development Kit, 즉 BOARD=frdm_k64f를 대상으로 합니다.
1단계: MCUboot 빌드
MCUboot 공식 문서의 지침에 따라 bootloader를 build합니다. Application image와 같은 signing key 및 partition layout을 사용하도록 MCUboot와 Zephyr build 설정을 맞춰야 합니다.
2단계: MCUboot 플래시
생성된 MCUboot image를 flash memory의 0x0 address에 씁니다.
west flash
3단계: hawkBit Docker 시작
기본 hawkBit application은 HTTP port 8080에서 실행됩니다. RabbitMQ 기반 DMF를 끄고 DDI anonymous authentication을 허용한 update server container를 시작합니다.
sudo docker run -p 8080:8080 hawkbit/hawkbit-update-server:latest \
--hawkbit.dmf.rabbitmq.enabled=false \
--hawkbit.server.ddi.security.authentication.anonymous.enabled=true
이 command는 host system에서 hawkBit server를 시작합니다. Browser에서 <your-ip-address>:8080을 열고 기본 계정의 login과 password에 각각 admin을 입력합니다. 이 기본 credential 및 anonymous mode는 시험 환경용이며 production 배포에는 그대로 사용하면 안 됩니다.
4단계: hawkBit 빌드
Freedom-K64F용 기본 sample은 prj.conf로 build합니다.
# From the root of the zephyr repository
west build -b frdm_k64f samples/subsys/mgmt/hawkbit -- -DCONF_FILE="prj.conf"
실행 중 hawkBit server address와 port를 설정할 수 있게 하려면 overlay-runtime.conf를 함께 사용합니다.
# From the root of the zephyr repository
west build -b frdm_k64f samples/subsys/mgmt/hawkbit -- -DCONF_FILE="prj.conf overlay-runtime.conf"
Firmware는 build system이 MCUboot repository의 root-rsa-2048.pem key를 사용해 자동으로 서명합니다. MCUboot가 신뢰하는 public key와 이 signing key가 서로 대응해야 image 검증이 성공합니다.
5단계: 첫 번째 이미지 플래시
zephyr.signed.confirmed.bin file을 board의 image slot 0에 올립니다. Confirmed image를 첫 boot 기준 image로 사용하므로 MCUboot rollback 대상으로 취급되지 않습니다.
west flash --bin-file build/zephyr/zephyr.signed.confirmed.bin
Image가 flash되고 boot되면 sample은 console에 image build time을 출력합니다. Internet에 연결된 뒤 hawkBit server UI의 Targets pane에 frdm_k64f가 나타나는지 확인합니다. 이제 server에 새 firmware binary를 올리고 UI에서 update를 지정할 준비가 된 것입니다.
6단계: 테스트 이미지 빌드 및 서명
기능을 가장 간단히 시험하려면 4단계를 반복해 sample을 다시 build합니다. Build time이 달라져 첫 image와 구분되는 새 image가 만들어집니다. 이번에는 build directory의 zephyr.signed.bin을 사용합니다.
Server UI 왼쪽의 Upload icon을 선택하고 Apps type의 새 Software Module을 만듭니다. Example 값은 name: hawkbit, version: 1.0.1입니다. 이어 Upload file icon으로 signed image를 이 module에 올립니다.
왼쪽의 Distribution icon에서 Apps-only Distribution을 만듭니다. Example 값은 name: frdm_k64f_update, version: 1.0.1입니다. 앞서 만든 Software Module을 Distribution에 할당한 다음 Deployment icon을 선택해 frdm_k64f_update Distribution을 frdm_k64f target에 배정합니다.
7단계: 업데이트 실행
Board를 debug하던 terminal session에서 manual update probe를 시작합니다.
hawkbit run
Board는 server에 ping하고 새 update를 확인한 뒤 방금 만든 image를 download합니다. 정상적으로 설치되면 terminal에 Update installed가 출력됩니다.
Board는 자동으로 reboot하고 새 image로 시작합니다. 다른 image build time을 출력한 뒤 server를 다시 자동 질의하며, 더 새로운 update가 없으면 Image is already updated가 출력됩니다.
8단계: HTTPS를 사용하는 hawkBit 복제 및 빌드
다음 절차는 self-signed certificate를 사용하는 HTTPS hawkBit server를 source에서 build합니다. 먼저 Eclipse hawkBit repository를 clone하고 server resource directory로 이동합니다.
git clone https://github.com/eclipse/hawkbit.git
cd hawkbit/hawkbit-runtime/hawkbit-update-server/src/main/resources
2048-bit private key를 생성합니다. -des3로 보호된 key의 passphrase를 이후 command에서도 사용할 수 있어야 합니다.
openssl genrsa -des3 -out server.key 2048
Private key로 Certificate Signing Request(CSR)를 생성합니다.
openssl req -new -key server.key -out server.csr
Command가 Country, State, City, Company name 등을 물으면 값을 입력하고 Common Name field에는 <your-ip-address>를 입력합니다. Client가 접속하는 host와 certificate identity가 맞아야 합니다.
Web server에서 사용할 수 있도록 CSR에 직접 서명해 365일 유효한 self-signed X.509 certificate를 만듭니다.
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
생성한 private key와 certificate를 하나의 PEM file로 결합합니다.
cat server.key > server.pem
cat server.crt >> server.pem
PEM material을 PKCS#12 container로 export합니다.
openssl pkcs12 -export -in server.pem -out keystore.pkcs12
PKCS#12 file을 Java keystore hb-pass.jks로 import합니다. <password_of_p12>에는 앞 단계에서 정한 PKCS#12 password를 사용합니다.
keytool -importkeystore -srckeystore keystore.pkcs12 -srcstoretype pkcs12 \
-destkeystore hb-pass.jks -deststoretype pkcs12 \
-alias 1 -deststorepass <password_of_p12>
hawkBit의 application.properties를 편집합니다.
vi application.properties
문서의 지시에 따라 anonymous DDI authentication setting을 true로 설정합니다.
hawkbit.server.ddi.security.authentication.anonymous.enabled=true
마지막에 HTTPS server와 artifact download, keystore, TLS protocol 및 cipher 정보를 추가합니다. Placeholder path와 password는 실제 생성한 keystore 값으로 바꿉니다.
server.hostname=localhost
server.port=8443
hawkbit.artifact.url.protocols.download-http.protocol=https
hawkbit.artifact.url.protocols.download-http.port=8443
security.require-ssl=true
server.use-forward-headers=true
server.ssl.key-store= <hb-pass.jks file location>
server.ssl.key-store-type=JKS
server.ssl.key-password= <password_of_key>
server.ssl.key-store-password= <password_of_key_store>
server.ssl.protocol=TLS
server.ssl.enabled-protocols=TLSv1.2
server.ssl.ciphers=TLS_RSA_WITH_AES_256_CBC_SHA256,
TLS_RSA_WITH_AES_256_CBC_SHA
hawkBit repository root로 돌아가 test를 생략한 Maven build를 실행합니다.
cd ~/hawkbit
mvn clean install -DskipTests=true
Build가 성공하면 생성된 update-server JAR를 실행합니다. #version#은 실제 build artifact version으로 바꿉니다.
java -jar ./hawkbit-runtime/hawkbit-update-server/target/ \
hawkbit-update-server-#version#-SNAPSHOT.jar
Self-signed certificate는 개발·시험용입니다. 실제 환경에서는 신뢰할 수 있는 CA certificate, hostname 검증, 강한 credential과 현재 보안 정책에 맞는 TLS suite를 사용해야 합니다.
9단계: hawkBit HTTPS 클라이언트 빌드
server.pem을 DER 형식의 self_sign.der로 변환하고 Zephyr sample의 hawkbit/src directory에 둡니다. Device가 server certificate를 검증할 때 이 trust material을 사용합니다.
Freedom-K64F용 HTTPS client는 overlay-tls.conf를 더해 build합니다.
# From the root of the zephyr repository
west build -b frdm_k64f samples/subsys/mgmt/hawkbit -- -DCONF_FILE="prj.conf overlay-tls.conf"
그다음 5단계부터 7단계를 반복해 첫 image 준비, server 배포 지정, device update를 HTTPS로 수행합니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.