docs
cairnobs.org Demo Source
Esc

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.

3 min read

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 SELECT queries); 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: false in agent.yaml, and the warning goes.

Nothing is read where Hyper-V isn't installed.

Upgrade and remove

  • Upgrade: run .\obs-beacon-agent.exe service install from 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 uninstall on the host. The config and state in ProgramData are kept.