Install · 7 of 8
Adding Windows hosts
The Windows agent: one PowerShell line from the web interface, a service under its own account with no administrator rights, and what it reads: services, the event log, certificate stores and Hyper-V's VMs.
The Windows agent runs on Windows Server 2016 and later, and Windows 10 and 11, on amd64 and arm64. It reports the same things the Linux agent does, where Windows has them, and the server judges a Windows host the same way.
With a join command
Under Configure › Hosts, type the host's name and press Make the install command. The box has a Windows line. Run it in PowerShell as Administrator:
& ([scriptblock]::Create((irm https://obs.example.org/install.ps1))) -Join cobsj1_…
install.ps1 fetches obs-beacon-agent_<version>_windows_<amd64|arm64>.zip
for the machine's architecture from the server's agent packages
(Where hosts get the package),
checks it against SHA256SUMS, installs the service, joins and starts it.
By hand
From the release's zip, in PowerShell as Administrator:
.\obs-beacon-agent.exe service install
& "C:\Program Files\Cairn OBS\obs-beacon-agent.exe" join cobsj1_…
Start-Service obs-beacon-agent
Or, instead of joining, write C:\ProgramData\obs-beacon\agent.yaml from
agent.example.yaml in the zip, with a token from the config file
(By hand, or with configuration tools),
and start the service.
The release's Windows files aren't code-signed, so SmartScreen and some
endpoint protection may warn about them. Check the zip against
SHA256SUMS and its signature first (Download and check).
How it runs
- A service,
obs-beacon-agent, starting automatically and restarted if it fails. - Under its own virtual account,
NT SERVICE\obs-beacon-agent: no password, no administrator rights, no helper. - Its config and state in
C:\ProgramData\obs-beacon, which only it, SYSTEM and Administrators can open. - It logs to the Application event log, source
obs-beacon-agent.
What it reads
| The host | CPU, memory (the page file as swap), fixed volumes, network, uptime, the Windows version. Windows has no load average, so that shows as "—" |
| Services | From the Service Control Manager. Running is active; stopped with an automatic start is failed; the rest inactive. Name the ones that must run in expected.yaml by service name (units: [W32Time, MSSQLSERVER]), or with Adopt what's running |
| The event log | Every five minutes, the errors and criticals of the last day in System and Application, grouped by source and event ID, on the host's page. A critical event in the last hour (Kernel-Power 41, a failing disk) is a warning; errors are listed, never alerted on. event_log: false turns it off |
| Certificates | The machine's My and WebHosting stores (cert_stores changes the list), read-only and never a key, and the certificates served on its listening ports (Certificates) |
| Maps | Listening ports and connections with their processes, as on Linux (Network and service maps) |
| Hyper-V | The host's VMs, their state, health, size and automatic start, below |
The hardware ID links a Windows VM to the VMware, Hyper-V, Proxmox or KubeVirt host it runs on, as for Linux VMs.
Hyper-V's VMs
Windows shows Hyper-V's VMs only to Administrators and members of Hyper-V Administrators; anyone else gets an empty list. Windows has no read-only Hyper-V role, and Hyper-V Administrators can also start, stop and change VMs. So the agent isn't added to it on install: on a Hyper-V host without it, the host's page and a warning say it "can't read its VMs". Choose one:
-
Let it read the VMs. The agent only ever reads (four WMI
SELECTqueries); the group is what Windows asks for, not what the agent uses.Add-LocalGroupMember -Group "Hyper-V Administrators" -Member "NT SERVICE\obs-beacon-agent" Restart-Service obs-beacon-agent -
Don't. Set
hyperv: falseinagent.yaml, and the warning goes.
Nothing is read where Hyper-V isn't installed.
Upgrade and remove
- Upgrade: run
.\obs-beacon-agent.exe service installfrom the new zip. It stops the service, replaces the program and starts it again. - Remove: Remove under Configure › Hosts revokes its
certificate, then
.\obs-beacon-agent.exe service uninstallon the host. The config and state in ProgramData are kept.