How mendersoftware/mender works
Purpose and deliverables
This is the C++ Mender device client for secure OTA updates on embedded Linux. It builds two operational binaries: mender-update for managed/standalone deployments and mender-auth/mender-authd for device authentication and credential services. Top-level build and installation wiring is in CMakeLists.txt, main.cmake, and src/CMakeLists.txt.
Process entry points and operating modes
src/mender-update/main.cpp dispatches CLI, daemon, and standalone update paths. Managed mode runs a persistent daemon that polls/communicates with the Mender backend; standalone mode applies a locally supplied artifact without a server. src/mender-auth/main.cpp starts authentication functions and its IPC-facing service. systemd integration deploys them as separate services via support/mender-updated.service and support/mender-authd.service.
Update orchestration state machine
The update daemon owns the durable deployment lifecycle—synchronization, download, installation, reboot/commit, and failure handling—through explicit states and events. Key boundaries are src/mender-update/daemon/state_machine/state_machine.cpp, src/mender-update/daemon/states.cpp, and src/mender-update/deployments/deployments.cpp. State-script execution lets device integrators hook lifecycle transitions, while bootloader/A/B partition integration outside this repository provides rollback semantics.
Artifact validation and execution pipeline
Artifacts are parsed as Mender Artifact v3 archives: read TAR content, parse header/manifest/payload metadata, verify manifest signatures/checksums, then select and execute payload handling. The core is src/artifact/artifact.cpp, src/artifact/v3/manifest/manifest.cpp, and src/artifact/v3/payload/payload.cpp. Archive and hashing adapters use libarchive and OpenSSL (src/artifact/tar/platform/libarchive/tar.cpp, src/artifact/sha/platform/openssl/sha.cpp). Artifact scripts are executed through src/artifact/v3/scripts/executor.cpp.
Update Modules and device-side application
Non-rootfs artifact payloads are delegated to externally installed Update Modules, invoked with the v3 module protocol and filesystem operations. This adapter boundary is src/mender-update/update_module/v3/update_module.cpp, src/mender-update/update_module/v3/update_module_download.cpp, and src/mender-update/update_module/v3/platform/c++17/update_module_call.cpp. Bundled reference modules live under support/modules/, including support/modules/rootfs-image and support/modules/directory.
Authentication, transport, and server boundary
The client communicates with Mender backend APIs over HTTP(S), authenticating devices and retaining credentials/keys. Shared API client interfaces are in src/api/client.cpp and src/api/auth/auth.cpp; auth service behavior is in src/mender-auth/api/auth/auth.cpp. mender-auth exposes local authentication/HTTP forwarding over IPC, optionally D-Bus, through src/mender-auth/ipc/server.cpp, src/mender-auth/http_forwarder/http_forwarder.cpp, and src/api/auth/platform/dbus/auth.cpp. The backend, artifact storage, and cloud integrations are external services, not implemented here.
Shared runtime and persistence
src/common/ supplies platform-isolated facilities used by both executables: asynchronous Boost event/HTTP transport, OpenSSL crypto, local key-value persistence, subprocess execution, filesystem access, structured logging, and optional D-Bus. Architecturally central implementations include src/common/http/platform/beast/http.cpp, src/common/key_value_database/platform/lmdb/lmdb.cpp, and src/common/platform/dbus/asio_libdbus/dbus.cpp. Configuration, identity, and inventory feed enrollment and deployment requests through src/client_shared/conf/conf.cpp, src/client_shared/identity_parser/identity_parser.cpp, and src/mender-update/inventory.cpp.
Build targets and portability
CMake builds a native C++ client with Boost, libarchive, LMDB, OpenSSL, D-Bus, and systemd dependencies. Platform seams permit POSIX/Linux and experimental QNX variants; examples include cmake/qnx.cmake, src/common/io/platform/posix/io.cpp, and cmake/aarch64.cmake. QNX can disable D-Bus and LMDB and embed authentication, preserving the update core behind these runtime substitutions.
Main entry points: state_machine.cpp Update state machine · auth.cpp Authentication API · main.cpp mender-update · deployments.cpp Deployment coordination
Components 20
Build & deployment
- CMake build · Builds native binaries and selects platform dependencies.
CMakeLists.txt - systemd services · Runs update and authentication daemons separately.
support/mender-updated.service
Update client
- mender-update · Dispatches managed daemon, CLI, and standalone update modes.
src/mender-update/main.cpp - Update state machine · Owns durable synchronization, install, reboot, commit, and failure transitions.
src/mender-update/daemon/state_machine/state_machine.cpp - Deployment coordination
src/mender-update/deployments/deployments.cpp - Identity & inventory · Feeds enrollment and deployment requests.
src/mender-update/inventory.cpp - Update Module adapter · Delegates non-rootfs payload operations to installed modules.
src/mender-update/update_module/v3/update_module.cpp
Artifact pipeline
- Artifact v3 parser · Parses artifact header, manifest, and payload metadata.
src/artifact/artifact.cpp - Manifest verification
src/artifact/v3/manifest/manifest.cpp - Payload & scripts · Selects payload handlers and runs artifact lifecycle scripts.
src/artifact/v3/payload/payload.cpp
Authentication service
- mender-auth / authd · Starts device authentication and local credential services.
src/mender-auth/main.cpp - Authentication API
src/mender-auth/api/auth/auth.cpp - IPC & HTTP forwarding · Exposes authentication and HTTP forwarding to local clients.
src/mender-auth/ipc/server.cpp
Shared runtime
- Shared API client · Provides common backend and authentication client interfaces.
src/api/client.cpp - Async HTTP transport
src/common/http/platform/beast/http.cpp - Credential persistence
src/common/key_value_database/platform/lmdb/lmdb.cpp - Platform seams · Substitutes runtime facilities such as D-Bus and LMDB by target platform.
cmake/qnx.cmake
External boundaries
- Mender backend · Provides device authentication, deployments, and artifact storage.
- Installed Update Modules · Reference rootfs-image and directory modules are bundled for installation.
- Bootloader / A-B partitions · Performs platform-specific reboot and rollback semantics.
Connections 22
- CMake build → mender-update: builds
- CMake build → mender-auth / authd: builds
- systemd services → mender-update: runs
- systemd services → mender-auth / authd: runs
- mender-update → Update state machine: managed mode
- Update state machine → Deployment coordination: synchronizes
- Identity & inventory → Deployment coordination: supplies metadata
- Deployment coordination → Shared API client: uses
- Update state machine → Artifact v3 parser: downloads and validates
- Artifact v3 parser → Manifest verification: verifies
- Manifest verification → Payload & scripts: authorizes payload
- Payload & scripts → Update Module adapter: delegates non-rootfs
- Update Module adapter → Installed Update Modules: invokes
- Update state machine → Bootloader / A-B partitions: reboot / commit
- mender-auth / authd → Authentication API: hosts
- Authentication API → IPC & HTTP forwarding: serves locally
- Authentication API → Credential persistence: stores credentials
- Authentication API → Shared API client: authenticates through
- Shared API client → Async HTTP transport: uses
- Async HTTP transport → Mender backend: HTTPS
- Platform seams → Async HTTP transport: selects runtime variants
- Platform seams → Credential persistence: may replace or disable