Skip to content
WatchTower15Docs

Upgrades

Keeping a monitoring agent current shouldn’t be a project. WatchTower15 agents learn about new versions from the backend and update themselves, with the same checksum verification used at install.

How version signalling works

Section titled “How version signalling works”

Every authenticated agent response includes an X-Agent-Required-Version header: the latest released agent version, which WatchTower15 caches for up to five minutes. When it differs from the running binary’s version, the agent knows an upgrade is available. This is a pull model — the backend never reaches into your host.

Self-update

Section titled “Self-update”

When an upgrade is signalled, the agent:

  1. Downloads the new binary from the distribution endpoint.
  2. Verifies it against the published X-Content-SHA256 — a mismatch aborts the upgrade and the current version keeps running.
  3. Swaps the binary in place and restarts the service.

Because the download is checksum-verified before it is ever executed, a corrupted or tampered download cannot replace a healthy agent.

The agent upgrades right after WatchTower15 has accepted a telemetry sample (or a heartbeat, on a server whose telemetry is switched off), and flushes the data it keeps on the host to disk before it restarts. An upgrade therefore keeps that data: the new version sends whatever was still waiting.

You can also upgrade a host explicitly by re-running the installer in upgrade mode, as root. It downloads the latest release, verifies it the same way, replaces the binary and restarts the service, keeping the host’s existing configuration (including any proxy):

Terminal window
curl -fsSL https://api.watchtower15.com/api/agent/install-script | sudo sh -s -- --upgrade

On a host behind a proxy, add -x <proxy> to that curl, as for the install; the upgrade itself reuses the proxy already in the agent’s configuration. Upgrades, automatic or run this way, download from api.watchtower15.com, so a host behind an IP allow-list needs nothing beyond the three addresses it already allows (see the Restricted egress tab under Install).

An upgrade run this way also installs the uninstall unit, which a host installed before agent 1.1.48 does not have. It is the one way such a host gets its agent removed by itself when its server is deleted; one whose agent already asked for its removal has it removed within seconds.

Rolling out across a fleet

Section titled “Rolling out across a fleet”

There is one advertised version for every agent: the latest release. Each agent picks it up the next time it contacts WatchTower15 after the release, so a fleet converges within minutes, with no orchestration. There is no per-profile or per-host version pinning.

What an upgrade never does

Section titled “What an upgrade never does”
  • It never changes the agent’s privilege model. The self-update replaces only the binary; the systemd unit, its service user and its two capabilities stay exactly as installed. Only --upgrade, run as root, adds the uninstall unit; the self-update never does.
  • It never requires inbound access to your host.
  • The automatic self-update never runs as root: it runs as the agent’s service user and writes only to the agent’s own directory, /var/lib/wt15-server-agent.

Verifying the running version

Section titled “Verifying the running version”

The agent logs its version on its start-up line, and the server’s page in the dashboard shows it as Version in the Agent card, on its Info tab:

Terminal window
grep 'agent running' /var/log/wt15-server-agent.log | tail -1
systemctl status wt15-server-agent

The start-up line also says where the agent’s configuration came from: config=fetched (from WatchTower15), config=cache (etag=…, saved … ago) (the profile kept on the host, when WatchTower15 could not be reached), or config=none (no profile: none was kept and WatchTower15 could not be reached, or the server is not being monitored, for example while it waits for approval). After a normal restart it reads config=fetched, preceded by the configuration the agent started from and WatchTower15’s confirmation:

agent config applied (source=cache, etag=…, saved=… (… ago), telemetry=15s, …)
agent config confirmed by WatchTower15 (etag=…): the cached profile is current
agent running v… (heartbeat=30s, telemetry=15s, …, config=fetched, proxy=none)

If an agent is stuck on an old version, check that it can reach the API (X-Agent-Required-Version is only seen on successful authenticated calls). Request signatures depend on the clock, and WatchTower15 refuses a server whose clock is more than 300 seconds off. The agent corrects its own clock when it is more than 290 seconds off WatchTower15’s, before that limit, and writes an error line asking for the server’s time to be fixed (see When WatchTower15 cannot be reached).

Section titled “Related”