Skip to content

Changing the server URL of an agent or collector

Since v0.38, you can change the server address of an existing agent or collector installation without re-installing. Useful e.g. for server domain migration.

There are two paths — both use the same mechanism:

Path When What can be changed
Server GUI (bulk or single) Agent/collector still sends heartbeats normally Server URL
Locally on the host (reconfigure subcommand) Agent/collector cannot reach the server (typo at setup, old domain shut down) Server URL and token / API key

Server-side token rotation is planned for a later release. If you need to rotate a token, do it via reconfigure directly on the host.

Path 1: Via the server GUI

The operator sets a new server URL in the backend. On the next heartbeat the server hands it back; the agent/collector rewrites its config and restarts itself (via systemd Restart=always). As soon as it reports back with the new URL, the change is considered confirmed and the "pending" marker disappears.

Single

  1. Collectors: on the Collectors page click the globe icon in the row of the collector you want to change → modal with URL field → save.
  2. Agents: on the Hosts page there is currently no per-row button for agents. Use the "Change agent server URL" button at the top right of the Hosts page, deselect all agent-managed hosts except the one you want, then save.

Bulk

  1. On the Collectors page or the Hosts page click "Change server URL (bulk)" at the top right.
  2. In the modal pick the desired targets (default: all pre-selected).
  3. Enter the new URL → save.

What you'll see

  • The globe icon for affected items turns yellow (pending marker). Hover shows the pending URL.
  • Once the next heartbeat arrives (agent ~1 min, collector ~30 sec) and the agent/collector reports with the new URL, the pending marker is cleared automatically — that's the confirmation.
  • For self-hosters with Restart=always (default since v0.18) this works without operator intervention. If the systemd unit was customised: trigger systemctl restart vesana-agent (or vesana-collector) on the target.

What if the agent can't reach the new URL at all?

The agent crashes after the restart because it cannot connect to the new URL. systemd restarts it ~10s later — same effect, you get a loop. Fix: run the reconfigure subcommand on the host and set the correct URL manually (see Path 2). Or use the GUI on the old server to set the pending URL back to the original address so the agent comes back up.

Path 2: Locally on the host (reconfigure)

Works without any server connection. Useful when server URL or token were mistyped at setup, or when the server can no longer reach the hosts.

Agent

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

Sample output:

Aktueller Server : https://vesana.alt.example.com
Aktueller Token  : vesana…XYZ4 (52 chars)
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.

Then:

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

Collector

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

Same prompt, writes /etc/vesana/collector.env. Then:

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

Notes

  • Leaving fields empty means no change.
  • The server URL must start with https:// or http://.
  • The token is never displayed in cleartext — only first 8 + last 4 characters, plus length, for plausibility checking.
  • The subcommand does not auto-restart the service, because it runs as a foreground process started by the user and systemd is not aware it should keep it running.

How does it work technically?

  1. Operator sets pending_server_url on agent_tokens.pending_server_url or collectors.pending_server_url.
  2. The next heartbeat returns that URL in the response ("pending_server_url": "...").
  3. The agent/collector compares with its current URL. On mismatch: writes the config atomically (tmp + rename) and exits with code 0. systemd (Restart=always) brings it back ~10s later.
  4. After the restart it connects to the new URL. In the next heartbeat it sends "current_server_url": "<new URL>".
  5. The server compares: if current == pending, the pending field is cleared. That closes the roundtrip.

The token (agent token / collector API key) stays the same — it must exist on the new server instance (e.g. after a DB migration). If only the domain changes but the DB content is preserved, this is transparent.