Create an Artifact

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.

Create a full filesystem update Artifact

Assuming you already have a generated filesystem image in rootfs.ext4 file, 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 Debian image.

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-version specifies the version string for the rootfs-image.
• -o: specifies the path to the output file.

Create an application update Artifact

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 /home/pi/.ssh 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.

Update Modules generation script

You can see the above example in the single file Update Module. You can also see how simple it is to write a custom Update Module.

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.

Server side Artifact generation

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.

For more details on how to write Update Modules, visit the Create a custom Update Module section and the Update Module API specification.