Zum Inhalt

Server-URL eines Agents oder Collectors ändern

Die Adresse, unter der Agents und Collectors deinen Vesana-Server erreichen, kannst du nachträglich ändern, ohne neu zu installieren. Praktisch beim Domain-Umzug, beim Wechsel auf eine neue IP oder beim Einrichten des Agent-Gateways.

Alles dazu lebt auf einer Admin-Seite: Admin → Agents & Collectors → Agent-Verbindung.

Die Seite: drei Schritte von oben nach unten

1. Server-Adresse

Ein Eingabefeld für die Adresse, unter der Agents & Collectors diesen Server erreichen (inklusive Port, falls nötig). Sie steht danach in den Installations-Befehlen für neue Maschinen — bestehende ziehst du in Schritt 3 darauf um.

Nach dem Speichern läuft ein Vorabcheck: der Server ruft die eingetragene Adresse selbst auf, um offensichtliche Fehler (falscher Port, DNS) sofort zu zeigen. Der Vorabcheck ist aber nur ein Hinweis — hinter Cloudflare oder NAT meldet er oft fälschlich „nicht erreichbar", obwohl die Adresse für echte Agents/Collectors funktioniert. Der verlässliche Test ist der Testlauf in Schritt 3.

2. Agent-Gateway (optional)

Ein Schalter, um den separaten Maschinen-Port zu aktivieren. Details dazu: Agent-Gateway.

3. Agents & Collectors umstellen

Die einzige folgenreiche Aktion auf der Seite — deshalb Canary-gegated:

  1. Erst ein Gerät testen: aus der Liste ein Agent oder Collector auswählen, „Mit einem Gerät testen" klicken. Das Gerät bekommt die neue Adresse vorgemerkt, stellt um und meldet sich zurück (in der Regel binnen einer Minute).
  2. Erst wenn dieser Testlauf erfolgreich war, wird „Alle umstellen" klickbar — das ist der Anti-Selbstabschuss: bevor du nicht bewiesen hast, dass mindestens eine Maschine die neue Adresse tatsächlich erreicht, lässt sich die ganze Flotte nicht in einem Rutsch umstellen.
  3. Die Fleet-Tabelle zeigt pro Gerät den Status: auf Ziel-Adresse / wechselt gerade / Fehler (mit Klartext-Ursache) / andere Adresse.

Schlägt der Testlauf fehl, bleibt das Testgerät auf der alten Adresse verbunden — es gibt keinen Ausfall, nur eine Fehlermeldung zum Nachbessern (z. B. falscher Port, Firewall).

Was technisch passiert (Pending-URL-Workflow)

  1. Der Server merkt die neue Adresse pro Agent/Collector als „pending" vor.
  2. Beim nächsten Heartbeat (Agent) bzw. Config-Poll (Collector) bekommt die Maschine die vorgemerkte Adresse zurückgemeldet.
  3. Brick-Schutz: Bevor die Maschine die neue Adresse übernimmt, probt sie sie zuerst (ein einfacher Health-Check gegen die neue Adresse). Schlägt die Probe fehl, bleibt sie auf der alten, funktionierenden Adresse und meldet dem Server den Grund — die Umstellung „hängt" dann sichtbar in der Fleet-Tabelle, statt dass die Maschine sich unerreichbar macht.
  4. War die Probe erfolgreich, schreibt die Maschine ihre Konfiguration neu und startet sich selbst neu (Linux: systemd Restart=always; Windows: Service-Neustart über den Restart-Helper).
  5. Nach dem Neustart meldet sie sich unter der neuen Adresse — der Server erkennt das und räumt den Pending-Status auf.

Der Token/API-Key bleibt bei einer reinen Adressänderung unverändert — er muss auf der Zielinstanz weiter gültig sein (z. B. nach einer Datenbank-Migration auf die neue Domain).

Lokal auf der Maschine (reconfigure)

Wenn eine Maschine den Server über keine bekannte Adresse mehr erreicht (Tippfehler beim Setup, alte Domain endgültig abgeschaltet), hilft die Server-GUI nicht weiter — dann direkt auf der Maschine:

sudo /usr/local/bin/vesana-agent reconfigure

sudo /usr/local/bin/vesana-collector reconfigure

Beide fragen interaktiv nach neuer Server-Adresse und (optional) neuem Token/API-Key ab und schreiben die Config-Datei. Leere Eingabe = keine Änderung. Der Token wird dabei nie im Klartext angezeigt (nur Anfang/Ende + Länge zur Plausibilitätsprüfung). Das Subcommand startet den Service danach nicht automatisch neu — manuell:

sudo systemctl restart vesana-agent      # bzw. vesana-collector
sudo journalctl -u vesana-agent -f       # zum Beobachten

Reihenfolge beim Einführen des Agent-Gateways

Ziehst du eine Bestandsflotte auf den separaten Agent-Gateway-Port um, gilt dieselbe Umzugs-Mechanik dieser Seite — mit einer verbindlichen Reihenfolge:

  1. Gateway aktivieren (Schritt 2 oben) + Funktionstest.
  2. Server-Adresse auf die Gateway-Adresse setzen (Schritt 1).
  3. Flotte migrieren — erst ein Gerät testen, dann alle (Schritt 3).
  4. Kontrollphase: beobachten, bis keine Maschine mehr über den alten Weg meldet.
  5. Erst danach die Web-Oberfläche per Firewall abschotten.

Details, Grenzen und Allowlist-Hintergrund: Agent-Gateway.