Mender uses Artifacts to package the
software updates for delivery to devices. As a user you manage the Artifacts
with the help of the
mender-artifact command. You can get it either as a pre-built
executable from the downloads section
or build from sources.
The two basic usage scenarios of this utility reflect the two main update types
Mender supports: full filesystem update and application update.
Assuming you already have a generated filesystem image in
you can use the following command to generate an Artifact that contains the entire filesystem image as the payload:
mender-artifact write rootfs-image \ -t beaglebone \ -n release-1 \ --software-version rootfs-v1 \ -f rootfs.ext4 \ -o artifact.mender
Note that the
rootfs.ext4 filesystem image must be properly integrated with Mender for successful deployments. This generally means that you either generated it using the Yocto Project, or converted it from an existing
The remaining flags specify the parameters used to match devices to deployments as follows:
-t: specifies the compatible device types.
-n: specifies the name of the Artifact.
--software-versionspecifies the version string for the rootfs-image.
-o: specifies the path to the output file.
Use the Mender Web UI to see which rootfs-image version is currently installed on the device, and which Artifact was the last one to be installed.
Creating an Artifact takes a different form in the case of application updates.
For example, assume that you want copy a new
authorized_keys file to the
directory on your devices. We first store the path to the destination directory and file into two separate files, for packaging purposes:
echo /home/pi/.ssh > dest_dir # store the destination target directory echo authorized_keys > filename # store the filename of the file we want to update
We can now create the Artifact using mender-artifact by running the following command:
mender-artifact write module-image \ -T single-file \ --device-type raspberrypi4 \ -o artifact.mender \ -n updated-authorized_keys-1.0 \ --software-name authorized_keys \ --software-version 1.0 \ -f dest_dir \ -f filename \ -f authorized_keys
Note specifically that in this case we are creating a module-image, using the single file Update Module. The Artifact created will be compatible with the raspberrypi4 device type, although you can specify multiple device types if needed. The name of the Artifact is declared as updated-authorized_keys-1.0, we set the name of the software we are installing to authorized_keys, and the version is set to 1.0. The payload files we created earlier are included, and the resulting file
artifact.mender holds the Artifact. Please note that, single-file is both the name of the Update Module and the Artifact type. Please note also, that the payload files must use the name specified here.
Also note that most of the Update Modules come with a script to simplify the Artifact creation, but generally these are wrappers around
mender-artifact utility to hide the complexity and make it easy to generate artifacts.
The hosted Mender server and any on-premise server installation, can generate application update Artifacts automatically using the single file Update Module. You can test it by uploading any file to the releases page. The resulting Artifact will carry the file you have uploaded, the destination directory, the filename, and permissions, exactly as we saw above.
Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to submit changes.
© 2021 Northern.tech AS