Distribution & Erreichbarkeit¶
Unter Admin → Agents & Collectors → Agent-Verbindung legst du fest, unter welcher URL deine Maschinen den Server erreichen (die Agent-Server-URL — inklusive der Basis für das optionale Agent-Gateway) und stellst eine bestehende Flotte auf eine neue Adresse um.
Woher kommen Installer und Binaries?¶
Vom Vesana-Server selbst — unter https://<dein-server>/agent/install.sh, /collector/install.sh usw. Installer und Auto-Update holen alles direkt vom Server (bzw. vom Agent-Gateway-Port, wenn du ihn nutzt). Eine separate „Distribution-Quelle" gibt es nicht mehr: die früheren Modi external (separater Distribution-Server) und ein Signatur-Pubkey-Feld wurden 09/2026 entfernt — es gab keinen Distribution-Server, den man hätte eintragen können, und die Signatur prüfte kein Installer.
Ohne Netzverbindung zur Zielmaschine nimmst du das Offline-Bundle: beim Anlegen von Agent/Collector der Tab „Offline-Bundle" erzeugt ein tar.gz/zip mit Binary, Installer und vorbefüllter Konfiguration (USB, Fileshare). Ein Bundle-Agent aktualisiert sich später ganz normal über den Server, sobald er ihn erreicht.
Die Server-URL¶
| Feld | Wer benutzt sie? | Wann setzen? |
|---|---|---|
| Agent-Server-URL | 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. |
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 → Wartung → Server-URLs) 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:
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 → 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 |
| Installierte Web-App am Smartphone | ist die normale Weboberfläche | Techniker nutzen sie über VPN / die interne URL |
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 (Fingerabdruck prüfen: Erreichbarkeits-Test zeigt pinned/trusted; Agent-Config server_cert_sha256) |
| 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?¶
Das Gateway nutzt die Zertifikate des Vesana-Stacks (dasselbe ssl-Volume wie der Stack-Webserver). Terminierst du TLS mit einem eigenen Reverse-Proxy davor (zweiter nginx, Caddy, Traefik mit Let's Encrypt), zeigt der Gateway-Port trotzdem das selbstsignierte Stack-Zertifikat — dein Proxy sitzt nicht vor dem Gateway-Port. Das ist kein Problem: Vesana erkennt das selbst. Die Install-Befehle und der vorbefüllte Windows-Installer tragen dann den Fingerabdruck des Stack-Zertifikats mit, und beim Umzug einer bestehenden Flotte reist er im Heartbeat mit. Agent und Collector akzeptieren genau dieses Zertifikat zusätzlich zur normalen Prüfung — ohne die Prüfung abzuschalten. Der Erreichbarkeits-Test der Agent-Server-URL sagt dir, ob das Zertifikat öffentlich vertrauenswürdig ist oder gepinnt wird. Auch der Installationsbefehl selbst prüft den Fingerabdruck schon beim Herunterladen des Installers — unter Windows über einen eingebauten Zertifikats-Check (PowerShell 5.1 und 7), unter Linux über curl --pinnedpubkey (curl muss auf dem Zielrechner vorhanden sein). Ein Befehl, der mit einem älteren Stack-Zertifikat erzeugt wurde, bricht nach einem Zertifikatswechsel ab: dann den Befehl in Vesana neu erzeugen.
Die Option „Server hat ein selbst-signiertes Zertifikat" beim Anlegen von Agent/Collector schaltet die Prüfung dagegen komplett ab — nur noch nötig, wenn du den Pin bewusst nicht willst. Für öffentlich erreichbare Server bleibt ein echtes Zertifikat (z. B. Let's Encrypt) die bessere Wahl.
Das ssl-Volume nicht löschen, solange Agents über das Gateway laufen
Ein neu erzeugtes Stack-Zertifikat hat einen anderen Fingerabdruck. Agents, die den UI-Port wegen der Firewall nicht mehr erreichen, können den neuen Pin nicht nachlernen. Zertifikat wechseln heißt: Flotte vorher über Server-URLs zurück auf den UI-Port, oder den neuen Pin per Server-URL-Umzug verteilen.