The Directory Update Module installs a user defined file tree structure (files and subfolders) into a given destination directory on the device.

Before deploying to the destination folder on the device, the Update Module will take a backup copy of the current contents. This allows to restore it with the rollback mechanism of the Mender client if something goes wrong.

Example use-cases:

  • Updating an application which resides in a standalone directory on the system


Module name directory
Supports rollback yes
Requires restart no
Artifact generation script yes
Full system updater no
Source code Update Module, Artifact Generator

Please be aware that Mender Update modules are meant to update parts of the system and if not configured properly they could potentially delete parts or the complete system. Always inspect the code carefully and only test modules on a systems 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.


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 -N -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

For convenience, an Artifact generator tool directory-artifact-gen is provided with the Update Module. This tool will generate Mender Artifacts in the same format that the Update Module expects them.

Download directory-artifact-gen, by running the following command:


Make it executable:

chmod +x directory-artifact-gen

Create example content to deploy:

mkdir dir-to-deploy
echo "File created by Mender directory Update Module!" > dir-to-deploy/file1.txt
echo "File created by Mender directory Update Module!" > dir-to-deploy/file2.txt

Now generate a Mender Artifact using the following command:

./directory-artifact-gen -n ${ARTIFACT_NAME} -t ${DEVICE_TYPE} -d ${DEST_DIR} -o ${OUTPUT_PATH} ${FILE_TREE}
  • 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
  • DEST_DIR - The path on target device where content of FILE_TREE will be installed.
  • FILE_TREE - The path to a folder containing the contents to be sent to the device in the update.

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 two payload files: a tarball containing all the files to be deployed and a regular file with the DEST_DIR in plain text.

The Mender Artifact contents will look like:

    Type: directory
    Provides: Nothing
    Depends: Nothing
    Metadata: Nothing
        name: update.tar
        size: 17571840
        modified: 2019-03-05 15:20:42 +0100 CET
        checksum: dab0a292a8c2a089eb0a22e56082e51fcfa5485264b66063a4f9798db919af23
        name: dest_dir
        size: 12
        modified: 2019-03-05 15:20:42 +0100 CET
        checksum: 5dfbbf0a8baa51888494fa5fe1665cc5b2826419f9ec6d90a92eeabd54a0f574

@lluiscampos, I have 2 doubts here:

  1. May I know the purpose of ARTIFACT_NAME="my-update-1.0"? AFAIK, the update module artifact will perform the update even if we run the same ARTIFACT_NAME="my-update-1.0" twice or more on the target. Moreover, this is different from the previous artifact info (previous one will check and prevent the update to run if the name is same on the target):

$ cat /etc/mender/artifact_info

  1. Standalone mode - The update module extracts and details are present for me inside the /data/mender/ even after update module tasks are completed. These extracts will go only when I do mender -commit after the update module completes.
    Is this the expected behavior?

Hi @ajithpv

  1. The Artifact name is important when using the Mender Server. You are right in that in standalone version it will always be installed (independently of being an Update Module or a classic rootfs-image), but the Server will prevent a re-install of the same Artifact. You should anyway version your Artifacts correctly.
  • Note: The /etc/mender/artifact_info file is deprecated from Mender 2.0 onward, as such info is now saved in the database.
  1. Yes, that is the expected behavior. The reason for it is that an Update Module might need to access the files during Rollback or Commit operations.

See Update Modules v3 API documentation for more details.

1 Like

Thank you for the clarification. I understood why artifact name is required for update module and also the mender -commit requirement.

Could you please confirm that, the /etc/mender/artifact_info file is removed in the mender 2.0.0b (beta)? I have upgraded to Mender 2.0.0b from Mender 1.7.0 and this file is present in my target! I didn’t get whether this file is removed in beta itself or only on the final mender 2.0.0 which yet to release :thinking:

It is still present as a way to identify the very first artifact name, before any additional artifact has been installed.

1 Like

I’m trying to use this module, but it seems that there’s something going wrong with key verification.
I used mender-artifact sign to sign the .mender file containing a directory. The device downloads the file, but then sayd:
“Fetching Artifact headers failed: installer: failed to read Artifact: readHeaderV3: reader: invalid signature: crypto/rsa: verification error”

Am I missing something?

I can’t say whether this is the cause of your issue, but there is definitely a serious bug when using the sign command on an artifact using update modules. Signing while creating the original artifact seems to work though, but there is an additional bug in 2.0.0 which prevents the argument from taking effect.

Can you try this workaround:

  1. Download the directory-artifact-gen from 2.0.x.
  2. Using this new generator, create the artifact again, and while doing so, append these arguments to the end:
    -- -k private.key
    Where private.key is the key you use to sign the artifact.
  3. Then retry the deployment.

Hi @kacf,
Please let me know the usage example for directory-artifact-gen? I have tried few but failed to create the signed artifact for docker…
Unable to understand where to specify the {DOCKER_IMAGES} and what is --dest-dir , directory options for it?

~/new-workspace/mender/docker-updatemodule/directory-artifact-gen --artifact-name {ARTIFACT_NAME} --device-type {DEVICE_TYPE} --dest-dir ~/new-workspace/mender/docker-images/ --output-path {OUTPUT_PATH} directory {DOCKER_IMAGES} – -k …/artifact-keys/private.key
File tree already specified. Unrecognized argument “debian@sha256:84e2351ae76c072adac3b6e0a958e5b238e693bdff3cc4f3c94eace3d4577f76”

You cannot use the directory-artifact-gen for generating docker artifacts. For that you need to use the docker-artifact-gen from 2.0.x.

Somehow, using the latest still doesn’t work correctly it seems. Still the same error.

Looking at the mender UI, the package seems signed correctly, and contains the update.tar and dest_dir files.

Is this something in mender client2.0.0?

Any update on this? You guys need more info on my environment or situation to diagnose this?

Server not the hosted cloud mender, but running on 2.0. Client is on 2.0 as well.

according to mender-artifact verify, the resulting .mender file is correct.

Thanks in advance!

Hmm, nothing immediate comes to mind; it’s a brand new error to me. You say that mender-artifact verifies the file. Does that include passing the -k argument and the public key to have the signature verified as well?

Yes, this is including the -k.

1 thing I haven’t tried yet, is to run mender-artifact verify on the device. But this shouldn’t matter.

Any other suggestions to check out? Anyone gotten this to work?

(Also, I’d be happy to do a teamviewer session or so to figure this out…)

Can you post the output from mender-artifact read <artifact.mender>?

Output, including invocation:

./mender-artifact read output.mender -k public.key
Mender artifact:
Name: testapp-3
Format: mender
Version: 3
Signature: signed and verified correctly
Compatible devices: ‘[raspberrypi3]’
Provides group:
Depends on one of artifact(s): []
Depends on one of group(s): []
State scripts:

    Type:   directory
    Provides: Nothing
    Depends: Nothing
    Metadata: Nothing
      name:     update.tar
      size:     10240
      modified: 2019-06-11 18:53:39 +0200 DST
      checksum: 5a23f139c5fa97881876cd81b32b3b8c4bda0d8861844e8cc608ca34d68a596a
      name:     dest_dir
      size:     9
      modified: 2019-06-11 18:53:39 +0200 DST
      checksum: 77516a23517355d95d8eb3014d6309e5ab38efe8abdfb90bc91ef1191fbd7aef

Nothing out of the ordinary AFAICS. Any chance you could post the artifact? Or perhaps one without sensitive content, if you can still reproduce it then. Preferably the public key as well.

See attached.

My main objective is working around a firmware updating issue I have with my raspberry’s though.

(Attachment public.key is missing)

(Attachment output.mender is missing)

How would I go about posting the artifact and key file? I tried attaching them, but I get an error about dangerous extensions…

I’m not sure but maybe putting them in a zip file will work. I guess it depends on how aggressive discourse is about scanning.

The other option is to put them on google drive or some such and just post a link.

How about posting them at ?