Concepts¶
The handful of words the dashboard and these docs use, each in one place. 
Device¶
A Linux machine with the KinuxOTA agent installed and enrolled. Each device belongs to one account and has its own API key, shown once when you add the device.
| Status | Meaning |
|---|---|
| NOT CONNECTED | The device was added but its agent has never connected. |
| ONLINE | The agent called in during the last 5 minutes. |
| OFFLINE | No call for 5 minutes or more (checked every minute). |
The agent reports every 60 seconds. With each report the dashboard learns the device's Platform
(for example Ubuntu 22.04 · amd64) and its Agent Version.
During the pilot an account can have up to 3 devices.
Agent¶
The program kinuxota on the device, from the Debian package kinuxota. It runs as the systemd
service kinuxota, as root, because it runs the commands, scripts and package operations you send.
It keeps a live connection to the service (MQTT over TLS) that tells it when there is work, and
fetches the work and sends results over HTTPS. When the live connection is down it polls instead.
Results it cannot send yet are kept on disk (the outbox) and sent later. See
The agent.
Command¶
One shell command run on one device, as root, for example df -h. You send it with Send Command
on the device page. A command has an optional timeout (default 1 hour, at most 24 hours); the device
stops a command that runs longer and reports it as failed.
| Status | Meaning |
|---|---|
| PENDING / SENT | Waiting for the device to pick it up. A command not picked up within 7 days fails. |
| RUNNING | The device runs it; the output streams live. |
| COMPLETED | It finished; the exit code is shown (exit 0 and so on). |
| FAILED | It failed, timed out, or the device did not report. |
| CANCELLED | You cancelled it. |
The dashboard keeps up to 10 MB of output per command; beyond that it shows the start and the last 64 KB.
The dashboard also sends built-in commands for its own features, and they show in Command Logs:
get-health-status (Ping), get-packages, install-packages, remove-packages (Package Manager)
and update-client (Update agent).
Script¶
A folder of files in your library: an entry file that runs (for example run.sh) and any other
files it needs, such as configuration files or .deb packages. A script can have parameters,
which the run passes to it as environment variables. You run a script on one device or up to 100 at
once; each run keeps its output per device. See the Scripts guide.
Run¶
One start of a script on a set of devices, numbered #1, #2 and so on. The Runs page lists
them. A run keeps each device's status, exit code and output, also after the script is deleted.
Packages¶
The device's apt packages. The Package Manager tab lists them and installs, updates or removes them through apt on the device (up to 10 packages per install).
Health¶
Ping Device asks the device for its health now: CPU, memory, disk (/), uptime and the network
state, with an overall Healthy, Degraded or Unhealthy. The dashboard shows the answer;
it does not store a history.
Agent update¶
The agent updates through apt, from the KinuxOTA repository: Update agent on the device page, or
sudo kinuxota update on the device. See Update the agent.