diff --git a/README.md b/README.md deleted file mode 100644 index 7e96948..0000000 --- a/README.md +++ /dev/null @@ -1,81 +0,0 @@ -# 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. - -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, from PowerShell 7 (`pwsh`): - ```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, - 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`): - ```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`. - -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. -- `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.