Customize Mender

tutorial

Pre-release versions

If you want to use pre-release versions of the Mender components, please have a look at the PREFERRED_VERSION variables in the local.conf example.

Configuring server address and port

If the client should connect to a different address than the default of https://docker.mender.io/, then you should specify this variable in your local.conf:

MENDER_SERVER_URL = "https://mender.example.com"

Port numbers can be specified in the same way as you would in a browser, as a colon after the address followed by the number, for example https://mender.example.com:8999.

Note that the https protocol specifier is required in the address. For security reasons, Mender does not support the plaintext http protocol.

Configuring polling intervals

You can configure how frequently the Mender Client will make requests to the Mender Server as described in Polling intervals before starting the build process.

In order to do this, add the following in your local.conf:

MENDER_UPDATE_POLL_INTERVAL_SECONDS = "1800"
MENDER_INVENTORY_POLL_INTERVAL_SECONDS = "28800"

Configuration file

It is possible to put your own mender.conf configuration file in the image. The file will be merged with settings from Yocto variables. To use your own file, use a mender_%.bbappend file in your own layer, add a mender.conf file to the layer, and list this file in the SRC_URI of the mender recipe, like this:

FILESEXTRAPATHS:prepend := "${THISDIR}/<DIRECTORY-WITH-MENDER-CONF>:"
SRC_URI:append = " file://mender.conf"

Replace <DIRECTORY-WITH-MENDER-CONF> with the path to the mender.conf file, relative to the recipe file.

Prior to Mender Client version 4.0.0, the recipe was called mender-client. Please modify mender-client_%.bbappend instead of mender_%.bbappend if you are using such a version. This applies to the sections below as well.

Note that variables take precedence over entries in the mender.conf file, so if there are any conflicts, you should either set the affected variables to the empty string, or remove the entry from your mender.conf file. The message will normally look like this:

Configuration key 'ServerURL', found in mender.conf, conflicts with MENDER_SERVER_URL. Choosing the latter.

Disabling Mender as a system service

If you do not want Mender to run as a system service, and you prefer to carry out update steps manually using the command line client interface, you can disable the service that starts Mender at boot.

This is simple to accomplish by adding a recipes-mender/mender/mender_%.bbappend file in your Yocto Project layer, with the following content:

SYSTEMD_AUTO_ENABLE = "disable"

In this case it is also possible to avoid Mender's current dependency on systemd. If you do not wish to enable systemd in your build, add the following to local.conf:

MENDER_FEATURES_DISABLE:append = " mender-systemd"

Also, you do not need any daemon-related configuration items in your local.conf as outlined in the section on configuring the Yocto Project build.

If you disable Mender running as a daemon under systemd, you must run all required Mender commands from the CLI or scripts. Most notably, you need to run mender-update commit after booting into and verifying a successful deployment. When running in managed mode, any pending mender-update commit will automatically run by the Mender daemon after it starts. See Modes of operation for more information about the difference.

Identity

In order to include an identity script, simply augment the mender recipe and install the script in the expected folder. For example, create a mender_%.bbappend file in your layer, and add this:

FILESEXTRAPATHS:prepend := "${THISDIR}/<DIRECTORY-WITH-IDENTITY-SCRIPT>:"
SRC_URI:append = " file://mender-device-identity"

do_install:append() {
    install -d ${D}/${datadir}/mender/identity
    install -m 755 ${WORKDIR}/mender-device-identity ${D}/${datadir}/mender/identity/mender-device-identity
}

Replace <DIRECTORY-WITH-IDENTITY-SCRIPT> with the path to the mender-device-identity file, relative to the recipe file.

Inventory

Mender comes with some inventory scripts available out of the box. These are:

  • mender-inventory-bootloader-integration
  • mender-inventory-geo
  • mender-inventory-hostinfo
  • mender-inventory-network
  • mender-inventory-os
  • mender-inventory-provides
  • mender-inventory-rootfs-type
  • mender-inventory-update-modules

In order to include an inventory script of your own making, augment the mender recipe and install the script in the expected folder. For example, create a mender_%.bbappend file in your layer, and add this:

FILESEXTRAPATHS:prepend := "${THISDIR}/<DIRECTORY-WITH-INVENTORY-SCRIPT>:"
SRC_URI:append = " file://mender-inventory-custom-attribute"

do_install:append() {
    install -d ${D}/${datadir}/mender/inventory
    install -m 755 ${WORKDIR}/mender-inventory-custom-attribute ${D}/${datadir}/mender/inventory/mender-inventory-custom-attribute
}

Replace <DIRECTORY-WITH-INVENTORY-SCRIPT> with the path to the mender-inventory-custom-attribute file, relative to the recipe file. The string custom-attribute can be replaced with a string of your choice, as long as the filename starts with mender-inventory-.

Remove the mender-inventory-geolocation script

By default the mender recipe installs with the mender-inventory-geo script enabled. To some users this is undesireable, as the script relies on a third party service for geolocating the device through its IP address. If this is applicable to you, then disable the script through setting:

PACKAGECONFIG:remove:pn-mender = " inventory-network-scripts"

in your local.conf file.

Update Modules

Mender comes with some standard Update Modules ready to be used, and it's also possible to install your own custom Update Modules with Yocto.

Standard Update Modules

The standard Update Module are

  • rootfs-image
  • directory
  • single-file

These Update Modules are installed by default. To remove the standard Update Modules, you need to remove the modules entry to the PACKAGECONFIG of the mender recipe. This can be done either by adding your own .bbappend recipe file, or by adding it to local.conf. To add it to a recipe file, create mender_%.bbappend and add this:

PACKAGECONFIG:remove = " modules"

Alternatively, add this to local.conf:

PACKAGECONFIG:remove:pn-mender = " modules"

Custom Update Modules

In order to include your own custom Update Module, simply augment the mender recipe and install the Update Module in the expected folder. For example, create a mender_%.bbappend file in your layer, and add this:

FILESEXTRAPATHS:prepend := "${THISDIR}/<DIRECTORY-WITH-UPDATE-MODULE>:"
SRC_URI:append = " file://custom-update-module"

do_install:append() {
    install -d ${D}/${datadir}/mender/modules/v3
    install -m 755 ${WORKDIR}/custom-update-module ${D}/${datadir}/mender/modules/v3/custom-update-module
}

Replace <DIRECTORY-WITH-UPDATE-MODULE> with the path to the custom-update-module file, relative to the recipe file. The name, "custom-update-module", can be any string, and must have the same name as the payload type used for Artifacts installed with this Update Module. See Create a custom update module for more information.

Delta update support

Delta update support is covered in its own sub section.

Add-ons

Mender Connect

We do not enable Mender Connect by default, unless you are building with the demo layer. To enable Mender Connect you can add it either via your own .bbappend recipe file, or via your local.conf file.

To add it to a recipe file, create mender_%.bbappend and add this:

IMAGE_INSTALL:append = " mender-connect"

Alternatively, add the snippet to your local.conf.

Mender Connect provides several configuration options. Set MENDER_CONNECT_USER and MENDER_CONNECT_SHELL via your local.conf file for meta-mender to generate a mender-connect.conf with User and ShellCommand fields:

MENDER_CONNECT_USER = "root"
MENDER_CONNECT_SHELL = "/bin/bash"

To add optional fields, or override the values for the required ones, create your own mender-connect.conf and augment the mender-connect recipe with the new configuration. For example, create a mender-connect_%.bbappend file in your layer, and add this:

FILESEXTRAPATHS:prepend := "${THISDIR}/<DIRECTORY-WITH-MENDER-CONNECT-CONF>:"
SRC_URI:append = " file://mender-connect.conf"

do_install:append() {
    install -m 600 ${WORKDIR}/mender-connect.conf ${D}/${sysconfdir}/mender/mender-connect.conf
}

Replace with the path to the mender-connect.conf file, relative to the recipe file.

Monitor

Note: The Mender Monitor add-on package is required. See the Mender features page for an overview of all Mender plans and features.

Download the Mender Monitor add-on from https://downloads.customer.mender.io/content/hosted/mender-monitor/yocto/1.4.0/mender-monitor-1.4.0.tar.gz and download the tarball to a known location on your local system using your hosted Mender username and password:

HOSTED_MENDER_EMAIL=<your.email@example.com>
curl --fail -u $HOSTED_MENDER_EMAIL -o ${HOME}/mender-monitor-1.4.0.tar.gz https://downloads.customer.mender.io/content/hosted/mender-monitor/yocto/1.4.0/mender-monitor-1.4.0.tar.gz

Add the meta-mender commercial layer to your build layers:

bitbake-layers add-layer ../sources/meta-mender/meta-mender-commercial

To use Mender Monitor you need to accept its commercial license. If you decide to accept it, add the following line to your local.conf:

LICENSE_FLAGS_ACCEPTED:append = " commercial_mender-yocto-layer-license"

Give the mender-monitor recipe the path to the local source code just downloaded:

SRC_URI:pn-mender-monitor = "file://${HOME}/mender-monitor-1.4.0.tar.gz"

Then make Mender monitor a part of your image with:

IMAGE_INSTALL:append = " mender-monitor"

Which means your local.conf should now contain the following lines:

LICENSE_FLAGS_ACCEPTED:append = " commercial_mender-yocto-layer-license"
SRC_URI:pn-mender-monitor = "file://${HOME}/mender-monitor-1.4.0.tar.gz"
IMAGE_INSTALL:append = " mender-monitor"

mender-gateway

Mender Gateway is only available in the Mender Enterprise plan. See the Mender plans page for an overview of all Mender plans and features.

Download the Mender Gateway from https://downloads.customer.mender.io/content/hosted/mender-gateway/yocto/2.0.0/mender-gateway-2.0.0.tar.xz and download the tarball to a known location on your local system using your hosted Mender username and password:

HOSTED_MENDER_EMAIL=<your.email@example.com>
curl --fail -u $HOSTED_MENDER_EMAIL -o ${HOME}/mender-gateway-2.0.0.tar.xz https://downloads.customer.mender.io/content/hosted/mender-gateway/yocto/2.0.0/mender-gateway-2.0.0.tar.xz

Add the meta-mender commercial layer to your build layers:

bitbake-layers add-layer ../sources/meta-mender/meta-mender-commercial

To use Mender Monitor you need to accept its commercial license. If you decide to accept it, add the following line to your local.conf:

LICENSE_FLAGS_ACCEPTED:append = " commercial_mender-yocto-layer-license"

Give the mender-gateway recipe the path to the local source code just downloaded:

SRC_URI:pn-mender-gateway = "file://${HOME}/mender-gateway-2.0.0.tar.xz"

Then make Mender monitor a part of your image with:

IMAGE_INSTALL:append = " mender-gateway"

Which means your local.conf should now contain the following lines:

LICENSE_FLAGS_ACCEPTED:append = " commercial_mender-yocto-layer-license"
SRC_URI:pn-mender-gateway = "file://${HOME}/mender-gateway-2.0.0.tar.xz"
IMAGE_INSTALL:append = " mender-gateway"

Configuration

To configure mender-gateway, create your own mender-gateway.conf and augment the mender-gateway recipe with the new configuration. For example, create a mender-gateway_%.bbappend file in your layer, and add this:

FILESEXTRAPATHS:prepend := "${THISDIR}/<DIRECTORY-WITH-MENDER-GATEWAY-CONF>:"
SRC_URI:append = " file://mender-gateway.conf"

do_install:append() {
    install -m 600 ${WORKDIR}/mender-gateway.conf ${D}/${sysconfdir}/mender/mender-gateway.conf
}

Replace with the path to the mender-gateway.conf file, relative to the recipe file.

Examples package

You should not use this package on production devices.

See Downloads for download links for this package.

To integrate it on your Yocto build, add the meta-mender demo layer to your build layers:

bitbake-layers add-layer ../sources/meta-mender/meta-mender-demo

Then, append the packae to mender-gateway sources:

SRC_URI:pn-mender-gateway:append = " file:///${HOME}/mender-gateway-examples-2.0.0.tar"

This will install the following on your device:

  • Self-signed demo certificate and key for *.docker.mender.io
  • Demo configuration file with UpstreamServer configured for hosted.mender.io

We welcome contributions to improve this documentation. To submit a change, use the Edit link at the top of the page or email us at .