Root Filesystem Image v2


This module performs a full rootfs filesystem updates on the device. The module was originally developed for testing purposes and it is published as a non-official alternative way of doing rootfs updates on systems with dual partition layout (A/B).

It supports rollback in the same way as the conventional root filesystem update: rolling back to the old partition on any unforeseen problem. See Mender Architecture documentation to learn more about this design.


Module name rootfs-image-v2
Supports rollback yes
Requires restart yes
Artifact generation script no
Full system updater yes
Source code Update Module

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.


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

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.


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

Create Mender Artifacts

The Artifact can be generated using mender-artifact tool. To generate a deb Update Module Mender Artifact, you can use command:

mender-artifact write module-image -T rootfs-image-v2 -n ${ARTIFACT_NAME} -t ${DEVICE_TYPE} -o ${OUTPUT_PATH} -f ${IMAGE}
  • ARTIFACT_NAME - The name of the Mender Artifact
  • DEVICE_TYPE - The compatible device type of this Mender Artifact
  • OUTPUT_PATH - The path where to place the output Mender Artifact. This should always have a .mender suffix
  • IMAGE - The path to the rootfs image to be packaged in the Artifact

You can either deploy this Artifact in managed mode with the Mender server as described in Deploy to physical devices or by using the Mender client only in Standalone deployments.

Artifact technical details

The Mender Artifact used by this Update Module has the root filesystem image as the only payload.

The Mender Artifact contents will look like:

Mender artifact:
  Name: my-update-1.0
  Format: mender
  Version: 3
  Signature: no signature
  Compatible devices: '[my-device-type]'
  Provides group: 
  Depends on one of artifact(s): []
  Depends on one of group(s): []
  State scripts:

    Type:   rootfs-image-v2
    Provides: Nothing
    Depends: Nothing
    Metadata: Nothing
      name:     rootfs.ext4
      size:     0
      modified: 2019-04-15 11:59:24 +0200 CEST
      checksum: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

hmm, this is confusing:

  • what is the difference from using mender-artifact write rootfs-image?
  • mender-artifact write module-image -h says that “This command is not meant to be used directly, but should rather be wrapped by an update module build command

The former command creates a normal rootfs update, the latter creates an update meant for an update module. Since update modules are generic plugins, there is no one command that can be recommended. Instead the update module should come with its own artifact build command which uses the module-image command under the hood.