You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 1.7.
A Mender Artifact is a file Mender uses to deploy updates. Please see Mender Artifacts for a more detailed description.
When testing deployments, it is useful that the Artifact you are deploying is different from the one that you have installed so you can see that the update is successful. You might also want to configure certain aspects of the update after you build it, but before deploying it.
In this tutorial we will highlight some key use cases covered by the
mender-artifact utility is used to create and inspect Mender Artifacts.
You can download a prebuilt mender-artifact Linux binary here.
If you need to build
mender-artifact from source, please see Compiling mender-artifact.
If you would like to change the Mender server the devices will be using,
you can use the
mender-artifact modify parameter:
MENDER_SERVER_URL='https://hosted.mender.io' MENDER_TENANT_TOKEN='<YOUR-MENDER-TENANT-TOKEN>' mender-artifact modify artifact.mender --server-uri "$MENDER_SERVER_URL" --tenant-token "$MENDER_TENANT_TOKEN"
--tenant-token parameter is only needed for multi-tenant Mender servers like Hosted Mender. In Hosted Mender you can find it under My organization.
If you are using a self-signed certificate for the Mender server (not needed for Hosted Mender), you can
include it in the Artifact using the
mender-artifact modify artifact.mender --server-cert server.crt
cat parameter will output a file in the Artifact to standard output.
For example, to see
/etc/hosts, run the following command:
mender-artifact cat artifact.mender:/etc/hosts
Files can be copied into and out from the Artifact using the
For example, to modify any Mender client configuration, such as the polling interval,
first copy it out:
mender-artifact cp artifact.mender:/etc/mender/mender.conf /tmp/mender.conf
/tmp/mender.conf and make the desired modifications.
Afterwards, write it back into the Artifact:
mender-artifact cp /tmp/mender.conf artifact.mender:/etc/mender/mender.conf
To control the permissions on the file written to the Mender Artifact, use the
install -m<permissions> parameter instead of
If you have a raw root file system (e.g.
ext4), you can create a Mender Artifact
file from it.
The Mender client and relevant configuration must already be contained in the root file system in order for the created Mender Artifact to be usable.
To create an Artifact, use the
mender-artifact write rootfs-image -t beaglebone -n release-1 -u rootfs.ext4 -o artifact.mender
The Artifact name (
-n) must correspond to the name stated inside the root file system at
If you are building for older Mender Clients that do not support the latest version of the Artifact format, you can build an older Artifact version with the
-v option. For example, to build a version 1 Artifact, you can run
mender-artifact write rootfs-image -v 1 -t beaglebone -n release-1 -u rootfs.ext4 -o artifact.mender. The default Artifact version is the latest one. Also see the build variable MENDER_ARTIFACT_EXTRA_ARGS.
If you would like to generate a signed Artifact, simply add the
-k option with the path to your private key. In our example above, the full command would be
mender-artifact write rootfs-image -t beaglebone -n release-1 -u rootfs.ext4 -o artifact-signed.mender -k private.key.
Currently the standard behaviour is to compress the artifact using
gzip, however you can also opt out of the standard
compression format by giving the
mender-artifact command the global flag
compression, and the argument
meaning that no compression will be done. Example:
mender-artifact --compression none write rootfs-image -t beaglebone -n release-1 -u rootfs.ext4 -o artifact.mender
If you are signing Artifacts, the signature will become invalid whenever you make modifications to them. See the section on signing and verification for more information.
mender-artifact is only necessary if you can not use the prebuilt
mender-artifact binary for Linux.
The Golang compiler is integrated with
git, so we need
on the system. On Ubuntu this can be achieved with:
sudo apt-get install git
Since the Mender Artifact utility is written in golang, a Golang compiler needs to be installed and set up in order to build it. You can find Golang download and installation instructions at https://golang.org/dl/.
You should check the latest version, adjust the paths to your needs
and add the exports to your
.profile as described when
clicking on the download link.
This is an example of installing and setting up Golang on a Linux system:
sudo tar -C /usr/local -xzf go1.7.4.linux-amd64.tar.gz
mkdir $HOME/golang && export GOPATH=$HOME/golang && cd $HOME/golang
After these steps, verify that Golang is correctly installed:
go version go1.7.4 linux/amd64
The Mender Artifact utility is available as open source in the Mender artifact repository on GitHub.
You can download and install it with the following commands:
go get github.com/mendersoftware/mender-artifact
go get ./...
You can now run the
mender-artifact utility in
$GOPATH/bin/mender-artifact, and make sure it works
mender-artifact version 0.1
For convenience, we can also make sure the
mender-artifact utility is in PATH: