Device Management¶

Note

All device management operations described in this section operate within the Open World environment. They cannot directly access or modify Bunker OS. For accessing Bunker OS telemetry and events, see the preview services mentioned in Fleet Management Overview.

Overview¶

Beyond OTA updates, the RDFM Linux Device Client (rdfm-client) running in Open World exposes a set of runtime management capabilities that allow operators to interact with the Open World environment of deployed devices without requiring physical access or a pre-existing SSH configuration. These capabilities include reverse shell, remote actions, file retrieval, and telemetry. All are mediated through the management WebSocket that rdfm-client maintains to the RDFM Management Server. The server never opens inbound connections to devices; all channels are initiated outbound by the device, making the full management feature set available even for devices behind NAT or restrictive firewalls.

Each capability is independently configurable and can be disabled entirely if not required for a given deployment. The client reports its active capabilities to the server via a CapabilityReport message immediately after the WebSocket connection is established; the server uses this report to determine which management operations it can offer for each device.

Device Lifecycle¶

Registration and Authorization¶

A device registers itself with the management server on the very first successful authentication request. The client sends a JSON payload containing its current metadata (device type, software version, and MAC address) along with its RSA public key and a cryptographic signature of the payload. The server validates the signature, stores the public key, and adds the device to its pending device registry.

Until an administrator explicitly authorises the device through the web frontend or REST API, it cannot interact with any other server endpoints. This two-step flow prevents unconfigured or unknown hardware from joining the fleet automatically. Once authorised, the server returns a short-lived application token that the client uses for all subsequent requests. The client handles token expiry transparently by reauthenticating when a 401 response is received.

Authentication is backed by the device’s RSA private key, which is generated on first boot and stored locally. The corresponding public key is submitted to the server during registration. Compromised devices can be excluded from the fleet by revoking their authorisation in the management console, which causes all subsequent authentication attempts from that MAC address to be rejected.

Device Metadata and Tags¶

Every update check request carries the device’s full metadata set as key/value pairs. The mandatory keys (rdfm.hardware.macaddr, rdfm.software.version, rdfm.hardware.devtype) drive the OTA resolution logic described in Ship OTA Updates. Additional arbitrary metadata can be included and is stored in the server’s database, making it queryable and filterable through the frontend.

Devices can also carry a set of free-form string tags defined in /var/lib/rdfm/tags.conf. Each line of the file is one tag. Tags are synchronised with the server during registration and can also be assigned through the /api/v2/devices/{id}/tag endpoint. They appear in the web frontend and can be used to filter and group devices by role, location, or any other operator-defined dimension.

# /var/lib/rdfm/tags.conf: one tag per line
production
factory-a
arm64

Reverse Shell¶

The reverse shell capability allows an operator to open an interactive terminal session in the Open World environment of a device directly from the RDFM web frontend or command-line tool, without requiring any pre-existing SSH server configuration. The session is streamed bidirectionally over a dedicated WebSocket endpoint established through the management server.

When a shell request is received, the rdfm-client daemon spawns the configured shell binary running in the Open World context and bridges its standard input and output to the WebSocket stream. The operator’s keystrokes are forwarded to the shell’s input; output is sent back in real time. Sessions are fully interactive and support terminal control sequences.

Shell sessions are transient. They exist only for the duration of the WebSocket connection. Closing the browser tab or the terminal window terminates the session cleanly. Crash recovery is not provided: if the device loses connectivity during an active session, the session is lost and the operator must reconnect.

Configuration¶

The reverse shell is enabled by default. The following configuration keys control its behaviour in /var/lib/rdfm/rdfm.conf:

ShellEnable (bool, default: true)

Set to false to disable reverse shell entirely. When disabled, the device does not advertise the shell capability and the server will not offer shell sessions for this device.

ShellPath (string, default: empty)

Path to the shell binary to spawn for each session. If not set, the client uses the value of the $SHELL environment variable. If neither is available, it falls back to a list of common shell paths (/usr/bin/bash, /usr/bin/sh).

ShellConcurrentMaxCount (int, default: 5)

Maximum number of concurrent active shell sessions. Further requests are rejected by the client until an existing session is closed.

Usage¶

To open a shell session from the RDFM command-line tool:

rdfm-mgmt devices shell <device-identifier>

The device identifier is the MAC address as shown in the web frontend or returned by the /api/v2/devices endpoint. The session opens in the current terminal and behaves as a standard interactive shell for the duration of the WebSocket connection.

Remote Actions¶

Actions are predefined command sets that an operator can trigger in the Open World environment of a device remotely from the management server. Unlike the open-ended reverse shell, actions execute only commands that have been explicitly registered in the device’s local action configuration file, limiting the remote execution surface to a known and auditable set of operations. Typical use cases include triggering a health check script, restarting an application service, clearing a cache directory, or collecting a diagnostic bundle.

Action requests are persistent: they are stored in a queue on the device’s local disk and fulfilled in FIFO order. If the device is offline when a request arrives, the server holds it and re-delivers it once the device reconnects and reports its capabilities. Similarly, action results are persisted locally and reported to the server as soon as connectivity is re-established. This makes actions reliable across power cycles and transient network interruptions.

The default queue capacity is 32 pending requests per queue (one for incoming requests, one for outgoing results). This is configurable via ActionQueueSize.

Actions Configuration¶

Actions are defined in /var/lib/rdfm/actions.conf as a JSON array. Each element describes one action with the following fields:

Id (string)

Unique identifier used in API execution requests. Must be unique across all actions on the device.

Name (string)

Human-readable name displayed in the web frontend.

Command ([]string)

The command to execute. The first element is the executable path; subsequent elements are its arguments.

Description (string)

Human-readable description of what the action does.

Timeout (float)

Maximum execution time in seconds. The command is forcibly terminated if it does not complete within this period.

[
    {
        "Id":          "collect-diagnostics",
        "Name":        "Collect Diagnostics",
        "Command":     ["/usr/local/bin/collect-diag.sh"],
        "Description": "Collects a diagnostic bundle and saves it to /tmp/diag.tar.gz",
        "Timeout":     30.0
    },
    {
        "Id":          "restart-app",
        "Name":        "Restart Application",
        "Command":     ["systemctl", "restart", "my-application"],
        "Description": "Restarts the main application service",
        "Timeout":     10.0
    }
]

Note

The actions.conf file grants the ability to execute arbitrary commands on the device. Its permissions must be set to -rw-r--r-- (owner read/write, group and world read-only) to prevent unprivileged modification.

Configuration Keys¶

ActionEnable (bool, default: true)

Set to false to disable action functionality entirely. When disabled, the device does not advertise the action capability.

ActionQueueSize (int, default: 32)

Maximum number of pending requests (and separately, pending results) that can be queued on disk at any time. Requests beyond this limit are rejected by the client.

Triggering Actions¶

Actions can be triggered from the web frontend by navigating to a device’s detail view and selecting the action from the available list, or programmatically via the REST API:

# List available actions on a device
GET /api/v2/devices/<mac_address>/action-list

# Execute an action
GET /api/v2/devices/<mac_address>/action-exec/<action_id>

The action-exec response immediately confirms whether the request was queued successfully. The actual execution result (exit code and captured output) is returned asynchronously and is available through the same endpoint or through the web frontend once the device reports it.

File Retrieval¶

The file retrieval capability allows operators to download files from a running device without requiring interactive shell access. The client transfers the requested file through the management server to an intermediate storage location (local filesystem or S3, depending on server configuration), from which the operator downloads it.

This is useful for retrieving log files, configuration snapshots, diagnostic bundles, or any other file that exists on the device filesystem. The operation is one-directional: file retrieval allows downloading from the device but not uploading to it.

Configuration Keys¶

FileSystemEnable (bool, default: true)

Set to false to disable file retrieval entirely. When disabled the device does not advertise this capability.

FileSystemBaseDir (string, default: /)

Restricts downloadable files to paths within this directory. Any request for a file outside the base directory is rejected by the client. Set this to a specific directory (for example /var/log) to limit the scope of what operators can retrieve.

Usage¶

To download a file from the RDFM command-line tool:

rdfm-mgmt devices download <device> <remote-file-path> <local-file-path>

For example, to download the system journal from a device:

rdfm-mgmt devices download 00:11:22:33:44:55 /var/log/syslog ./device-syslog.txt

Telemetry¶

The telemetry subsystem allows the client to periodically execute arbitrary scripts or binaries on the device and transmit their output to the management server. Each executable is called a logger. Loggers run at configurable intervals and their captured standard output is batched and forwarded to the server. This provides a lightweight, extensible mechanism for collecting system metrics, sensor readings, resource usage statistics, or any other observable data without requiring a dedicated monitoring agent.

Loggers are defined in /etc/rdfm/loggers.conf as a JSON array. The file must be readable by the rdfm-client process; its permissions must be set to -rw-r--r-- to prevent unprivileged modification.

Loggers Configuration¶

Each logger entry has the following fields:

name (string)

Unique name for the logger, used for identification in server-side records.

path (string)

Absolute path to the executable to run.

args ([]string)

List of arguments to pass to the executable.

tick (int)

Interval in milliseconds between successive executions. If a logger takes longer than tick to complete, it is forcibly terminated and the client records a timeout error for that cycle.

[
    {
        "name": "cpu-temperature",
        "path": "/usr/bin/cat",
        "args": ["/sys/class/thermal/thermal_zone0/temp"],
        "tick": 5000
    },
    {
        "name": "memory-usage",
        "path": "/usr/bin/free",
        "args": ["-m"],
        "tick": 10000
    },
    {
        "name": "disk-usage",
        "path": "/usr/bin/df",
        "args": ["-h", "/"],
        "tick": 60000
    }
]

Telemetry transmission is batched. The TelemetryBatchSize configuration key (default: 50) controls how many log entries are sent to the server in a single request. The TelemetryLogLevel key filters which internal rdfm-client log levels are also captured and forwarded alongside the logger output.

Telemetry is disabled by default. It must be explicitly enabled with TelemetryEnable: true in /var/lib/rdfm/rdfm.conf.

Client Configuration Reference¶

The client reads its configuration from two overlapping files. The base configuration at /etc/rdfm/rdfm.conf is written at image build time by the meta-rdfm Yocto layer and contains partition-level settings that are specific to the hardware. The overlay configuration at /var/lib/rdfm/rdfm.conf is applied on top and is intended for settings that may change at runtime or that are not known until device provisioning. Overlay values take precedence over base values for all shared keys.

Both files are JSON formatted. The most commonly customized overlay keys are:

ServerURL (string)

URL of the RDFM Management Server. This is typically set during device provisioning.

ServerCertificate (string)

Path to the CA certificate file used to verify the TLS connection to the server. Required when the server uses a self-signed or privately-issued certificate.

UpdatePollIntervalSeconds (int)

How often the client checks for available updates. Increase this value for large fleets to reduce server load.

RetryPollIntervalSeconds (int)

Maximum wait time between successive authentication retry attempts when the device is not yet authorised.

ReconnectRetryCount (int)

Number of HTTP reconnect attempts before the client gives up and waits for the next poll cycle.

ReconnectRetryTime (int)

Base retry interval in seconds for reconnection attempts.

HttpCacheEnabled (bool, default: true)

When enabled, the client caches downloaded packages to avoid re-downloading on retries.

TelemetryEnable (bool, default: false)

Enables the telemetry logger subsystem.

TelemetryBatchSize (int, default: 50)

Number of telemetry entries to batch per server transmission.

TelemetryLogLevel (string)

Minimum severity level of internal client logs to include in telemetry. Accepted values: trace, debug, info, warn, error, fatal, panic.

ActionEnable (bool, default: true)

Enables the remote action capability.

ActionQueueSize (int, default: 32)

Maximum queue depth for pending action requests and results.

ShellEnable (bool, default: true)

Enables the reverse shell capability.

ShellConcurrentMaxCount (int, default: 5)

Maximum number of concurrent active reverse shell sessions.

ShellPath (string)

Path to the shell binary. Falls back to $SHELL or common shell paths if unset.

FileSystemEnable (bool, default: true)

Enables the file retrieval capability.

FileSystemBaseDir (string, default: /)

Base directory that restricts which files can be retrieved remotely.

Next Steps¶