package/mender: update readme.txt
Provide additional details on how Mender works within Buildroot.
Signed-off-by: Mirza Krak <mirza.krak@northern.tech>
[Thomas: remove duplicate "Default configuration files" title, rewrap
text]
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
(cherry picked from commit a10d911788)
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
This commit is contained in:
Mirza Krak
Peter Korsgaard
parent
b6669b433d
commit
601d2b356d
@ -1,18 +1,154 @@
|
||||
=== 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 artifact_info and device_type configuration files
|
||||
in /etc/mender. They contain default values, and thus they should be overridden
|
||||
on a production system.
|
||||
Buildroot comes with a default configuration and there a couple of
|
||||
files that need your attention:
|
||||
|
||||
The simplest way to do it is to change these files in an overlay or in a post
|
||||
build script.
|
||||
- /etc/mender/mender.conf
|
||||
- main configuration file for the Mender client
|
||||
- https://docs.mender.io/client-configuration/configuration-file/configuration-options
|
||||
|
||||
Configuring mender with certificates
|
||||
- /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 should select the ca-certificates
|
||||
package otherwise it doesn't work.
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user