Backup-Dashboard/collectors/wsb/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.

Not yet checked against a real server. The cmdlets are the WindowsServerBackup module's own (Get-WBJob, Get-WBSummary), but the properties of the objects they return, and whether job times are local or UTC, aren't fully documented. Before installing on the first server, run Get-WsbCollectorDiagnostics.ps1 and the collector with -DryRun (see below) to confirm what it reads.

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:

   python manage.py create-key wsb-acme-dc01
   

2. Copy this folder to the server and 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)
3. 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.

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
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
Next scheduled	Get-WBSummary's NextBackupTime. Empty when there's no scheduled backup
Message	Error description, error codes (as 0x8XXXXXXX), failed items, and the failure log path

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