From d8bc99873f6cbfe06ba7142b26f6fecbe3ca9cc4 Mon Sep 17 00:00:00 2001 From: cynfo3000 Date: Sat, 28 Feb 2026 13:36:59 +0100 Subject: [PATCH] README: Vollstaendige Installationsanleitung Backend+Agent, alle SQLite-Referenzen durch PostgreSQL+TimescaleDB ersetzt --- README.md | 244 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 208 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 0f96a35..ff387bf 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,8 @@ Go-basierter Agent + Backend mit WebSocket-Kommunikation und Session-basierten T │ rmm-agent │ Heartbeat │ REST API │ │ - Collectors │ WebSocket │ WebSocket Hub │ │ - WS Client │ Binary Msgs │ Tunnel Mgr │ -│ - Tunnel Mgr │ │ SQLite DB │ +│ - Tunnel Mgr │ │ PostgreSQL + │ +│ │ │ TimescaleDB │ └────────────────┘ └────────────────┘ ``` @@ -87,9 +88,56 @@ Client ──► Backend:ProxyPort ──► WebSocket (Binary) ──► Agent - **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 -- **SQLite DB**: Persistente Agent- und Systemdaten +- **PostgreSQL + TimescaleDB**: Relationale Daten + Time-Series Metriken -## Build +## Voraussetzungen + +- **Build-System**: Go 1.24+ (Cross-Compilation, kein CGO) +- **Backend-Server**: Linux (Debian 12+), PostgreSQL 17+, TimescaleDB 2.x +- **Agent-Ziel**: OPNsense / FreeBSD (amd64) + +## Installation (Backend) + +### 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 < /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 `agents`, `system_data`, `config_backups`, `agent_events` werden automatisch angelegt +- Hypertable `metrics` wird erstellt (TimescaleDB) +- Retention Policy (90 Tage) und Compression Policy (nach 7 Tagen) werden automatisch gesetzt + +### 8. Datenbank-Schema (automatisch) + +Das Backend erstellt folgendes Schema bei erstem Start: + +| Tabelle | Typ | Beschreibung | +|---------|-----|-------------| +| `agents` | Relational | Agent-Registry (ID, Name, Hostname, IP, Version, Heartbeat) | +| `system_data` | Relational | Letzte Systemdaten pro Agent (JSONB) | +| `config_backups` | Relational | OPNsense Config-Backups (dedupliziert per SHA256) | +| `agent_events` | Relational | Online/Offline/Connected Events | +| `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) + +## Installation (Agent / OPNsense) + +### 1. Agent bauen + +```bash +make agent # Erzeugt build/rmm-agent (freebsd/amd64) +``` + +### 2. Agent konfigurieren (`agent/config.yaml`) ```yaml -backend_url: "https://backend-ip:8443" -api_key: "dein-api-key-hier" +backend_url: "https://BACKEND_IP:8443" +api_key: "SICHERER_API_KEY" interval_seconds: 60 agent_name: "opnsense-fw01" -insecure: true # Self-signed Certs akzeptieren +insecure: true # Self-signed Certs akzeptieren (false bei CA-Certs) ``` -## Deployment - -### Backend +### 3. Agent deployen ```bash -# Build + Copy -make backend -scp build/rmm-backend user@backend:/pfad/rmm-backend - -# Starten (als normaler User, kein root noetig) -cd /pfad && nohup ./rmm-backend config.yaml > rmm-backend.log 2>&1 & -``` - -### Agent (OPNsense/FreeBSD) - -```bash -# Build + Copy -make agent -scp build/rmm-agent root@opnsense:/usr/local/rmm/rmm-agent +# Verzeichnis anlegen + Binary + Config kopieren +ssh root@OPNSENSE "mkdir -p /usr/local/rmm" +scp build/rmm-agent root@OPNSENSE:/usr/local/rmm/rmm-agent +scp agent/config.yaml root@OPNSENSE:/usr/local/rmm/config.yaml # Starten via FreeBSD daemon -daemon -f -p /var/run/rmm-agent.pid -o /usr/local/rmm/rmm-agent.log \ - /usr/local/rmm/rmm-agent --config /usr/local/rmm/config.yaml --insecure +ssh root@OPNSENSE 'daemon -f -p /var/run/rmm-agent.pid -o /usr/local/rmm/rmm-agent.log \ + /usr/local/rmm/rmm-agent --config /usr/local/rmm/config.yaml --insecure' ``` -**Wichtig**: Agent-ID wird persistent in `/usr/local/rmm/agent_id` gespeichert. +Oder per Makefile: `make deploy-agent` + +### 4. Autostart einrichten (rc.d) + +```bash +ssh root@OPNSENSE 'cat > /usr/local/etc/rc.d/rmm_agent << RCEOF +#!/bin/sh +# PROVIDE: rmm_agent +# REQUIRE: NETWORKING +# KEYWORD: shutdown + +. /etc/rc.subr + +name="rmm_agent" +rcvar="rmm_agent_enable" +pidfile="/var/run/${name}.pid" +command="/usr/local/rmm/rmm-agent" +command_args="--config /usr/local/rmm/config.yaml --insecure &" + +load_rc_config $name +run_rc_command "$1" +RCEOF +chmod +x /usr/local/etc/rc.d/rmm_agent' + +ssh root@OPNSENSE 'sysrc rmm_agent_enable="YES" && service rmm_agent restart' +``` + +### 5. Verifizieren + +```bash +# Agent-Log pruefen +ssh root@OPNSENSE "tail -20 /usr/local/rmm/rmm-agent.log" + +# Auf dem Backend: Agent sollte erscheinen +curl -sk -H "X-API-Key: DEIN_API_KEY" https://BACKEND_IP:8443/api/v1/agents +``` + +**Wichtig**: Agent-ID wird persistent in `/usr/local/rmm/agent_id` gespeichert. Bei Neuinstallation bleibt die ID erhalten. ## API @@ -239,7 +411,7 @@ Retention: 90 Tage (Raw), Compression nach 7 Tagen. | GET | `/api/v1/agents/{id}/backups/diff?a={id}&b={id}` | Zeilenweises Diff zwischen zwei Backups | Backups werden dedupliziert: gleicher SHA256-Hash = kein neuer Eintrag. -Config-XML wird Base64-kodiert vom Agent zum Backend uebertragen und als Klartext in SQLite gespeichert. +Config-XML wird Base64-kodiert vom Agent zum Backend uebertragen und als Klartext in PostgreSQL gespeichert. ### Tunnel-Management @@ -574,8 +746,8 @@ rmm/ ## Technische Details -- **PostgreSQL + TimescaleDB**: Agent-Registry, Config-Backups, Time-Series Metriken (pgx Driver) -- **CGO-frei**: Kein CGO noetig (pure-Go PostgreSQL Driver) +- **PostgreSQL 17 + TimescaleDB 2.x**: Agent-Registry, Config-Backups, Time-Series Metriken +- **Pure-Go**: pgx/v5 Driver, kein CGO noetig - **Cross-Compilation**: Backend linux/amd64, Agent freebsd/amd64 - **TLS**: Self-signed Zertifikate (automatisch generiert) - **WebSocket**: gorilla/websocket, Binary Messages fuer Tunnel-Daten