docs: Linux-Agent vollständige Command-Referenz (exec, reboot, tunnel, pty_start/stop/resize, agent_update, OTA-Prozess)
This commit is contained in:
cynfo3000
parent
879cf5cd28
commit
a51d1bb02f
@ -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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user