Skip to content

Agent versioning

Agents and collectors auto-update — the server provides new binaries, clients fetch them at next config refresh.

Mechanism

sequenceDiagram
    participant A as Agent
    participant API as Server
    participant FS as /opt/vesana/agent-binaries/

    loop every 5 min (Agent) / 60 s (Collector)
        A->>API: GET /api/v1/agent/config
        API->>FS: read current VERSION file
        API-->>A: {config, latest_version, binary_url}
        alt latest_version > own version
            A->>FS: GET binary_url
            FS-->>A: new binary
            A->>A: verify SHA256
            A->>A: rename old binary, install new
            A->>A: restart service (systemd / Windows service)
        end
    end

On the server, binaries live under /opt/vesana/agent-binaries/:

agent-binaries/
├── VERSION                                    (e.g. "v1.4.2")
├── vesana-agent-linux-amd64
├── vesana-agent-windows-amd64.exe
├── vesana-agent-setup.exe                   (NSIS wizard for Windows)
└── install.sh                                 (one-command installer)

Same shape under /opt/vesana/collector-binaries/ for collectors.

Version format

Semver with v prefix: v1.0.0, v1.4.2. Auto-update only goes forward — agents don't downgrade themselves.

Which version is running?

In the UI: Admin → Hosts → Host detail → Agent box shows current agent version + server version + status (up to date / pending update / outdated).

On the machine:

vesana-agent --version

Pause updates

If a specific host shouldn't auto-update (pinning a version):

Host detail → Agent → Pause auto-update

Sets a flag — at the config endpoint the latest_version isn't appended, so the agent stops checking.

Pause status visible in host list as a pause icon next to the version.

Force update

# On the machine if update is stuck:
sudo systemctl restart vesana-agent  # Linux
net stop VesanaAgent && net start VesanaAgent  # Windows

Force from server side:

Host detail → Agent → Request update now

Sets a marker in the DB. On next heartbeat, the agent updates immediately.

Releasing a new version (internal)

Operations detail

This section is for people developing Vesana. Self-hosters get updates via GUI.

# 1. Tag
git tag v1.5.0
git push origin v1.5.0

# 2. Build agent + collector
cd agent && make build-all VERSION=v1.5.0
cd collector && make build VERSION=v1.5.0

# 3. Build Windows installer (NSIS)
cd agent/deploy && makensis installer.nsi

# 4. Upload to server
SSH=...
scp agent/bin/vesana-agent          ${SSH}:/opt/vesana/agent-binaries/vesana-agent-linux-amd64
scp agent/bin/vesana-agent.exe      ${SSH}:/opt/vesana/agent-binaries/vesana-agent-windows-amd64.exe
scp agent/bin/vesana-agent-setup.exe ${SSH}:/opt/vesana/agent-binaries/vesana-agent-setup.exe

# 5. Update VERSION file (triggers auto-update)
ssh ${SSH} 'echo "v1.5.0" > /opt/vesana/agent-binaries/VERSION'

# 6. Restart server-internal agent
ssh ${SSH} 'systemctl stop vesana-agent && \
            cp /opt/vesana/agent-binaries/vesana-agent-linux-amd64 /usr/local/bin/vesana-agent && \
            systemctl start vesana-agent'

VERSION is passed to Go via -ldflags="-X main.Version=v1.5.0". Without explicit VERSION=, Go appends -dirty because the repo has untracked files.

Don't change the VERSION file before binary is tested

A bad binary plus updated VERSION triggers auto-update on all agents/collectors at once. Bad binary = all customer agents broken. Always verify on a test instance before echo VERSION.

NSIS wizard for Windows

vesana-agent-setup.exe isn't the bare binary but an NSIS wizard with input fields for server URL and token. Logic in agent/deploy/installer.nsi. The wizard:

  1. Asks server URL and token
  2. Installs binary into C:\Program Files\Vesana\Agent\
  3. Writes config into C:\ProgramData\Vesana\Agent\config.yaml
  4. Registers Windows service VesanaAgent
  5. Starts service

After make build-all, always run makensis installer.nsi, otherwise setup.exe is stale.

Auto-update for custom builds

If you build the agent with custom modifications and don't want auto-update:

  1. VESANA_AUTO_UPDATE=false in /etc/vesana-agent/config.yaml (or Windows registry)
  2. Restart service

The agent stops checking version comparison.

Agent rollback

No automatic agent rollback. If a new agent version causes issues:

  1. Reset server VERSION file to old version
  2. On affected machines: restore old binary from /usr/local/bin/.vesana-agent.bak (auto-update backup)
  3. Restart service

For widespread issues: reset VERSION, pause auto-update on agents, debug calmly.

Next