1=== Notes on using Mender on Buildroot 2====================================== 3 4Mender is an open source over-the-air (OTA) software updater for 5embedded Linux devices. Mender comprises a client running at the 6embedded device, as well as a server that manages deployments across 7many devices. There is also various tooling around the Mender project, 8such as 'mender-artifact' which is used to create Mender Artifacts 9that are compatible with the Mender client and server. 10 11Mender aims to address this challenge with a robust and easy to use 12updater for embedded Linux devices, which is open source and available 13to anyone. 14 15Robustness is ensured with atomic image-based deployments using a dual 16A/B rootfs partition layout. This makes it always possible to roll 17back to a working state, even when losing power at any time during the 18update process. 19 20The official documentation is a good resource to get an in depth 21understanding of how Mender works: 22 23 https://docs.mender.io 24 25In Buildroot the following packages are provided: 26 27- BR2_PACKAGE_MENDER 28 - This will install the client on target rootfs 29- BR2_PACKAGE_HOST_MENDER_ARTIFACT 30 - This will install the 'mender-artifact' tool in host rootfs. 31 32To fully utilize atomic image-based deployments using the A/B update 33strategy, additional integration is required in the bootloader. This 34integration is board specific. 35 36Currently supported bootloaders are GRUB and U-boot, and for reference 37integrations please visit: 38 39 https://github.com/mendersoftware/buildroot-mender 40 41Default configurations files 42---------------------------- 43 44Buildroot comes with a default configuration and there a couple of 45files that need your attention: 46 47- /etc/mender/mender.conf 48 - main configuration file for the Mender client 49 - https://docs.mender.io/client-configuration/configuration-file/configuration-options 50 51- /etc/mender/artifact_info 52 - The name of the image or update that will be built. This is what the 53 device will report that it is running, and different updates must have 54 different names 55 56- /var/lib/mender/device_type 57 - A string that defines the type of device 58 59Mender server configuration 60--------------------------- 61 62The Mender server can be setup in different ways, and how you 63configure the Mender client differs slightly depending on which server 64environment is used. 65 66- Mender demo environment 67 68This is if you have followed the Getting started documentation where 69you launch a Mender server locally and to configure your environment 70to connect to this local server you need to provide the IP address of 71the server on the local network. 72 73By default the demo environment will connect to 'docker.mender.io' and 74's3.docker.mender.io' and we need to make sure that these are resolved 75to the local IP address of the running server by adding the following 76entry to '/etc/hosts' 77 78 <ip address of demo environment> docker.mender.io s3.docker.mender.io 79 80This is required because the communication between client and server 81is utilizing TLS and the provided demo server certificate (server.crt) 82is only valid for 'docker.mender.io' and 's3.docker.mender.io' 83domains. 84 85- Hosted Mender 86 87To authenticate the Mender client with the Hosted Mender server you 88need a tenant token. 89 90To get your tenant token: 91 92- log in to https://hosted.mender.io 93- click your email at the top right and then “My organization” 94- press the “COPY TO CLIPBOARD” 95- assign content of clipboard to TenantToken 96 97Example mender.conf options for Hosted Mender: 98 99 { 100 ... 101 "ServerURL": "https://hosted.mender.io", 102 "TenantToken": "<paste tenant token here>" 103 ... 104 } 105 106 107Creating Mender Artifacts 108------------------------- 109 110To create Mender Artifacts based on Buildroot build output you must 111include BR2_PACKAGE_HOST_MENDER_ARTIFACT in your configuration, and 112then you would typically create the Mender Artifact in a post image 113script (BR2_ROOTFS_POST_IMAGE_SCRIPT). Below is an example of such a 114script: 115 116 #!/bin/sh 117 118 set -e 119 set -x 120 121 device_type=$(cat ${TARGET_DIR}/var/lib/mender/device_type | sed 's/[^=]*=//') 122 artifact_name=$(cat ${TARGET_DIR}/etc/mender/artifact_info | sed 's/[^=]*=//') 123 124 if [ -z "${device_type}" ] || [ -z "${artifact_name}" ]; then 125 echo "missing files required by Mender" 126 exit 1 127 fi 128 129 ${HOST_DIR}/usr/bin/mender-artifact write rootfs-image \ 130 --update ${BINARIES_DIR}/rootfs.ext4 \ 131 --output-path ${BINARIES_DIR}/${artifact_name}.mender \ 132 --artifact-name ${artifact_name} \ 133 --device-type ${device_type} 134 135As you can see some properties are extracted from target rootfs, and 136this is because these values are used for compatibility checks, 137meaning that the information must be present in both rootfs and in 138Mender Artifact meta data. 139 140- device_type - must be an exact match between rootfs and Mender 141 Artifact meta-data to apply update. You can set an 142 array of devices here as well, e.g if your image is 143 compatible with multiple hardware revisions 144 145- artifact_name - must be an exact match between rootfs and Mender 146 Artifact meta-data to apply update. 147 148Configuring Mender with certificates 149------------------------------------ 150 151Mender uses TLS to communicate with the management server, and if you 152use a CA-signed certificate on the server, you must include 153BR2_PACKAGE_CA_CERTIFICATES in your configuration to authenticate TLS 154connections. 155