rmm2/docs/BACKEND.md

# Backend — Installation & Konfiguration

Das RMM-Backend laeuft auf Linux (Debian 12+) und stellt die REST API, den WebSocket Hub und den Tunnel Manager bereit.

## Komponenten

- **REST API**: Agent-Registrierung, Heartbeat, Systemdaten, Tunnel-Management
- **WebSocket Hub**: Verwaltet Agent-Verbindungen, routet Commands und Binary-Messages
- **Tunnel Manager**: Proxy-Listener, Session-Tracking, Ready-Handshake
- **PostgreSQL + TimescaleDB**: Relationale Daten + Time-Series Metriken

## 1. PostgreSQL + TimescaleDB installieren

```bash
# Debian 12+ (Bookworm/Trixie)
apt install -y postgresql postgresql-client

# TimescaleDB Repository hinzufuegen
echo "deb https://packagecloud.io/timescale/timescaledb/debian/ bookworm main" \
  > /etc/apt/sources.list.d/timescaledb.list
curl -L https://packagecloud.io/timescale/timescaledb/gpgkey | gpg --dearmor \
  > /etc/apt/trusted.gpg.d/timescaledb.gpg
apt update

# TimescaleDB passend zur PG-Version installieren (z.B. PG 17)
apt install -y timescaledb-2-postgresql-17

# TimescaleDB in postgresql.conf aktivieren
echo "shared_preload_libraries = 'timescaledb'" >> /etc/postgresql/17/main/conf.d/timescaledb.conf
systemctl restart postgresql
```

## 2. Datenbank und User anlegen

```bash
sudo -u postgres psql <<EOF
CREATE USER rmm WITH PASSWORD 'SICHERES_PASSWORT';
CREATE DATABASE rmm OWNER rmm;
\c rmm
CREATE EXTENSION IF NOT EXISTS timescaledb;
GRANT ALL ON SCHEMA public TO rmm;
EOF
```

Verbindung testen:

```bash
psql -h 127.0.0.1 -U rmm -d rmm -c "SELECT default_version FROM pg_available_extensions WHERE name='timescaledb';"
```

## 3. Build

```bash
make all       # Backend (linux/amd64) + Agent (freebsd/amd64)
make backend   # Nur Backend
make agent     # Nur Agent
```

Binaries landen in `build/`. Kein CGO — reine Go-Compilation.

## 4. TLS-Zertifikate generieren

```bash
make certs
```

Oder manuell:

```bash
mkdir -p certs
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
  -keyout certs/server.key -out certs/server.crt \
  -days 3650 -nodes \
  -subj "/CN=rmm-backend/O=RMM" \
  -addext "subjectAltName=IP:BACKEND_IP,IP:127.0.0.1,DNS:localhost"
```

## 5. Backend konfigurieren (`config.yaml`)

```yaml
listen_addr: ":8443"
tls_cert: "certs/server.crt"
tls_key: "certs/server.key"
api_keys:
  - "SICHERER_API_KEY"

database:
  host: "127.0.0.1"
  port: 5432
  user: "rmm"
  password: "SICHERES_PASSWORT"
  dbname: "rmm"
  sslmode: "disable"        # "require" wenn PG ueber Netz
```

Alternativ per Environment-Variablen: `RMM_LISTEN_ADDR`, `RMM_TLS_CERT`, `RMM_TLS_KEY`, `RMM_DB_HOST`, `RMM_DB_PASSWORD`.

## 6. Backend deployen und starten

```bash
# Verzeichnis anlegen
ssh root@BACKEND_IP "mkdir -p /opt/rmm/certs"

# Binary + Config + Certs kopieren
scp build/rmm-backend root@BACKEND_IP:/opt/rmm/rmm-backend
scp config.yaml root@BACKEND_IP:/opt/rmm/config.yaml
scp certs/server.* root@BACKEND_IP:/opt/rmm/certs/

# Systemd-Service einrichten
ssh root@BACKEND_IP 'cat > /etc/systemd/system/rmm-backend.service << EOF
[Unit]
Description=RMM Backend
After=network.target postgresql.service

[Service]
Type=simple
WorkingDirectory=/opt/rmm
ExecStart=/opt/rmm/rmm-backend /opt/rmm/config.yaml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF'

ssh root@BACKEND_IP "systemctl daemon-reload && systemctl enable rmm-backend && systemctl start rmm-backend"
```

Oder per Makefile: `make deploy-backend`

## 7. Starten und verifizieren

```bash
# Status pruefen
systemctl status rmm-backend

# Log pruefen
journalctl -u rmm-backend -f

# API testen
curl -sk -H "X-API-Key: DEIN_API_KEY" https://BACKEND_IP:8443/api/v1/agents
```

Beim ersten Start:
- Tabellen werden automatisch angelegt
- Hypertable `metrics` wird erstellt (TimescaleDB)
- Retention Policy (90 Tage) und Compression Policy (nach 7 Tagen) werden automatisch gesetzt
- Default-Admin `admin` / `Start!123` wird erstellt

## Datenbank-Schema (automatisch)

| Tabelle | Typ | Beschreibung |
|---------|-----|-------------|
| `agents` | Relational | Agent-Registry (ID, Name, Hostname, IP, Version, Heartbeat, customer_id, update_requested) |
| `system_data` | Relational | Letzte Systemdaten pro Agent (JSONB) |
| `config_backups` | Relational | OPNsense Config-Backups (dedupliziert per SHA256) |
| `agent_events` | Relational | Online/Offline/Connected Events |
| `customers` | Relational | Kundenstammdaten (Nummer, Name) |
| `users` | Relational | Benutzer (Username, bcrypt-Hash, Display-Name) |
| `agent_firmware` | Relational | Agent-Binaries pro Plattform+Version (BYTEA, SHA256) |
| `metrics` | TimescaleDB Hypertable | Time-Series Metriken (CPU, RAM, Disk, Network, Gateway) |

### TimescaleDB Policies

- **Retention**: Rohdaten werden nach 90 Tagen automatisch geloescht
- **Compression**: Daten aelter als 7 Tage werden komprimiert (segmentby: agent_id+metric)

### DB-Funktionen

- `GetAgentByName`: Sucht Agent nach Name — verwendet fuer Pre-Registration Matching bei Agent-Registrierung

## Hinweise

- Backend braucht **kein root** — laeuft als normaler User auf Port 8443
- Beim Deploy: **alte Prozesse killen** bevor neuer startet (sonst "bind: address already in use")
- FreeBSD csh hat kein `$()` — Agent verwendet `/bin/sh -c` fuer Commands