Distribution & Erreichbarkeit¶

Unter Admin → Engine & Erfassung → Distribution legst du zwei Dinge fest:

Woher Agents und Collectors ihre Binaries und Updates beziehen (die drei Distribution-Modi).
Unter welchen URLs deine Maschinen den Server erreichen (die Server-URLs — inklusive der Basis für das optionale Agent-Gateway).

Die drei Distribution-Modi¶

integrated (Standard)¶

Der Vesana-Server selbst liefert die Binaries aus — unter https://<dein-server>/agent/install.sh, /collector/install.sh usw. Installer und Auto-Update holen alles direkt vom Server.

Distribution-URL: nicht nötig — es ist die eigene Server-URL.
„Distribution-Server testen": prüft, ob die Binaries lokal im Server vorliegen. Es wird nicht vesana.org getestet — das ist die Hersteller-Website, keine Distribution-Quelle.
Passt für die allermeisten Self-Hosted-Installationen.

external¶

Der Vesana-Server ist nur intern erreichbar (z. B. nur über VPN), aber die Kunden-VMs sollen sich trotzdem installieren und aktualisieren können. Binaries kommen dann von einem separaten, erreichbaren Distribution-Server.

Distribution-URL: Pflicht — die öffentlich erreichbare URL des Distribution-Servers (Layout /{dist}/vX.Y.Z/…).
„Distribution-Server testen": prüft diese URL per HTTP.

offline_only¶

Kein erreichbarer Server. Binaries werden als tar.gz/zip-Bundle verteilt (USB, Fileshare) und lokal entpackt. Auto-Updates sind aus; Updates erfolgen über ein neues Bundle.

Bundle erzeugen: beim Agent/Collector-Anlegen den Tab Offline-Bundle.
„Distribution-Server testen": entfällt (es gibt keinen Server zu testen).

Die Server-URLs¶

Auf derselben Seite gibt es zwei URL-Felder, die oft verwechselt werden:

Feld	Wer benutzt sie?	Wann setzen?
Agent-Server-URL (öffentlich)	Agents, Collectors, Install-Scripts, der vorbefüllte Windows-Installer	Wenn Maschinen den Server unter einer anderen Adresse erreichen als dein Browser — insbesondere mit aktivem Agent-Gateway (dann inkl. Port, z. B. `https://server.example.com:8443`). Leer = Vesana leitet die URL aus deiner Browser-Adresse ab.
Internal Server-URL	Install-Snippets in den Modi `external`/`offline_only`	Wenn Kunden-VMs den (internen) Server über VPN/Site-to-Site unter einer internen Adresse erreichen.

Die Agent-Server-URL landet überall dort, wo eine Maschine provisioniert wird: in den Linux-/Windows-Install-Kommandos, im heruntergeladenen setup.exe (die URL wird serverseitig ins Binary geschrieben) und in Offline-Bundles.

Erreichbarkeit testen (vom Server aus)

Neben dem Feld gibt es einen Test-Button: der Server ruft seine eigene Agent-Server-URL auf (GET /health). Das entlarvt Tippfehler, falsche Ports und Firewall-Probleme sofort — bevor du auch nur einen Agent umstellst. Die TLS-Prüfung ist dabei bewusst aus, damit der Test auch mit selbst-signiertem Zertifikat funktioniert.

Agent-Gateway: Weboberfläche abschotten¶

Ab v1.9.93. Wenn Agents und Collectors aus Kundennetzen über das Internet einliefern, muss dein Server öffentlich erreichbar sein. Ohne weitere Maßnahme hängt daran auch die komplette Weboberfläche: Login-Seite, Verwaltungs-API, alles.

Das Agent-Gateway löst das: ein separater Port, der ausschließlich Maschinen-Endpunkte bedient — Agent-Konfiguration, Heartbeats, Ergebnis-Annahme, Installer und Binary-Downloads. Keine Login-Seite, kein Frontend, keine Verwaltungs- oder Admin-API. Damit gibst du in der Firewall nur den Gateway-Port frei und beschränkst den UI-Port auf interne Netze oder VPN. Die Kundenmaschinen brauchen weiterhin nur ausgehendes HTTPS — daran ändert sich nichts.

Aktivieren — direkt in der Oberfläche (ab v1.9.95)¶

Auf derselben Seite (Admin → Engine & Erfassung → Distribution) findest du die Karte „Agent-Gateway": Port eintragen (Standard 8443) → „Gateway aktivieren" — fertig. Vesana persistiert die Einstellung (sie überlebt Updates und Neustarts) und startet den Gateway-Container. Schlägt der Start fehl, etwa weil der Port auf dem Server schon belegt ist, wird die Einstellung automatisch zurückgenommen und der Fehler direkt in der Karte angezeigt. Deaktivieren geht über denselben Knopf. Kein Handanlegen am Server nötig.

Alternativ: manuell per .env (headless/Automation, v1.9.93–94 oder ohne Updater)

In der .env deiner Installation zwei Zeilen ergänzen und den Stack neu starten:

COMPOSE_PROFILES=agent-gateway     # mehrere Profile kombinieren: "ai,agent-gateway"
AGENT_GATEWAY_PORT=8443            # Host-Port, frei wählbar (Standard 8443)

docker compose -f docker-compose.prod.yml up -d

Der Gateway-Container nutzt dasselbe Image und dieselben TLS-Zertifikate wie der Haupt-Webserver. Funktionstest:

curl -k https://<server>:8443/health              # → {"status":"ok", ...}
curl -k https://<server>:8443/                    # → 404 — kein Frontend
curl -k https://<server>:8443/api/v1/auth/login   # → 404 — kein Login

Beide Ports sind frei wählbar¶

Nur eine öffentliche IP, und die Agents sollen den Standard-Port 443 nutzen? Dann tauschst du einfach:

HTTPS_PORT=8443           # Weboberfläche wandert auf 8443 (nur intern erreichbar)
AGENT_GATEWAY_PORT=443    # Agents nutzen den Standard-Port

Bestehende Installation umstellen — Reihenfolge einhalten!¶

Der UI-Port bedient weiterhin alles (auch die Agent-Endpunkte). Deine Agents brechen also erst, wenn du sie migrierst und danach die Firewall schließt. Deshalb strikt in dieser Reihenfolge:

Gateway aktivieren (siehe oben) und mit den drei curl-Proben verifizieren.
Agent-Server-URL setzen (siehe Server-URLs) auf die Gateway-URL, z. B. https://server.example.com:8443 — und den Erreichbarkeits-Test drücken. Ab jetzt bekommen neue Agents automatisch die richtige URL.
Bestandsflotte migrieren: Admin → Instanz & Wartung → Server-URLs — Agents und Collectors auf die Gateway-URL umstellen. Jede Maschine übernimmt die neue URL beim nächsten Heartbeat automatisch und schreibt ihre Konfiguration selbst um.
Kontrollphase: Im Diagnose-Log (Kategorie „Verbindung") beobachten, bis alle Maschinen über den neuen Weg kommen. Nicht vorher weitermachen.
Erst jetzt: Firewall — UI-Port (HTTPS_PORT) nur noch intern/VPN, Gateway-Port öffentlich.

Nicht aussperren

Schließt du die Firewall, bevor die Flotte migriert ist, verlieren alle Agents die Verbindung (Status „Keine Daten"). Das ist jederzeit umkehrbar — Firewall wieder öffnen genügt —, kostet aber Monitoring-Lücken. Halte die Reihenfolge ein.

Rollback¶

Jederzeit ohne Update oder Neustart: Firewall wieder öffnen bzw. die Server-URL über dieselbe Umzugs-Seite zurückstellen.

Was bewusst NICHT über das Gateway läuft¶

Bereich	Warum	Konsequenz
Öffentliche Status-Pages	Mensch-Endpunkt, braucht das Frontend	Bei abgeschottetem UI-Port sind sie nicht öffentlich erreichbar — bei Bedarf den UI-Port gezielt für die nötigen Quellen freigeben
Mobile App	spricht die normale Benutzer-API	Techniker nutzen die App über VPN / die interne URL
APK-Download (`/downloads/`)	Menschen-Artefakt	über die Weboberfläche laden

Der Windows-Installer (setup.exe) und die Install-Scripts sind dagegen absichtlich auf dem Gateway verfügbar — das ist Provisionierung von Kundenmaschinen, genau der Zweck des Ports. Du kannst den Download-Link direkt an einen Kunden geben.

Fehlersuche¶

Symptom	Ursache / Lösung
`curl https://server:8443/health` → Timeout	Firewall/NAT: Gateway-Port nicht freigegeben, oder Container läuft nicht (`docker compose ps`)
Erreichbarkeits-Test im Admin schlägt fehl, `curl` vom Kundennetz geht	Der Server selbst erreicht seine öffentliche URL nicht (Hairpin-NAT). Der Test ist ein starkes Indiz, aber die Wahrheit ist der Kunden-Standort
Agent bleibt nach Migration „Keine Daten"	agent.log auf der Maschine prüfen (`C:\ProgramData\Vesana\Agent\agent.log` bzw. `journalctl -u vesana-agent`): steht dort die neue URL? Timeout → Firewall; 401 → Token; TLS-Fehler → Zertifikat/`insecure_skip_verify`
Login-Seite auf dem Gateway-Port sichtbar	Das darf nie passieren — Rolle prüfen: der Container braucht `VESANA_NGINX_ROLE=gateway` (bei Standard-Compose automatisch gesetzt)

Self-signed-Zertifikat?¶

Hat dein Server (noch) kein öffentliches Zertifikat, aktiviere beim Anlegen von Agent/Collector die Option „Server hat ein selbst-signiertes Zertifikat" — dann überspringt der Installer die TLS-Prüfung. Für öffentlich erreichbare Server besser ein echtes Zertifikat (z. B. Let's Encrypt) einrichten. Das Gateway nutzt automatisch dieselben Zertifikate wie die Weboberfläche.