From a51d1bb02ffdcb9f84876983b91e14abd82d6fd6 Mon Sep 17 00:00:00 2001
From: cynfo3000 <cynfo3000@cynfo.net>
Date: Sat, 7 Mar 2026 00:43:33 +0100
Subject: [PATCH] =?UTF-8?q?docs:=20Linux-Agent=20vollst=C3=A4ndige=20Comma?=
 =?UTF-8?q?nd-Referenz=20(exec,=20reboot,=20tunnel,=20pty=5Fstart/stop/res?=
 =?UTF-8?q?ize,=20agent=5Fupdate,=20OTA-Prozess)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 agent-linux/README.md | 161 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 157 insertions(+), 4 deletions(-)

diff --git a/agent-linux/README.md b/agent-linux/README.md
index dd15e76..83d5d43 100644
--- a/agent-linux/README.md
+++ b/agent-linux/README.md
@@ -88,11 +88,164 @@ Wenn auf Proxmox VE installiert, sammelt der Agent zusätzlich:
 
 ## Remote-Commands
 
-Über WebSocket unterstützte Commands:
+Alle Commands werden über die bestehende WebSocket-Verbindung als JSON-Message gesendet.
+Der Backend-Endpoint ist `POST /api/v1/agents/{id}/exec` für direkte Ausführung.
 
-- **exec**: Beliebige Shell-Befehle ausführen
-- **reboot**: System-Neustart
-- **agent_update**: Agent-Binary aktualisieren
+### Übersicht
+
+| Command | Beschreibung | Parameter |
+|---------|-------------|-----------|
+| `exec` | Shell-Befehl ausführen (blockierend, gibt Output zurück) | `command`, `timeout` |
+| `reboot` | System-Neustart | `delay` (Sekunden, default 5) |
+| `tunnel_connect` | TCP-Tunnel zu lokalem Dienst öffnen | `session_id`, `tunnel_id`, `target_host`, `target_port` |
+| `tunnel_disconnect` | Tunnel-Session schliessen | `session_id` |
+| `pty_start` | Interaktive PTY-Shell starten (Web Terminal) | `session_id`, `cols`, `rows` |
+| `pty_stop` | PTY-Session beenden | `session_id` |
+| `pty_resize` | PTY-Fenstergrösse ändern | `session_id`, `cols`, `rows` |
+| `agent_update` | Agent-Binary direkt ersetzen (Legacy, normalerweise über Updater) | `binary` (Base64), `hash`, `version` |
+
+---
+
+### `exec` — Shell-Befehl ausführen
+
+Führt einen beliebigen Shell-Befehl aus und gibt stdout+stderr zurück. Blockiert bis der Befehl abgeschlossen ist oder der Timeout erreicht wird.
+
+**Request (via Backend):**
+```bash
+POST /api/v1/agents/{id}/exec
+Content-Type: application/json
+X-API-Key: ...
+
+{
+  "command": "df -h",
+  "timeout": 30
+}
+```
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "data": {
+    "output": "Filesystem      Size  Used Avail Use% Mounted on\n..."
+  }
+}
+```
+
+**Fehler-Response:**
+```json
+{
+  "status": "error",
+  "error": "exit status 1",
+  "data": { "output": "..." }
+}
+```
+
+**Timeout:** Default 30s, max sinnvoll ~300s. Bei Überschreitung: `Timeout: Agent hat nicht rechtzeitig geantwortet`.
+
+---
+
+### `reboot` — System-Neustart
+
+```json
+{
+  "command": "reboot",
+  "params": { "delay": 5 }
+}
+```
+
+Führt nach `delay` Sekunden `/sbin/shutdown -r now` aus. Response kommt sofort.
+
+---
+
+### `tunnel_connect` / `tunnel_disconnect` — TCP-Tunnel
+
+Wird vom Backend automatisch verwaltet über `POST /api/v1/agents/{id}/tunnel`. Nicht direkt aufrufen.
+
+**Intern verwendete Parameter:**
+```json
+{
+  "session_id": "abc123",
+  "tunnel_id":  "def456",
+  "target_host": "127.0.0.1",
+  "target_port": 22
+}
+```
+
+Typische Verwendung über die Frontend-Buttons:
+- `127.0.0.1:22` → SSH-Tunnel
+- `127.0.0.1:8006` → Proxmox WebGUI
+- Beliebiger Host:Port im Netzwerk des Agents
+
+---
+
+### `pty_start` / `pty_stop` / `pty_resize` — Web Terminal (PTY)
+
+Öffnet eine interaktive Bash-Shell im Browser. Wird vom Backend über den Endpoint  
+`GET /api/v1/agents/{id}/terminal` (WebSocket-Upgrade) gesteuert.
+
+**`pty_start`:**
+```json
+{
+  "session_id": "pty-abc123",
+  "cols": 220,
+  "rows": 50
+}
+```
+
+Shell: `/bin/bash -l`  
+PTY-Output wird als Binary-Messages mit `session_id`-Prefix an das Backend gestreamt.  
+Browser-Eingaben laufen als Binary-Messages zurück zum Agent.
+
+**`pty_resize`** (wird bei Fenstergrößenänderung gesendet):
+```json
+{
+  "session_id": "pty-abc123",
+  "cols": 180,
+  "rows": 40
+}
+```
+
+**`pty_stop`** (beim Schliessen des Terminal-Modals):
+```json
+{
+  "session_id": "pty-abc123"
+}
+```
+
+---
+
+### `agent_update` — Binary-Update (Legacy)
+
+Normalerweise läuft Updates über den `rmm-updater`-Dienst (OTA, automatisch). Dieser Command ersetzt das Binary direkt via WebSocket.
+
+```json
+{
+  "binary": "<base64-kodiertes Binary>",
+  "hash":   "sha256-hash",
+  "version": "1.1.0"
+}
+```
+
+Nach erfolgreichem Schreiben wird `systemctl restart rmm-agent` ausgeführt.
+
+---
+
+## OTA-Update-Prozess (rmm-updater)
+
+Der `rmm-updater`-Dienst läuft parallel zum Agent und prüft alle 60 Sekunden:
+
+1. `GET /api/v1/firmware?platform=linux` → aktuelle Version + Hash
+2. Hash des lokalen Binaries prüfen — wenn gleich: nichts tun
+3. `GET /api/v1/agents/{id}` → `update_requested` Flag prüfen
+4. Falls `update_requested=true`: Binary herunterladen, Hash verifizieren, ersetzen, neu starten
+5. Bei Fehler: Rollback auf altes Binary (`.old`-Backup)
+
+**Service-Status prüfen:**
+```bash
+systemctl status rmm-updater
+journalctl -u rmm-updater -f
+```
 
 ## Entwicklung