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. Switching (test device as well as the whole fleet) requires a fresh confirmation of your identity (step-up) and the "Manage agents" permission. Without super-admin rights the only allowed targets are server addresses of this instance (the configured server address or BASE_URL); a foreign server cannot be installed as the new control centre this way.

  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 "Switch 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 request to /health under the new address). If the new address needs a certificate pin (e.g. gateway port with a self-signed certificate), the server sends it along; the machine probes with it and takes it into its configuration. 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 vesana-agent reconfigure

In an administrator PowerShell:

& "$env:ProgramFiles\Vesana Agent\vesana-agent.exe" reconfigure
Restart-Service VesanaAgent

sudo -u vesana-collector /opt/vesana-collector/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

On Windows: Restart-Service VesanaAgent.

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.