# KinuxOTA Client

The KinuxOTA client is a small agent that connects a Linux device to your KinuxOTA dashboard.
It is a single program, `kinuxota`, installed as a standard Debian package with a systemd service.

## Requirements

- Ubuntu 22.04 or 24.04 (other Debian-based distributions with the same libraries usually work)
- amd64 (x86-64). ARM builds (Raspberry Pi and similar) are planned.
- Outbound internet access to `back.kinuxota.com` (HTTPS) and `mqtt.kinuxota.com` (port 27202, TLS)
- `sudo` rights for installation

## Install

1. In the dashboard, open **Devices → Add Device** and create the device. Copy its **API key**;
   it is shown only once. The dialog also shows the commands below with the key filled in.
2. On the device:

```bash
curl -fsSLO https://github.com/yaswanthsk04/kinuxota_client/releases/latest/download/kinuxota_amd64.deb
sudo apt install ./kinuxota_amd64.deb
sudo kinuxota enroll --key <API_KEY>
```

`enroll` checks the key with the server, saves the configuration and starts the agent. The
device appears as **Online** in the dashboard within a few seconds.

To verify the download first, get `SHA256SUMS` from the same release and run
`sha256sum -c SHA256SUMS --ignore-missing`.

## Commands

| Command | What it does |
|---|---|
| `sudo kinuxota enroll --key <API_KEY>` | Connect this device to your account (again) and start the agent |
| `kinuxota status` | Version, service state and connection to the dashboard (`sudo` shows more) |
| `kinuxota health` | CPU, memory, disk and uptime of this device |
| `sudo kinuxota logs [-f]` | Agent logs (`-f` to follow) |
| `sudo kinuxota update` | Install the latest release (`--version X.Y.Z` for a specific one) |
| `kinuxota version` | Installed version |
| `kinuxota help` | All commands |

The agent runs as the systemd service `kinuxota`:

```bash
sudo systemctl status kinuxota
sudo systemctl restart kinuxota
```

## Update

Either run `sudo kinuxota update` on the device, or install a newer `.deb` with `apt` as above.
Updates keep the device's enrollment.

## Uninstall

```bash
sudo apt remove kinuxota          # remove the program, keep the enrollment
sudo apt purge kinuxota           # remove everything, including the API key
```

## Files

| Path | Contents |
|---|---|
| `/usr/bin/kinuxota` | The program |
| `/etc/kinuxota/config.json` | Enrollment: API key, server addresses (readable by root only) |
| `/usr/share/kinuxota/ca.crt` | Certificate used to verify the KinuxOTA MQTT broker |
| `/etc/kinuxota/ca.crt` | Optional override of that certificate (self-hosted brokers) |
| `/lib/systemd/system/kinuxota.service` | The service definition |
| systemd journal | Logs: `kinuxota logs` or `journalctl -u kinuxota` |

## Security

- All traffic to KinuxOTA is encrypted (HTTPS and MQTT over TLS). The client verifies the server
  certificates.
- Each device has its own API key and can only receive its own commands.
- The agent runs as root because it executes the commands, scripts and package operations you send
  from the dashboard. Only your account can send them.

## Troubleshooting

- **`kinuxota status` says "API key rejected"**: the device was deleted in the dashboard or the key
  is wrong. Create the device again and re-run `sudo kinuxota enroll --key <NEW_KEY>`.
- **"unreachable"**: check that the device can reach `https://back.kinuxota.com`
  (`curl -I https://back.kinuxota.com/api/health`) and that outbound port 27202 is allowed.
- **The device shows Offline**: run `sudo kinuxota logs -n 50` and look for `Connected to broker successfully`.