Directory

Description

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

Specification

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.

Prerequisites

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 https://raw.githubusercontent.com/mendersoftware/mender/master/support/modules/directory

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

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:

wget https://raw.githubusercontent.com/mendersoftware/mender/master/support/modules-artifact-gen/directory-artifact-gen

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:

ARTIFACT_NAME="my-update-1.0"
DEVICE_TYPE="my-device-type"
OUTPUT_PATH="my-update-1.0.mender"
DEST_DIR="/opt/installed-by-directory/"
FILE_TREE="dir-to-deploy"
./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 (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 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:

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

4 posts were split to a new topic: ARTIFACT_NAME when using Update Modules

26 posts were split to a new topic: Issue with key verification using Directory Update Module

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.

14 posts were split to a new topic: Issues with rollback using Directory Update Module

Hi,

I’m trying to create and deploy a directory artifact. Creation did work, I could upload to Mender Server, but when I want to deploy, I’m getting a “no artifact” message from Mender Server.

This is how the artifact is recognized by Mender Server:

This is the message I got when trying to deploy this artifact:

When I check the logs on the device, there was never an attempt to install something, in other words, the server did not deploy this artifact.

Any idea what is wrong with my generated artifact?

Edit: I tried to deploy this very artifact to another device. This worked flawlessly. In that case it does not seem to be the artifact itself but my device. What is wrong then? I freshly installed mender client on this device as I have done on others. So there is currently no artifact installed. But that shouldn’t be a precondition to deploy a new artifact, right?

Edit2: I was able to solve my problem. It was linked to a wrong device_type on my client. The following happened:
During setup of the device I had a typo in the device_type in /var/lib/mender/device_type. Although I was pretty sure that I later on corrected it (because it was correctly reported to Mender Server in the inventory), it was still wrong in the local device_type. This lead to the above described situation.

All I did was corrected a second time the /var/lib/mender/device_type and then the deployment worked!

Bruno

Great tutorial.
Just wondering how do we handle updating a directory with executables running? does mender provide a handler to stop the execution before going ahead with the update? Thanks.

Nothing specific since it’s going to be very dependent on the system design. The existing update module could be easily updated to handle that for your specifics though.

Is there a way to force a device restart after the artifact gets installed?

Fork and make your own version of the directory Update Module, and implement the ArtifactReboot state, where you should print Automatic and exit 0. This will reboot every time the Update Module installs anything.

You can also add more advanced logic and consider printing No in some cases, if you want to make it conditional.

1 Like

@drewmoseley thanks for that. Is it possible to update multiple folders at different locations in the target device? Thanks.

Not with this update module. You can do that with a custom module.

Are you looking for something like this?