Artifact
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:
- Name of the software build, used to track names of Artifacts and ensures that the same Artifact is not deployed twice in a row.
- Version of the software build, used to track installed software on a given device.
- Device types the software is compatible with, so that software is not deployed to incompatible hardware (e.g. CPU architecture, hardware floating point support, peripheral drivers).
- Checksum of the payload, so that software is not run if it gets corrupted during transit or storage.
The Mender Artifact file format
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.
Provides and Depends
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
installed Artifact.
Not all Artifacts have dependencies; if they don't, then it doesn't matter what the Provides values on the device are.
Streaming, resume and compression
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.
Artifact format versions
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.
Work with Mender Artifacts
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
Downloads section.
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:
Sign and verify
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.