kyleandClaude Opus 5.5
b625a8af65
Checked with Get-WsbCollectorDiagnostics.ps1 output from a Server 2019
Hyper-V host (AAOG-EDM-HVR1):
- WBJob StartTime/EndTime are culture-formatted local-time strings
("10/6/2026 9:00 PM"). Parse them with the current culture: the
[datetime] cast uses the invariant (US) format and would misread
dd/MM dates, e.g. on en-CA/en-GB servers. Confirmed local, not UTC,
against the Microsoft-Windows-Backup event log
- Hyper-V backups nest VMs under a VirtualMachineList item's
SubItemList; failures, names and the items list now come from the
leaf items, falling back to a parent's SubItemFailed count
- Report size from the top-level items' BytesProcessed
- FailureLogPath is set even on success: running backups get no
message, and the log is only cited for warnings/failures
- HRESULTs are strings; conversion tolerates hex and bad values
- Mock rebuilt on the real shapes; tested under en-US and en-GB
Co-Authored-By: Claude Opus 5.5 <[email protected]>
70 lines
3.7 KiB
Markdown
70 lines
3.7 KiB
Markdown
# 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.
|
|
|
|
1. On the dashboard host, create a key for this server:
|
|
```bash
|
|
python manage.py create-key wsb-acme-dc01
|
|
```
|
|
2. Copy this folder to the server and run:
|
|
```powershell
|
|
.\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)
|
|
3. Preview the payloads, then backfill 30 days so the history view is populated straight away:
|
|
```powershell
|
|
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.
|
|
|
|
## 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
|
|
|
|
```powershell
|
|
. ./tests/MockWsb.ps1 # or: . ./tests/MockWsb.ps1 -WithRunningJob
|
|
./Send-WsbBackupStatus.ps1 -ConfigPath ./my-test-config.json -DryRun
|
|
```
|