Description
The Directory Overlay Update Module installs a user defined file tree structure into a given destination directory in the target.
Before the deploy into the destination folder on the device, the Update Module will take a backup copy of the current contents, allowing restore of it using the rollback mechanism of the Mender client if something goes wrong. The Update Module will also delete the current installed content that was previously installed using the same module, this means that each deployment is self contained and there is no residues left on the device storage from the previous deployment.
Example use-cases:
- Deploy root filesystem overlays
Specification
| Module name | dir-overlay |
| Supports rollback | yes |
| Requires restart | no |
| Artifact generation script | yes |
| Full operating system updater | no |
| Source code | Update Module, Artifact Generator |
| Maintainer | Community |
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 the complete operating system. Always inspect the code carefully and only test modules on a devices 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:
- Install the Mender client, version 2.0 or later
The dir-overlay module will store state information in /var/lib/mender, and that is:
- Manifest files of current and previous installation
- list of files
- Backup of current installed files based on previous manifest, which is used in case of roll-back
Sample directory layout:
$ ls /var/lib/mender/dir-overlay/
backup.tar manifest manifest.prev
The dir-overlay directory is created by the module.
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/dir-overlay/module/dir-overlay && chmod +x /usr/share/mender/modules/v3/dir-overlay
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:
- Install mender-artifact , version 3.1.0 or later
Create Mender Artifacts
For convenience, an Artifact generator tool dir-overlay-artifact-gen is provided along the module. This tool will generate Mender Artifacts in the same format that the Update Module expects them.
To download dir-overlay-artifact-gen, run the following:
wget https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/dir-overlay/module-artifact-gen/dir-overlay-artifact-gen
Make it executable by running,
chmod +x dir-overlay-artifact-gen
Create example root filesystem content to deploy,
# The permissions must match DEST_DIR on the device, otherwise this module will
# overwrite the set permissions.
#
# You can check this by running the following command on the device (if DEST_DIR="/"):
#
# stat -c %a /
#
sudo install -d -m 755 -g root -o root rootfs_overlay
# Create directory structure
sudo install -d -m 755 -g root -o root rootfs_overlay/etc
sudo install -d -m 755 -g root -o root rootfs_overlay/usr/bin
sudo install -d -m 755 -g root -o root rootfs_overlay/usr/share/app
# Create sample files
sudo touch rootfs_overlay/etc/app.conf
sudo touch rootfs_overlay/usr/bin/app
sudo touch rootfs_overlay/usr/share/app/data.txt
# You would typically chmod above files to have the appropriate mode in a production environment
The result should look like this:
$ tree rootfs_overlay/
rootfs_overlay/
├── etc
│ └── app.conf
└── usr
├── bin
│ └── app
└── share
└── app
└── data.txt
5 directories, 3 files
Now generate your 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="/"
OVERLAY_TREE="rootfs_overlay"
./dir-overlay-artifact-gen -n ${ARTIFACT_NAME} -t ${DEVICE_TYPE} -d ${DEST_DIR} -o ${OUTPUT_PATH} ${OVERLAY_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.mendersuffix -
DEST_DIR- The path on target device where content ofOVERLAY_TREEwill be installed. -
OVERLAY_TREE- The path a folder containing the contents to be installed on top of theDEST_DIRon 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 three payload files:
-
update.tar- a tarball containing all the files to be deployed -
dest_dir- a regular file with theDEST_DIRin plain text -
manifest- a regular file with a list of files installed in plain text
The Mender Artifact contents will look like:
Artifact my-update-1.0.mender generated successfully:
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:
Updates:
0:
Type: dir-overlay
Provides: Nothing
Depends: Nothing
Metadata: Nothing
Files:
name: update.tar
size: 10240
modified: 2019-04-01 12:01:41 +0000 UTC
checksum: fabfd7f6739d35130dd05dbab42ff7fe8baa76fea22f134b254671bd52604807
Files:
name: dest_dir
size: 2
modified: 2019-04-01 12:01:41 +0000 UTC
checksum: f465c3739385890c221dff1a05e578c6cae0d0430e46996d319db7439f884336
Files:
name: manifest
size: 48
modified: 2019-04-01 12:01:41 +0000 UTC
checksum: fc582174946ec48e2782ed9357e9d4389cc0e2a3bfbc261b418d4fd5a326d472
