In order to ensure a secure and robust update process, Mender needs additional metadata alongside the raw bits of the update payload. Depending on the version of the Artifact used, the metadata might be different, but must contain the:
To handle the requirements mentioned above, Mender uses a
specific file format, identified by its
.mender suffix which is also known 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 doing software deployments.
Internally, a Mender Artifact is simply a file archive in the tarball format. It contains several files for incorporating versioning, extensions, metadata and the payload file(s).
Mender Artifact compresses artifact payloads by default and supports multiple compression algorithms to do so.
The diagram below shows an example of the main attributes and structure of a Mender Artifact file.
The exact Artifact format may vary between versions.
You can find more details about the Mender Artifact format in the Mender Artifact specification.
In addition to Version information, an Artifact may contain additional Provides fields which the Mender client will store on the device during the Artifact installation.
In addition to Device types information, an Artifact may contain additional Depends fields. On Artifact installation, all Depends fields need to match a corresponding Provides field on the device.
An example of this is the checksum of a read-only root filesystem. During the installation of a delta Artifact, the server uses the information about the existing checksum to decide which Artifact to deploy. Take an Artifact with these fields:
Provides: rootfs-image.checksum: 012345... Depends: rootfs-image.checksum: abcdef...
The Artifact in the example above can only be installed on a device which has
Provides: rootfs-image.checksum: abcdef... stored in its database, because of
the Depends entry. And future Artifacts need to list
Depends: rootfs-image.checksum: 012345... in their dependencies to match the newly
Not all Artifacts have dependencies; if they don't, then it doesn't matter what the Provides values on the device are.
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.
In cases where Artifact downloads are interrupted, e.g. due to unreliable wireless network connectivity, the Mender client will resume the download from where it was interrupted, using HTTP range requests.
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, as well as some of the metadata, like headers, currently with the gzip compression algorithm by default.
Mender is constantly evolving to adapt to the needs of its users, and the Mender Artifact format has several revisions. See the Compatibility section for an overview of which versions of the Mender Artifact format are supported by which Mender client versions.
The command-line utility
mender-artifact is the best way to work directly with
Mender Artifacts. It allows you to view, create, modify and sign all types of
Mender Artifacts. Get it in the
Mender also has OS-level integrations for creating system updates as part of your existing OS build process. Learn more by reading the following sections:
To verify that the Artifact comes from a trusted source, the Mender Artifact format supports end-to-end signing and verification. In order to create a signed Artifact, please follow the instructions at Sign & Verify.
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