Update collectors/vveam/README.md

2026-10-06 00:54:38 +00:00
parent 8e29b9cbc4
commit 33c1613ef9
1 changed files with 0 additions and 0 deletions
@@ -0,0 +1,68 @@
+# Veeam Backup & Replication collector
+
+A PowerShell script that runs on each client's VBR server and reports job results to the dashboard.
+It covers jobs returned by `Get-VBRJob`: VM backup, replication and backup copy jobs.
+
+## Install (on the VBR server, as an administrator)
+
+1. On the dashboard host, create a key for this server:
+   ```bash
+   python manage.py create-key veeam-acme
+   ```
+2. Copy this folder to the VBR server and run:
+   ```powershell
+   .\Install-VeeamCollector.ps1 -ApiUrl https://backups.example.com -Tenant "Acme Corp"
+   ```
+   It prompts for the key, then:
+   - writes `C:\ProgramData\BackupDashboard\veeam-collector.json` (readable only by SYSTEM and Administrators)
+   - copies the script to `C:\Program Files\BackupDashboard\`
+   - registers the scheduled task **Backup Dashboard - Veeam collector** (SYSTEM, every 15 minutes)
+3. Preview the payloads, then backfill 30 days so the history view is populated straight away:
+   ```powershell
+   & 'C:\Program Files\BackupDashboard\Send-VeeamBackupStatus.ps1' -DryRun
+   & 'C:\Program Files\BackupDashboard\Send-VeeamBackupStatus.ps1' -LookbackHours 720
+   ```
+
+Re-run the installer to change settings or update the script. To remove the collector,
+delete the scheduled task and both `BackupDashboard` folders.
+
+## What it sends
+
+| Dashboard | Veeam |
+|---|---|
+| Company | `Tenant` from the config |
+| Job | Job name. The job's GUID is the ID, so renaming a job in Veeam doesn't duplicate it |
+| Status | Session result (Success / Warning / Failed). Any state other than Stopped is **Running**. A session that stopped with no result (e.g. cancelled) is reported as **Warning** |
+| Started / finished | Session `CreationTime` / `EndTime` |
+| Next scheduled | Job's next run. Sent as empty for disabled jobs and chained ("run after") jobs, so those are never flagged Overdue |
+| Message | Session reason, each VM or object that didn't succeed, and warning/error lines from the session log |
+| Size | `BackupStats.BackupSize` |
+
+Each run covers the last 48 hours (`LookbackHours`), so a few missed runs (server rebooting, API
+down) fill in automatically. Sessions already delivered are recorded in
+`veeam-collector.state.json`. Running sessions are re-sent until they finish.
+
+## Troubleshooting
+
+- Log: `C:\ProgramData\BackupDashboard\veeam-collector.log` (rotates at 5 MB).
+- Exit codes: `0` OK, `1` some jobs failed to send (they're retried next run), `2` setup failed
+  (config, Veeam module, or Veeam connection).
+- `API key rejected`: the key was revoked or mistyped. Re-run the installer with a new key.
+- `Get-VBRBackupSession` loads every session in the VBR database. On a server with years of history,
+  this can make each run take a minute or more. The task's 30-minute limit and "don't start if
+  already running" setting keep that safe.
+
+## Testing without Veeam
+
+`tests/MockVeeam.ps1` defines stand-in `Get-VBRJob` / `Get-VBRBackupSession` cmdlets with a mix of
+success, warning, failed, running and disabled jobs:
+
+```powershell
+. ./tests/MockVeeam.ps1
+./Send-VeeamBackupStatus.ps1 -ConfigPath ./my-test-config.json -DryRun
+```
+
+## Not covered yet
+
+- Veeam Agent jobs managed by VBR (`Get-VBRComputerBackupJob`), tape jobs, and SureBackup.
+- Veeam Backup for Microsoft 365, which has its own PowerShell module.