Artifacts

A firmware artifact is the binary payload that a device downloads and applies during an OTA update. OTA-Pulse stores artifacts server-side and serves them to devices on demand. Before you can create a deployment, the firmware record must have an artifact attached.

Format

OTA-Pulse accepts only Mender artifacts — files with the .mender extension. A Mender artifact is a tar-based container that includes the raw firmware payload, metadata headers (artifact name, compatible device types), and optional state-script hooks. The server rejects uploads with any other extension.

If you have a raw firmware image (.img, .ext4, .bin) you need to wrap it first using the mender-artifact CLI tool:

mender-artifact write rootfs-image \
    -t <your-device-type> \
    -n release-v1.2.0 \
    -f firmware.ext4 \
    -o firmware-v1.2.0.mender

The server can also wrap a previously uploaded raw image for you via POST /firmware/{id}/create-artifact if the mender-artifact tool is installed on the server. Call GET /firmware/artifact-tool/status to check availability.

What happens on upload

When you call an upload endpoint:

1. The file streams to disk at /var/lib/soc-monitoring/storage/firmware/{org_id}/{version}.mender.
2. A SHA-256 checksum is computed while writing and stored on the firmware record.
3. If mender-artifact is available, the server extracts artifact_name and device_types from the artifact headers and updates the record.
4. Signature status is evaluated and stored as signed, unsigned, or invalid.

To inspect metadata without saving, use POST /firmware/preview-artifact.

Signing

Signing is optional by default (ARTIFACT_SIGNATURE_REQUIRED=false). When set to true, an unsigned or invalid signature status causes the upload to be rejected with 422.

Two algorithms are supported:

Algorithm	Details
RSA-4096	RSA 4096-bit key, PSS padding, SHA-256 hash
ECDSA-P384	NIST P-384 curve, SHA-384 hash

Generate a key pair via POST /signing-keys (the private key is returned once and never stored server-side). Sign the .mender file locally, then store the base64-encoded signature in the signature field before upload. On upload, the server tries each active org key: a match yields signed, no match yields invalid, no signature yields unsigned.

On the device, place the public keys in /etc/soc-monitoring/signing-keys/active/ and list them under ArtifactVerifyKeys in the agent config.

Delta updates

Delta updates are not currently supported. Every device receives the complete artifact regardless of its current firmware version. The min_version field on a firmware record can be used to skip devices running firmware that is too old, but no binary diff is computed.

Storage

Artifacts are stored at /var/lib/soc-monitoring/storage/firmware/{organization_id}/ on the server filesystem. There is no API-layer size limit; available disk is the ceiling.

The SHA-256 checksum is returned in the X-Checksum response header when the agent downloads an artifact, enabling end-to-end integrity verification independent of TLS.