Dirty (template module /example)

Update Modules
1

Description

The dirty Update Module: modify your device state without installing an Artifact.

Example use-cases:

  • you have a specific action on the device that you want to run multiple times
  • you want to avoid re-creating artifacts just for the sake of a new version/name
  • you don’t want the artifact the show up in the list of installed artifacts

The module will always fail the update process, which means it can never be marked as installed. So it can be attempted any number of times without having to recreate newly versioned artifacts.

Benefits:

  • you can put your desired operation into the dirty_action function
  • after the (failed) deployment, you can check if your operation
    • finished successfully: the update failed in ArtifactCommit
    • resulted in an error: the update failed in ArfifactInstall

Specification

NOTE: the given module is a template that is meant to insert your own functionality!

Specification
Module name dirty
Supports rollback no
Requires reboot no
Artifact generation script yes
Full operating system updater no
Source code GitHub
Maintainer josef.holzmayr@northern.tech

TODO: Consider removing below warning if you deem your Update Module to not fit the description.

Please be aware that Mender Update modules are meant to update parts of the operating system and if not configured properly they could potentially delete parts or even the full operating system. Always inspect the code carefully and only test modules on device that you can recover easily.

It is not recommended to install a Mender Artifact on your workstation

Prepare the device

This section describes how to setup 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:

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

Install the Update Module

Download the latest version of this Update Module by running:

mkdir -p /usr/share/mender/modules/v3 && wget -P /usr/share/mender/modules/v3 https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/dirty/module/dirty && chmod +x /usr/share/mender/modules/v3/dirty

Package your “dirty” operation

The example structure provides all necessary states and a dirty_action stub function. The operation to
occur should be implemented in the dirty_action stub, and return

  • 0 upon successful completion
  • != 0 upon error

Prepare the development environment on your workstation

This section describes how to set up your development environment on your workstation.

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

Prerequisites

This Update Modules has the following prerequisites for the development environment:

Create Mender Artifacts

ARTIFACT_NAME="my-update-1.0"
DEVICE_TYPE="my-device-type"
./dirty-artifact-gen --artifact-name ${ARTIFACT_NAME} \
                     --device-type ${DEVICE_TYPE}

You can either deploy this Artifact in managed mode with the Mender server (upload it under Releases in the server UI) or by using the Mender client only in Standalone deployments.

Artifact technical details

This Update Module is a template with an example action that alters the persistent state of the device without being installed, technically through failing in the process.
A key consideration for this was to define the action in a static way, so it cannot be (un-)intentionally changed, the Artifact is just the trigger.