Distribution & Erreichbarkeit¶
Unter Admin → Agents & Collectors → Agent-Verbindung legst du fest, unter welcher Adresse deine Maschinen den Server erreichen (die Server-Adresse — 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. Hat der Server ein selbstsigniertes Zertifikat, trägt das Bundle dessen Fingerabdruck mit (Datei vesana-cert-pin.env, vom Installer gelesen) — wie die Online-Befehle.
Die Server-Adresse¶
| Feld | Wer benutzt sie? | Wann setzen? |
|---|---|---|
| Server-Adresse | Agents, Collectors, Install-Scripts, der vorbefüllte Windows-Installer | Wenn Maschinen den Server unter einer anderen Adresse erreichen sollen als der BASE_URL aus der .env — insbesondere mit aktivem Agent-Gateway (dann inkl. Port, z. B. https://server.example.com:8443). Ist nichts gespeichert, gilt BASE_URL. Gespeichert wird mit „Adresse speichern". |
Die Server-Adresse 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. Bestehende Maschinen behalten ihre Adresse, bis du sie unten auf der Seite umstellst.
Vorabcheck vom Server aus
Während du die Adresse eingibst, ruft der Server sie selbst auf (GET /health) und zeigt „Vorabcheck: vom Server aus erreichbar" oder den Grund (Port zu, Zeitüberschreitung, DNS, TLS). Das entlarvt Tippfehler und falsche Ports, bevor du einen Agent umstellst. Hinter Cloudflare oder NAT kann der Vorabcheck scheitern, obwohl die Adresse von außen geht — entscheidend ist der Testlauf mit einem Gerät (siehe unten).
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¶
Auf derselben Seite (Admin → Agents & Collectors → Agent-Verbindung) findest du die Karte „Agent-Gateway": Schalter umlegen — Vesana startet das Gateway auf Port 8443 und trägt die Server-Adresse https://<host>:8443 für dich ein (für Proxy-Setups überschreibbar). Einen anderen Port setzt du danach über „Port ändern" → „Übernehmen (Neustart)". Vesana persistiert die Einstellung (sie überlebt Updates und Neustarts). Schlägt der Start fehl, etwa weil der Port auf dem Server schon belegt ist, wird die Einstellung zurückgenommen und der Fehler direkt in der Karte angezeigt; die Karte hat außerdem einen Firewall-Hinweis zum Aufklappen. Deaktivieren geht über denselben Schalter. Deine laufenden Maschinen bleiben dabei auf ihrer bisherigen Adresse, bis du sie bewusst umstellst. Der Schalter braucht den Updater-Dienst.
Alternativ: manuell per .env (headless/Automation 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. - Server-Adresse prüfen (siehe Die Server-Adresse): Das Einschalten hat sie auf die Gateway-URL gesetzt, z. B.
https://server.example.com:8443; der Vorabcheck sollte „erreichbar" zeigen. Ab jetzt bekommen neue Agents automatisch die richtige URL. - Bestandsflotte umstellen — unten auf derselben Seite: „1. testen" → Testgerät wählen → „Mit einem Gerät testen". Erst wenn sich das Testgerät auf der neuen Adresse zurückmeldet (≤ 1 Min), wird „2. umstellen" → „Alle umstellen" klickbar. Jede Maschine übernimmt die neue Adresse beim nächsten Heartbeat, prüft sie vorher selbst und schreibt ihre Konfiguration um; erreicht sie die Adresse nicht, bleibt sie auf der alten verbunden.
- Kontrollphase: In der Liste (Filter „auf Ziel" / „ausstehend" / „Fehler") bzw. 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-Adresse auf derselben Seite zurückstellen und die Maschinen erneut umstellen.
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) |
Vorabcheck im Admin schlägt fehl, curl vom Kundennetz geht |
Der Server selbst erreicht seine öffentliche URL nicht (Hairpin-NAT). Der Vorabcheck ist ein Indiz, maßgeblich ist der Testlauf mit einem Gerät |
| Testgerät erreicht die neue Adresse nicht | Das Gerät bleibt auf der alten Adresse verbunden (kein Ausfall); der Grund steht in der Zeile. Adresse/Port korrigieren, „Testlauf zurücksetzen", erneut testen |
| 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 in der Agent-Config server_cert_sha256 prüfen) |
| 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. 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 (TLS-Prüfung überspringen)" 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.
Zertifikat aus Vesana (Let's Encrypt) und Pins¶
Stellt Vesana das Zertifikat selbst aus (Admin → System → Zertifikat, TLS / Zertifikat), liefern Weboberfläche UND Gateway-Port dasselbe öffentlich vertraute Zertifikat aus — Agents und Collectors brauchen dann keinen Pin mehr, auch solche, die bisher mit Pin auf das selbstsignierte verbunden waren (sie prüfen „Kette ODER Pin"). Ein ACME-Zertifikat pinnt Vesana nie: es wechselt bei jeder Erneuerung. Erreicht ein Gerät Vesana über eine Adresse, die das Zertifikat nicht deckt (z. B. eine IP), nennt die Vorprüfung es VOR dem Einsetzen — dann das Gerät über Agent-Verbindung auf einen gedeckten Namen umziehen.
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 Agent-Verbindung zurück auf den UI-Port, oder den neuen Pin per Adress-Umzug verteilen.