290 lines
7.0 KiB
Markdown
290 lines
7.0 KiB
Markdown
# 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
|
|
|
|
1. **Repo auf dem Zielsystem klonen und Binary bauen:**
|
|
```bash
|
|
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
|
|
```
|
|
|
|
2. **Installationsskript ausführen:**
|
|
```bash
|
|
cd /opt/rmm/agent-linux
|
|
chmod +x install.sh
|
|
./install.sh
|
|
```
|
|
|
|
3. **Konfiguration anpassen:**
|
|
```bash
|
|
nano /etc/rmm/config.yaml
|
|
```
|
|
|
|
4. **Service starten:**
|
|
```bash
|
|
systemctl start rmm-agent-linux
|
|
systemctl status rmm-agent-linux
|
|
journalctl -u rmm-agent-linux -f
|
|
```
|
|
|
|
## Konfiguration
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
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):**
|
|
```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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
``` |