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 rootfs-image-v2 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 (upload it under Releases in the server UI) 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
1 Like

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.

Hello @lluiscampos . I followed this document to get the full system update and I came to the end. But when I run the last command, I get an answer like this:

root@ubuntu:/home/robust2# ARTIFACT_NAME=“full-update-1.0”
root@ubuntu:/home/robust2# DEVICE_TYPE=“imx6ul-var-dart”
root@ubuntu:/home/robust2# OUTPUT_PATH=“full-update-1.0.mender”
root@ubuntu:/home/robust2# IMAGE=“rootfs.ext4”
root@ubuntu:/home/robust2# ./mender-artifact write module-image -T rootfs-image-v2 -n {ARTIFACT_NAME} -t {DEVICE_TYPE} -o {OUTPUT_PATH} -f {IMAGE}
writer: can not open data file: rootfs.ext4: open rootfs.ext4: no such file or directory

Finally I can’t generate artifact.
What is the reason of this ? What does the image mean? How do I fix this problem?

Hello again @mEK,

This Update Module requires a full filesystem image. If you have full Mender integration in your device (namely A/B filesystems), you can generate update images for your device the same way you created the first image: using Yocto project or mender-convert .

Then, once you have an image, you can specify the path with IMAGE=... for the Mender Artifact to include it.

Thank you for your quick and clear answer. First of all, what are the steps I need to follow for full mender integration? Where do you think I should start? Is meta-mender not enough to create an A / B root file system?

But how have you installed Mender in your device?

Your logs hint that you are using an NXP imx6 based board, so maybe you have followed a Board integration tutorial here on Mender Hub? If so, you have already yocto environment ready to create new images :slight_smile: