vantage-docs/docs/reference/agent-config.md at 11b1936bb20f91934fc5221692ec6ae33afd7689

Files

T

mrhid6 11b1936bb2 feat: documentation site

Docusaurus 3 docs-only site at docsite/, served statically by nginx under
/docs on the marketing host. Covers getting started (self-hosted install
through first server and first licence), the control plane, Vantage HQ,
a reference section and operations.

Wired into docker-compose.site.yml as docsite (3005:80) and into the
image build workflow, rebuilding on its own directory only. Never added
to the self-hosted compose file.

2026-07-28 15:46:33 +01:00

2.9 KiB

Raw Blame History

id, title, sidebar_label

id	title	sidebar_label
agent-config	Agent configuration	Agent config

The agent reads no environment variables. Everything is in one YAML file.

Location

Platform	Path
Linux	`/etc/vantage/config.yaml`
Windows	`%ProgramData%\vantage\config.yaml`

Directory 0700, file 0600. The install script sets both.

server_url: "vantage.yourdomain.com:9090"
server_id: "<uuid>"
pre_reg_token: "<token>" # removed after the first successful Register()
agent_token: "" # written by the agent after Register()
poll_interval: 30s
tls: true

Field	Meaning
`server_url`	`host:port` of the gRPC endpoint. Comes from the server's `GRPC_HOST`
`server_id`	The identity issued when the enrolment was created
`pre_reg_token`	Single-use, one hour. Cleared once registration succeeds
`agent_token`	The permanent credential, written by the agent itself
`poll_interval`	How often `SyncKeys` runs. Default `30s`
`tls`	Whether to use TLS. Leave `true`

:::danger This file is the credential agent_token is plaintext here and nowhere else — the control plane holds only its SHA-256. Anyone who can read this file can act as this agent. That is why it is 0600 and the directory is 0700. :::

Startup sequence

1. Load the config
2. pre_reg_token present → Register() → save agent_token,
   clear pre_reg_token, reconnect
3. Start goroutines: command stream · hourly update check ·
   inventory · monitors
4. Enter the SyncKeys poll loop

The poll loop

1. SyncKeys(server_id, agent_token, agent_version)
2. Non-Linux hosts stop here — Windows agents register and heartbeat only
3. Diff the desired keys against /root/.ssh/authorized_keys;
   unchanged → write nothing
4. Changed → write a temp file, os.Rename() over the real one, chmod 0600

Service management

Linux

Unit at /etc/systemd/system/vantage-agent.service, Restart=always, running as root.

systemctl status vantage-agent
systemctl restart vantage-agent
journalctl -u vantage-agent -f

Windows

A service registered through NSSM, or installed by the MSI that CI builds.

Get-Service vantage-agent
Restart-Service vantage-agent

Command-line flags

vantage-agent -generate-key

Generates a keypair locally. Normal operation takes no flags.

Moving an agent to a new control plane

Change server_url, clear agent_token, set a fresh pre_reg_token from a new enrolment, and restart. The old control plane still holds a server record that will go offline; delete it there.

Uninstalling

systemctl disable --now vantage-agent
rm -f /usr/local/bin/vantage-agent /etc/systemd/system/vantage-agent.service
rm -rf /etc/vantage
systemctl daemon-reload

Keys already written to authorized_keys remain on disk — the agent is no longer running to remove them. Revoke first if that matters.

2.9 KiB Raw Blame History