Files

T

History

kyleandClaude Opus 5.5 c5fe69a813 Add a Pester test suite for the collectors

84 tests in collectors/tests, run with Invoke-CollectorTests.ps1 (~15 s,
PowerShell 7.2+ and Pester 5.5+):

- Module.Tests: the shared module (property lookup, time format,
  config/lookback, sent-run state and pruning, dry runs, exit codes,
  401 detection)
- Veeam/Mars/Wsb/Vb365.Tests: each collector run in its own process
  against its mock and a stand-in ingest API, asserting the behaviours
  confirmed on real servers: VBR 13 live schedule, copy jobs, MARS UTC
  times and ErrorCode 0, WSB culture-formatted times and nested VMs,
  VB365 organization mapping, log prefixes and retries, state and
  resending, rejected keys
- Installers.Tests: config, files and scheduled task from each
  installer, with stand-ins for icacls / Task Scheduler / the key prompt

Collectors run under the test runner's PowerShell, or another shell via
-CollectorShell (e.g. powershell.exe, to test under Windows PowerShell
5.1 like the MARS, WSB and VB365 servers). The mocks take their "now"
from MOCK_NOW so expectations can't drift with the clock; the WSB mock
gains -RunningJobFinished for the running-to-finished case.

Each of 12 past bugs, put back one at a time, fails the test for its
behaviour (and the runner exits 1).

Co-Authored-By: Claude Opus 5.5 <[email protected]>

2026-10-08 13:36:27 -06:00

tests

Add a Pester test suite for the collectors

2026-10-08 13:36:27 -06:00

Get-WsbCollectorDiagnostics.ps1

Add Windows Server Backup collector

2026-10-07 15:56:04 -06:00

Install-WsbCollector.ps1

Move code shared by the collectors into one module

2026-10-08 11:09:01 -06:00

README.md

Move code shared by the collectors into one module

2026-10-08 11:09:01 -06:00

Send-WsbBackupStatus.ps1

Move code shared by the collectors into one module

2026-10-08 11:09:01 -06:00

README.md

Windows Server Backup collector

A PowerShell script that runs on each server using Windows Server Backup (WSB) and reports its backups to the dashboard. Each server appears as one job, named <SERVER> - Windows Server Backup by default.

Checked against: Server 2019 Hyper-V host backing up VMs, successful backups only. Not yet seen on a real server: a failed backup, a failed VM or volume, or a backup in progress. Those paths are written to the same object model, but if one looks wrong, run Get-WsbCollectorDiagnostics.ps1 while it's in that state and send the output.

Install (on the server, as an administrator)

Requires the Windows Server Backup feature with its PowerShell module (Install-WindowsFeature Windows-Server-Backup). Runs under Windows PowerShell 5.1 (powershell.exe), which that module targets.

On the dashboard host, create a key for this server:
```
python manage.py create-key wsb-acme-dc01
```
Copy the whole collectors folder to the server (the installer needs common as well as this folder), then from collectors\wsb run:
```
.\Install-WsbCollector.ps1 -ApiUrl https://backups.example.com -Tenant "Acme Corp"
```
Add -JobName "Domain Controller" to choose the name shown on the dashboard. It prompts for the key, then:
- writes C:\ProgramData\BackupDashboard\wsb-collector.json (readable only by SYSTEM and Administrators)
- copies the script to C:\Program Files\BackupDashboard\
- registers the scheduled task Backup Dashboard - WSB collector (SYSTEM, every 60 minutes)

Preview the payloads, then backfill 30 days so the history view is populated straight away:

powershell.exe -File 'C:\Program Files\BackupDashboard\Send-WsbBackupStatus.ps1' -DryRun
powershell.exe -File 'C:\Program Files\BackupDashboard\Send-WsbBackupStatus.ps1' -LookbackHours 720

It can be installed alongside the other collectors: it uses its own config, state, log and task. Re-run the installer to change settings or update the script. It also installs BackupDashboard.Collector.psm1, the code shared by all collectors, next to the script.

What it sends

Dashboard	Windows Server Backup
Company	`Tenant` from the config
Job	One per server, ID `wsb:<computer name>`, so changing `JobName` renames rather than duplicates it
Run	One per backup job from `Get-WBJob`, identified by its start time (WSB jobs have no ID). Restores are ignored. `details.items` lists what was backed up: the VMs for a Hyper-V backup, otherwise volumes
Status	Error HRESULT → Failed. Success, but a detailed error or a failed item (e.g. one volume) → Warning. Cancelled or unrecognised → Warning. In progress → Running
Started / finished	Job start / end time. WSB gives these as local-time text to the minute, in the server's date format; the collector parses them with that format
Next scheduled	`Get-WBSummary`'s `NextBackupTime`. Empty when there's no scheduled backup
Message	Error description, error codes (as `0x8XXXXXXX`), failed VMs/volumes, and the failure log path
Size	Bytes processed across the backup's items

Each run covers the last 48 hours (LookbackHours). Runs already delivered are recorded in wsb-collector.state.json.

Troubleshooting

Log: C:\ProgramData\BackupDashboard\wsb-collector.log. Exit codes: 0 OK, 1 some runs failed to send (retried next run), 2 setup failed (config or WindowsServerBackup module).
Wrong status, times or messages: run .\Get-WsbCollectorDiagnostics.ps1 (read-only). It prints the real structure of what the cmdlets return, plus recent Microsoft-Windows-Backup events to compare times against.

Testing without Windows Server Backup

. ./tests/MockWsb.ps1                    # or: . ./tests/MockWsb.ps1 -WithRunningJob
./Send-WsbBackupStatus.ps1 -ConfigPath ./my-test-config.json -DryRun