Skip to content

Changing the server URL of an agent or collector

You can change the address agents and collectors use to reach your Vesana server without reinstalling anything. Useful for a domain move, switching to a new IP, or setting up the agent gateway.

Everything for this lives on one admin page: Admin → Instance & maintenance → Agent connection.

The page: three steps top to bottom

1. Server address

An input field for the address agents & collectors use to reach this server (including port, if needed). After saving it appears in the install commands for new machines — you migrate existing ones onto it in step 3.

After saving, a pre-check runs: the server calls the entered address itself to surface obvious problems (wrong port, DNS) immediately. The pre-check is only a hint though — behind Cloudflare or NAT it often incorrectly reports „unreachable" even though the address works fine for real agents/collectors. The reliable test is the test run in step 3.

2. Agent gateway (optional)

A toggle to activate the separate machine port. Details: Agent gateway.

3. Migrate agents & collectors

The one consequential action on the page — hence canary-gated:

  1. Test one device first: pick an agent or collector from the list, click „Test with one device". That device gets the new address staged, switches over, and reports back (usually within a minute).
  2. Only once that test run succeeds does „Migrate all" become clickable — this is the anti-self-destruct guard: until you've proven at least one machine actually reaches the new address, you can't flip the entire fleet at once.
  3. The fleet table shows per-device status: on target address / switching / error (with a plain-text cause) / other address.

If the test run fails, the test device stays connected on the old address — there's no outage, just an error to fix (e.g. wrong port, firewall).

What happens technically (pending-URL workflow)

  1. The server stages the new address per agent/collector as „pending".
  2. On the next heartbeat (agent) or config poll (collector), the machine gets the pending address back.
  3. Brick protection: before the machine adopts the new address, it probes it first (a simple health check against the new address). If the probe fails, it stays on the old, working address and reports the reason back to the server — the migration then visibly „hangs" in the fleet table instead of the machine making itself unreachable.
  4. If the probe succeeds, the machine rewrites its config and restarts itself (Linux: systemd Restart=always; Windows: service restart via the restart helper).
  5. After restarting it reports in under the new address — the server detects this and clears the pending status.

The token/API key stays unchanged on a pure address change — it must remain valid on the target instance (e.g. after a database migration to the new domain).

Locally on the machine (reconfigure)

If a machine can no longer reach the server under any known address (typo at setup, old domain shut down for good), the server GUI won't help — run this directly on the machine instead:

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

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

Both prompt interactively for a new server address and (optionally) a new token/API key, then write the config file. Empty input = no change. The token is never shown in cleartext (only start/end + length, for plausibility checking). The subcommand does not restart the service automatically afterwards — do it manually:

sudo systemctl restart vesana-agent      # or vesana-collector
sudo journalctl -u vesana-agent -f       # to watch

Order when introducing the agent gateway

Moving an existing fleet to the separate agent gateway port uses this same migration mechanism — with a mandatory order:

  1. Activate the gateway (step 2 above) + run the function test.
  2. Set the server address to the gateway address (step 1).
  3. Migrate the fleet — test one device first, then all (step 3).
  4. Verification phase: watch until no machine reports in via the old path anymore.
  5. Only then lock down the web UI behind a firewall.

Details, limits, and allowlist background: Agent gateway.