Mender Configure update module

Description

An update module to manage device configuration via Mender Configure add-on. See Mender Docs for an overview of the add-on.

mender-configure is the update module responsible for fetching and reporting configuration, and requires the user to use one or multiple apply-device-config script(s) to apply the configuration on the device. See Mender Docs guide How to make an apply-device-config script for more details.

Example use-cases:

  • Setting timezone
  • Setting WiFi credentials
  • Setting firewall rules
  • Setting any user-specific configuration parameters

Specification

Specification
Module name mender-configure
Supports rollback Yes
Requires reboot Maybe(*)
Artifact generation script No(**)
Full system updater No
Source code GitHub repository
Maintainer Northern.tech

(*) It depends on the user provided apply-device-config scripts
(**) The Artifact is generated in the Mender UI

Prepare the device

This section describes how to set up your target device, i.e. the device to be updated. This will also be referred to as the device environment.

All commands outlined in this section should be run in the device environment.

Prerequisites

This Update Module has the following prerequisites for the device environment:

Install the Update Module

Follow the instructions that correspond to your device setup.

Yocto project

mender-configure is available in meta-mender releases dunfell-v2021.04 and newer. If you are using meta-mender-demo layer, the Update Module is added to your image by default together with some apply-device-config script. If not, you can add it to your image with

IMAGE_INSTALL_append = " mender-configure"

Debian family (via mender-convert)

mender-configure is available for mender-convert builds, and is enabled setting the following variable:

MENDER_ADDON_CONFIGURE_INSTALL=”y”

The specific version to install can also be configured if desired. See Mender Docs page for more information.

Debian family (standalone deb package)

mender-configure is also available in the Mender APT repository. Follow instructions in Mender Docs to install the repository in your device. Then, install mender-configure with:

sudo apt-get update
sudo apt-get install mender-configure

From source

Alternatively to all the above, it is possible to install from source. Follow these steps:

git clone -b 1.0.3 https://github.com/mendersoftware/mender-configure-module.git
cd mender-configure-module
make install

Install apply-device-config script(s)

To actually apply the configuration on your device, Mender relies on user supplied apply-device-config scripts. See Mender Docs guide How to make an apply-device-config script for a complete guide on how to write such scripts.

As an example, see the timezone script which sets the timezone of the device, according to the “timezone” key, given in the file in the first argument.

Deploy configuration updates

The configuration Artifacts are generated by the Mender Server on the fly, so no local use of mender-artifact nor other generation scripts are required. See Mender Docs for more information.

Hi there,

Thanks for this great feature. Am I right with the assumption that there is nothing speaking against deploying a configuration directly to a device group, since they are artifacts/deployments? Would it also be possible to create a kind of default config deployment mechanism that sends a config to a device receives when it gets added to a group? Or have I missed another feature that could be able to handle this?

Cheers,
Dominik

Indeed you can. The only difference is that you have to create and upload the artifact yourself, you can’t do it directly with the configuration editor.

I think you can do this with dynamic deployments, but I’m not an expert in this area, so don’t take my word for it.

1 Like

I have some small questions about the mender-configure module. My organization is considering using Mender for OTA updates for both our system and application software and I’d like to propose moving configuration over to Mender as well if it is able to be feature-complete with our current in-house solution.

  1. When I push a configuration through the hosted.mender.io frontend, the deployment succeeds and /var/lib/mender-configure/device-config.json on the device is modified. However, the frontend does not reflect the new configuration and displays the following message:
The device appears to either have an empty configuration or not to have reported a configuration yet.

It appears that the configuration state on the device does not properly make it back to the server. As a result, subsequent configuration changes will overwrite the configuration json file on the device rather than update it. My mender-client has been set up in the demo mode as advised by the starter docs if that is relevant to this situation.

  1. Does hosted.mender.io support all JSON as configuration? It appears that all values I enter are coerced to JSON strings, even valid JSON values such as the numeral 1.

I have had a positive experience so far testing Mender for OTAs and would love if we could use it for device configuration as well. Thank you for taking the time to read!

The reporting of values back to the server is supposed to be done by the /usr/share/mender/inventory/mender-inventory-mender-configure script. Can you run it manually, and look for error messages?

At the moment, only strings are supported. One workaround which has been suggested in a different thread is to embed a second JSON string inside one of the values of the primary JSON document, and then decode that. Obviously this will need some escaping of certain characters.

1 Like

Since config updates are just artifacts, I’m wondering how mender-client behaves if ArtifactVerifyKey is set to a public key file. If I understand the documentation correctly, once ArtifactVerifyKey is set, all artifacts must be signed with the corresponding private key. However, since the configuration artifact is created on the fly in Mender’s cloud it couldn’t be signed with my private key. How does this work?

It doesn’t. Configure and Signed Artifacts are mutually exclusive when using the UI. You can of course make your own signed Configure Artifact and upload that, but then it is just a normal deployment, and won’t have support through the UI.

Hello! During our testing of mender-configure, we found that if you successfully set a configuration parameter through the mender UI and then do a clean flash of the device, the parameter that was set through the mender UI is lost once the device comes back online. Is this the intended outcome?

Yes, the device is the “source of truth”. The server has the power to change the contents, but once the deployment is over, the server will obey whatever the client says that it has.

1 Like

Great! Thanks for the info!