You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 1.1.
As described in the architecture overview Mender uses the output from a build system and deploys this to remote devices.
In order to ensure a robust update process, Mender needs additional metadata alongside the raw bits of the file system. Depending on the version of the Artifact used, the metadata might be different, but must contain:
Furthermore, as new use cases and platforms are supported in the future, more metadata is expected to be needed as part of the Mender deployment process.
To handle the requirements mentioned above, Mender defines and uses a
specific file format, identified by its
.mender suffix. A file in this format
is referred to as a Mender Artifact, or simply an Artifact.
All relevant components of Mender, such as the client and server, understand
and use (only) this specific file format when working with software deployments.
Internally, a Mender Artifact is simply a file archive in the tarball format. It contains several files for incorporating versioning, extensions and metadata, as well as the main file: the root file system.
The diagram below shows an example of the main attributes and structure of a Mender Artifact file. Please note that the exact format of the artifact may vary between versions.
Mender is constantly evolving to adapt to the needs of its users. As new features are added, new versions of the Mender Artifact format may be introduced as well, if the features require it.
At the moment there are two different versions of the Mender Artifact format. The compatibility matrix for Mender Client and Artifact versions is shown below:
|Artifact v1||Artifact v2|
|Mender Client 1.0.X||yes||no|
|Mender Client 1.1.X||yes||yes|
Older Mender clients do not support newer versions of the Artifact format; they will abort the deployment. You can build older versions of the Mender Artifact format to upgrade older Mender clients. See Write a new Artifact for an introduction how to do this.
In addition to what is included in version 1, version 2 adds support for image signing and verification. Among the other metadata it contains manifest and manifest.sig files, which are the collection of the file checksums and the signature of the manifest respectively. More details about the exact format of the Mender Artifact can be found in the Mender Artifact file documentation.
The tar format supports streaming, which Mender takes advantage of. As a Mender Artifact is downloaded from the Mender server or external storage, the Mender client streams the root file system within it directly to the inactive partition, without needing any temporary storage for unpacking it before it is written. This drastically reduces storage requirements for the update process, improves performance and reduces flash wear.
To enable streaming and control based on metadata, like aborting the download if the Artifact is not compatible with the device, the Mender Artifact itself is not compressed. Instead, the root file systems within Artifacts are compressed, currently with the gzip compression algorithm.
To verify that the Artifact comes from a known source, the Mender Artifact format supports image signing and verification. In order to create a signed Artifact, which can be verified by the Mender Client during the update process, please follow the instructions at Signing and verifying Mender Artifact.
The easiest and most common way to generate Mender Artifacts is by adding the meta-mender layer to your Yocto Project build environment. There is more information on how to do this as part of the tutorial Building a Mender Yocto Project image.
Although it is possible to use a tar utility to extract, modify and package Mender Artifacts, this is error-prone due to the amount of details that need to be handled, like the ordering of the files, contents of metadata and checksum computation. For this reason, it is recommended to use the Mender Artifact utility or Go library when you need to work with Mender Artifacts. The Mender Artifacts library and utility is available as open source in the Mender Artifacts repository and there is a tutorial using the utility at Modifying a Mender Artifact.