95 lines
4.6 KiB
Markdown
95 lines
4.6 KiB
Markdown
# 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)
|
|
|
|
=======
|
|
Requires PowerShell 7 installed machine-wide (`winget install Microsoft.PowerShell` or the MSI),
|
|
which VBR 13's Veeam module expects. The Microsoft Store version won't work, because the SYSTEM
|
|
account can't run it. The installer checks for this before changing anything.
|
|
|
|
>>>>>>> add-backend-api
|
|
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:
|
|
=======
|
|
2. Copy this folder to the VBR server and run, from PowerShell 7 (`pwsh`):
|
|
>>>>>>> add-backend-api
|
|
```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:
|
|
=======
|
|
- registers the scheduled task **Backup Dashboard - Veeam collector** (SYSTEM, every 15 minutes,
|
|
run by `C:\Program Files\PowerShell\7\pwsh.exe`; use `-PwshPath` if it's installed elsewhere)
|
|
3. Preview the payloads, then backfill 30 days so the history view is populated straight away
|
|
(from `pwsh`):
|
|
>>>>>>> add-backend-api
|
|
```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` |
|
|
|
|
=======
|
|
**Backup copy jobs (VBR 12+):** Veeam records their sessions under hidden per-source "worker" jobs.
|
|
The collector files each worker session under its copy job (via the worker's `PolicyJobId`), so a
|
|
copy job gets one run per source job it copies, with the source in `copied_from`.
|
|
|
|
>>>>>>> add-backend-api
|
|
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.
|
|
=======
|
|
- A job shows **Unknown** on the dashboard: the collector sent the job but matched no sessions to it.
|
|
Run `.\Get-VeeamCollectorDiagnostics.ps1` (read-only). It lists sessions whose job ID matches no
|
|
job, plus the type and link properties of the jobs left without sessions.
|
|
>>>>>>> add-backend-api
|
|
- `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.
|