cynfo3000 a51d1bb02f docs: Linux-Agent vollständige Command-Referenz (exec, reboot, tunnel, pty_start/stop/resize, agent_update, OTA-Prozess)

2026-03-07 00:43:33 +01:00

7.0 KiB

Raw Blame History

RMM Agent Linux

Linux/Proxmox Agent für das RMM-System. Sammelt Systemdaten und ermöglicht Remote-Management über WebSocket.

Features

System-Monitoring: CPU, Memory, Disk, Network, Services, Updates
Proxmox-Integration: VMs, Container, Storage, Cluster, Subscription, ZFS Pools
Remote-Commands: exec (beliebige Befehle), reboot
Agent-Updates: Automatische Binary-Updates über WebSocket
Cross-Platform: Funktioniert auf normalen Linux-Systemen und Proxmox VE

Unterstützte Systeme

Debian/Ubuntu (mit apt)
Proxmox VE
Andere Linux-Distributionen mit systemd

Installation

Repo auf dem Zielsystem klonen und Binary bauen:

apt install -y git golang-go
git clone https://git.cynfo.net/christian/rmm2.git /opt/rmm
cd /opt/rmm
make agent-linux VERSION=1.0.0

Installationsskript ausführen:

cd /opt/rmm/agent-linux
chmod +x install.sh
./install.sh

Konfiguration anpassen:
```
nano /etc/rmm/config.yaml
```

Service starten:

systemctl start rmm-agent-linux
systemctl status rmm-agent-linux
journalctl -u rmm-agent-linux -f

Konfiguration

backend_url: "https://your-rmm-backend.example.com"
api_key: "your-api-key-here"
interval_seconds: 60
agent_name: "linux-server-01"
insecure: true  # Für Entwicklung, false für Produktion

CLI-Flags

rmm-agent-linux [flags]

Flags:
  -config string
        Path zur Konfigurationsdatei (default "/etc/rmm/config.yaml")
  -insecure
        TLS-Zertifikatpruefung deaktivieren
  -version
        Version anzeigen

Proxmox-Features

Wenn auf Proxmox VE installiert, sammelt der Agent zusätzlich:

VMs/Container: Status, Ressourcen-Usage, Uptime
Storage: Verfügbarer Platz, Typen (ZFS, LVM, NFS, etc.)
Cluster: Node-Status, Quorum
Subscription: Lizenz-Status
ZFS: Pool-Health, Scrub-Status, Größen

Systemd Service

Service Name: rmm-agent-linux
Config: /etc/rmm/config.yaml
Agent ID: /etc/rmm/agent_id (automatisch generiert)
Logs: journalctl -u rmm-agent-linux

Remote-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.

Ü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):

POST /api/v1/agents/{id}/exec
Content-Type: application/json
X-API-Key: ...

{
  "command": "df -h",
  "timeout": 30
}

Response:

{
  "status": "ok",
  "data": {
    "output": "Filesystem      Size  Used Avail Use% Mounted on\n..."
  }
}

Fehler-Response:

{
  "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

{
  "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:

{
  "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:

{
  "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):

{
  "session_id": "pty-abc123",
  "cols": 180,
  "rows": 40
}

pty_stop (beim Schliessen des Terminal-Modals):

{
  "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.

{
  "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:

GET /api/v1/firmware?platform=linux → aktuelle Version + Hash
Hash des lokalen Binaries prüfen — wenn gleich: nichts tun
GET /api/v1/agents/{id} → update_requested Flag prüfen
Falls update_requested=true: Binary herunterladen, Hash verifizieren, ersetzen, neu starten
Bei Fehler: Rollback auf altes Binary (.old-Backup)

Service-Status prüfen:

systemctl status rmm-updater
journalctl -u rmm-updater -f

Entwicklung

# Dependencies installieren
cd agent-linux
go mod tidy

# Entwicklung
go run . -config config.yaml.example

# Cross-compile für Linux
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o rmm-agent-linux .

# Mit Version
go build -ldflags "-X main.Version=1.0.0" -o rmm-agent-linux .

Unterschiede zum FreeBSD/OPNsense Agent

OS-Detection: Linux-spezifische /proc-Dateien und systemd
Package-Updates: apt list --upgradable statt pkg
Services: systemctl statt service
Proxmox: Zusätzliche pvesh-Integration für VMs/Container
Keine OPNsense-Features: Kein WireGuard, DHCP, Certificates, etc.

Troubleshooting

# Service Status
systemctl status rmm-agent-linux

# Live-Logs
journalctl -u rmm-agent-linux -f

# Config testen
rmm-agent-linux -config /etc/rmm/config.yaml -version

# Manuelle Registrierung testen
rm /etc/rmm/agent_id
systemctl restart rmm-agent-linux

7.0 KiB Raw Blame History