[Buildroot] [PATCH 1/1] package/mender: update readme.txt

[Buildroot] [PATCH 1/1] package/mender: update readme.txt

[Mirza Krak]

Provide additional details on how Mender works within Buildroot.

Signed-off-by: Mirza Krak <mirza.krak@northern.tech>
---
 package/mender/readme.txt | 147 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 139 insertions(+), 8 deletions(-)

diff --git a/package/mender/readme.txt b/package/mender/readme.txt
index 329b2a42f2..1afc7b6268 100644
--- a/package/mender/readme.txt
+++ b/package/mender/readme.txt
@@ -3,16 +3,147 @@
 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.
+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.
 
-The simplest way to do it is to change these files in an overlay or in a post
-build script.
+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.
 
-Configuring mender with certificates
+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 should select the ca-certificates
-package otherwise it doesn't work.
+CA-signed certificate on the server, you must include
+BR2_PACKAGE_CA_CERTIFICATES in your configuration to authenticate TLS
+connections.
-- 
2.11.0

[Buildroot] [PATCH 1/1] package/mender: update readme.txt

[Thomas Petazzoni]

Hello,

Thanks for this patch.

On Fri, 31 May 2019 14:32:05 +0200
Mirza Krak <mirza.krak@northern.tech> wrote:

> Provide additional details on how Mender works within Buildroot.
> 
> Signed-off-by: Mirza Krak <mirza.krak@northern.tech>
> ---
>  package/mender/readme.txt | 147 +++++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 139 insertions(+), 8 deletions(-)
> 
> diff --git a/package/mender/readme.txt b/package/mender/readme.txt
> index 329b2a42f2..1afc7b6268 100644
> --- a/package/mender/readme.txt
> +++ b/package/mender/readme.txt
> @@ -3,16 +3,147 @@
>  Default configurations files
>  ----------------------------

This title was now duplicated, so I dropped this first one, since the
text below is an introduction to Mender, and you repeat the "Default
configuration files" later on.

I've also rewrapped the text, and then applied to master.

Thanks,

Thomas
-- 
Thomas Petazzoni, CTO, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

[Buildroot] [PATCH 1/1] package/mender: update readme.txt

[Peter Korsgaard]

>>>>> "Mirza" == Mirza Krak <mirza.krak@northern.tech> writes:

 > Provide additional details on how Mender works within Buildroot.
 > Signed-off-by: Mirza Krak <mirza.krak@northern.tech>

Committed to 2019.02.x, thanks.

-- 
Bye, Peter Korsgaard