readme.txt 5.3 KB

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