Zum Inhalt

Server-URL eines Agents oder Collectors ändern

Ab v0.38 kann die Server-Adresse einer bestehenden Agent- oder Collector- Installation nachträglich geändert werden, ohne neu installieren zu müssen. Praktisch z.B. beim Server-Umzug auf eine neue Domain.

Es gibt zwei Wege — beide verwenden die gleiche Mechanik:

Weg Wann Was geändert werden kann
Server-GUI (Bulk oder Einzeln) Wenn der Agent/Collector noch normal Heartbeats sendet Server-URL
Lokal auf dem Host (reconfigure-Subcommand) Wenn der Agent/Collector den Server nicht mehr erreicht (Tippfehler, alte Domain abgeschaltet) Server-URL und Token/API-Key

Token-Rotation server-seitig kommt in einer späteren Version. Wenn du den Token rotieren musst, mach das via reconfigure direkt auf dem Host.

Weg 1: Über die Server-GUI

Der Operator setzt eine neue Server-URL im Backend. Beim nächsten Heartbeat liefert der Server sie aus, der Agent/Collector schreibt seine Konfig und startet sich neu (per systemd Restart=always). Sobald er sich mit der neuen URL meldet, gilt der Wechsel als bestätigt und der „Pending"-Marker verschwindet.

Einzeln

  1. Collectors: auf der Seite Collectors in der Zeile des Collectors das Globus-Icon klicken → Modal mit URL-Feld → speichern.
  2. Agents: Hosts-Seite → es gibt aktuell keinen Per-Row-Knopf für Agents. Stattdessen im „Agent-Server-URL ändern"-Knopf oben rechts auf der Hosts-Seite alle agent-managed Hosts deselektieren bis nur der gewünschte übrig bleibt → speichern.

Bulk

  1. Auf der Collectors-Seite oder der Hosts-Seite oben rechts „Server-URL ändern (Bulk)" klicken.
  2. Im Modal alle gewünschten Ziele markieren (Default: alle vorausgewählt).
  3. Neue URL eingeben → speichern.

Was du danach siehst

  • Das Globus-Icon der betroffenen Items wird gelb (Pending-Marker). Hover zeigt die Pending-URL.
  • Sobald der nächste Heartbeat eintrudelt (Agent ~1 Min, Collector ~30 Sek) und der Agent/Collector sich neu mit der neuen URL meldet, wird der Pending-Marker automatisch geleert. Das ist die Bestätigung.
  • Bei Self-Hostern mit Restart=always (Default seit v0.18) klappt das ohne Operator-Eingriff. Falls die systemd-Unit angepasst wurde: systemctl restart vesana-agent (bzw. vesana-collector) auf dem Zielsystem auslösen.

Was wenn der Agent die neue URL gar nicht erreichen kann?

Der Agent crashed dann nach dem Restart, weil er zur neuen URL keine Verbindung bekommt. systemd startet ihn ~10 Sek später wieder, gleicher Effekt — ein Loop. Lösung: auf dem Host das reconfigure-Subcommand ausführen und manuell die richtige URL setzen (siehe Weg 2). Oder auf dem alten Server die GUI öffnen, dort die Pending-URL zurück auf die alte Adresse setzen, sodass der Agent wieder hochkommt.

Weg 2: Lokal auf dem Host (reconfigure)

Funktioniert komplett ohne Server-Verbindung. Praktisch wenn beim Setup Server-URL oder Token vertippt wurden, oder wenn der Server die Hosts nicht mehr erreicht.

Agent

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

Beispiel-Output:

Aktueller Server : https://vesana.alt.example.com
Aktueller Token  : vesana…XYZ4 (52 Zeichen)
Leer lassen = unverändert.

Neue Server-URL (https://…): https://vesana.neu.example.com
Neuer Token: 
✓ Geschrieben: /etc/vesana-agent/config.yaml
Jetzt systemctl restart vesana-agent ausführen damit die Änderung wirksam wird.

Danach:

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

Collector

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

Selbe Eingabemaske, schreibt /etc/vesana/collector.env. Danach:

sudo systemctl restart vesana-collector
sudo journalctl -u vesana-collector -f

Hinweise

  • Felder leer lassen bedeutet keine Änderung.
  • Server-URL muss mit https:// oder http:// beginnen, sonst Fehler.
  • Token wird nicht im Klartext angezeigt — nur die ersten 8 und letzten 4 Zeichen, plus Längen-Anzeige zur Plausibilität.
  • Das Subcommand startet den Service nicht automatisch neu, weil es als Foreground-Tool vom User gestartet wird und systemd nicht weiß, dass es laufen darf.

Was passiert technisch?

  1. Operator setzt im Backend pending_server_url auf agent_tokens.pending_server_url bzw. collectors.pending_server_url.
  2. Der nächste Heartbeat liefert diese URL in der Response zurück ("pending_server_url": "...").
  3. Agent/Collector vergleicht mit der aktuell verwendeten URL. Bei Abweichung: schreibt die Konfig (atomar via tmp + rename) und beendet den Prozess mit Exit-Code 0. systemd (Restart=always) startet ihn ~10 Sek später neu.
  4. Nach dem Neustart verbindet er gegen die neue URL. Im nächsten Heartbeat schickt er "current_server_url": "<neue URL>".
  5. Server vergleicht: wenn current == pending, wird das Pending-Feld geleert. Das schließt den Roundtrip ab.

Token (Agent-Token / Collector-API-Key) bleibt unverändert — wird vom Server beim alten Wert validiert, der auch auf der neuen Server-Instanz existieren muss (z.B. nach Datenbank-Migration). Wenn nur die Domain wechselt aber der DB-Inhalt erhalten bleibt, läuft das transparent.