Skip to content

Agent versioning

Agents and collectors update themselves automatically. The matching binaries arrive on the server with every Vesana update; agents and collectors fetch them on their next configuration poll.

Mechanism

sequenceDiagram
    participant A as Agent / collector
    participant S as Vesana server

    loop on config poll (agent every 5 min, collector every minute)
        A->>S: fetch configuration
        S-->>A: configuration + current version + download address
        alt server version newer than own
            A->>S: download binary
            A->>S: download signature (<binary>.sig)
            A->>A: verify signature (otherwise no update)
            A->>A: replace binary
            A->>A: restart (systemd / Windows service)
        end
    end
  • Version: agent and collector carry the same version number as the Vesana server (v1.<line>.<patch>). After a server update the agents follow within about 5 minutes, collectors within a minute.
  • Forward only: if the server's version is not newer than its own, nothing happens. An agent never downgrades by itself.
  • Download address: the server address the agent itself uses (also on the agent gateway or with a non-default HTTPS port), otherwise the configured agent server address. A pinned certificate also applies to the update download.
  • Checks before replacing: the file must be a real executable (an HTML error page is never installed) and at most 256 MiB.
  • Linux agent: the binary is replaced, the agent exits, systemd restarts it (Restart=always).
  • Windows agent: the running binary is renamed to vesana-agent.exe.old, the new one takes its place; a short-lived scheduled task restarts the service.
  • Collector and active collector: the service only stages the verified update. A root helper (a systemd path unit, for the collector vesana-collector-update.path) verifies the signature again, replaces the root-owned file under /opt/vesana-collector or /opt/vesana-active-collector and restarts the service. A rejected update replaces nothing; the reason is in the journal. Details: Collector.

Signed updates

Every agent and collector binary that Vesana ships carries a vendor signature (a <binary>.sig file next to it). Agent and collector verify it before every self-update against keys built into them:

  • If the signature is missing or doesn't match, there is no update. The agent keeps running on its version; monitoring is not affected. The agent log states the reason; the next attempt for the same version comes after one hour.
  • Signing happens at the vendor, never on your instance. The Vesana server only delivers binary and signature. Even a compromised Vesana server therefore cannot slip a foreign binary to an agent — this also protects Agent Lock against the binary being swapped.
  • No going back to older versions: the signature covers product, version, operating system, architecture, checksum and size. An agent won't accept an older, genuinely signed version.
  • The check cannot be turned off — not from the server either.

The initial installation does not check a signature; it is protected by TLS or the certificate pin. Self-built binaries carry no vendor signature; an agent therefore won't accept them as an update — they can only be installed via the installer.

Which version is running

In Vesana:

  • on the agent chip on the host page and under Manage host → Connection ("Online · v1.…"),
  • for the whole fleet under Admin → Agents & Collectors → Agent Lock ("Version" column).

On the machine:

vesana-agent --version                                              # Linux
& "$env:ProgramFiles\Vesana Agent\vesana-agent.exe" version          # Windows (PowerShell)

What does not exist

  • No per-host pause and no "request update now". Every agent follows the version of its server. Restarting the service does not trigger an update; the check happens on the next regular config poll.
  • No automatic rollback. If the Vesana server goes back to an older version, the agents stay on their newer version (no downgrade). A machine only gets an older agent version through a reinstall.
  • No update control in the agent config. Instances that previously set distribution to "offline only" keep that: their agents get no update address and do not update themselves. It can no longer be set in the UI.

Windows setup wizard

vesana-agent-setup.exe is not the bare binary but a setup wizard. The download from Vesana ("Set up agent" dialog) comes with the server address pre-filled and, if needed, the certificate fingerprint. The wizard:

  1. asks for server URL and token (silent: /S /TOKEN=… /SERVER=…),
  2. installs the program into C:\Program Files\Vesana Agent\,
  3. locks C:\ProgramData\Vesana\Agent down to SYSTEM and Administrators and creates config.yaml there afresh,
  4. registers the Windows service VesanaAgent and starts it.

The wizard is only for the initial installation; afterwards the agent updates itself.

Next