123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154 |
- === Notes on using Mender on Buildroot
- ======================================
- Mender is an open source over-the-air (OTA) software updater for
- embedded Linux devices. Mender comprises a client running at the
- embedded device, as well as a server that manages deployments across
- many devices. There is also various tooling around the Mender project,
- such as 'mender-artifact' which is used to create Mender Artifacts
- that are compatible with the Mender client and server.
- Mender aims to address this challenge with a robust and easy to use
- updater for embedded Linux devices, which is open source and available
- to anyone.
- Robustness is ensured with atomic image-based deployments using a dual
- A/B rootfs partition layout. This makes it always possible to roll
- back to a working state, even when losing power at any time during the
- update process.
- The official documentation is a good resource to get an in depth
- understanding of how Mender works:
- https://docs.mender.io
- In Buildroot the following packages are provided:
- - BR2_PACKAGE_MENDER
- - This will install the client on target rootfs
- - BR2_PACKAGE_HOST_MENDER_ARTIFACT
- - This will install the 'mender-artifact' tool in host rootfs.
- To fully utilize atomic image-based deployments using the A/B update
- strategy, additional integration is required in the bootloader. This
- integration is board specific.
- Currently supported bootloaders are GRUB and U-boot, and for reference
- integrations please visit:
- https://github.com/mendersoftware/buildroot-mender
- Default configurations files
- ----------------------------
- Buildroot comes with a default configuration and there a couple of
- files that need your attention:
- - /etc/mender/mender.conf
- - main configuration file for the Mender client
- - https://docs.mender.io/client-configuration/configuration-file/configuration-options
- - /etc/mender/artifact_info
- - The name of the image or update that will be built. This is what the
- device will report that it is running, and different updates must have
- different names
- - /var/lib/mender/device_type
- - A string that defines the type of device
- Mender server configuration
- ---------------------------
- The Mender server can be setup in different ways, and how you
- configure the Mender client differs slightly depending on which server
- environment is used.
- - Mender demo environment
- This is if you have followed the Getting started documentation where
- you launch a Mender server locally and to configure your environment
- to connect to this local server you need to provide the IP address of
- the server on the local network.
- By default the demo environment will connect to 'docker.mender.io' and
- 's3.docker.mender.io' and we need to make sure that these are resolved
- to the local IP address of the running server by adding the following
- entry to '/etc/hosts'
- <ip address of demo environment> docker.mender.io s3.docker.mender.io
- This is required because the communication between client and server
- is utilizing TLS and the provided demo server certificate (server.crt)
- is only valid for 'docker.mender.io' and 's3.docker.mender.io'
- domains.
- - Hosted Mender
- To authenticate the Mender client with the Hosted Mender server you
- need a tenant token.
- To get your tenant token:
- - log in to https://hosted.mender.io
- - click your email at the top right and then “My organization”
- - press the “COPY TO CLIPBOARD”
- - assign content of clipboard to TenantToken
- Example mender.conf options for Hosted Mender:
- {
- ...
- "ServerURL": "https://hosted.mender.io",
- "TenantToken": "<paste tenant token here>"
- ...
- }
- Creating Mender Artifacts
- -------------------------
- To create Mender Artifacts based on Buildroot build output you must
- include BR2_PACKAGE_HOST_MENDER_ARTIFACT in your configuration, and
- then you would typically create the Mender Artifact in a post image
- script (BR2_ROOTFS_POST_IMAGE_SCRIPT). Below is an example of such a
- script:
- #!/bin/sh
- set -e
- set -x
- device_type=$(cat ${TARGET_DIR}/var/lib/mender/device_type | sed 's/[^=]*=//')
- artifact_name=$(cat ${TARGET_DIR}/etc/mender/artifact_info | sed 's/[^=]*=//')
- if [ -z "${device_type}" ] || [ -z "${artifact_name}" ]; then
- echo "missing files required by Mender"
- exit 1
- fi
- ${HOST_DIR}/usr/bin/mender-artifact write rootfs-image \
- --update ${BINARIES_DIR}/rootfs.ext4 \
- --output-path ${BINARIES_DIR}/${artifact_name}.mender \
- --artifact-name ${artifact_name} \
- --device-type ${device_type}
- As you can see some properties are extracted from target rootfs, and
- this is because these values are used for compatibility checks,
- meaning that the information must be present in both rootfs and in
- Mender Artifact meta data.
- - device_type - must be an exact match between rootfs and Mender
- Artifact meta-data to apply update. You can set an
- array of devices here as well, e.g if your image is
- compatible with multiple hardware revisions
- - artifact_name - must be an exact match between rootfs and Mender
- Artifact meta-data to apply update.
- Configuring Mender with certificates
- ------------------------------------
- Mender uses TLS to communicate with the management server, and if you
- use a CA-signed certificate on the server, you must include
- BR2_PACKAGE_CA_CERTIFICATES in your configuration to authenticate TLS
- connections.
|