Backup-Dashboard/collectors/mars/README.md

Azure Backup (MARS agent) collector

A PowerShell script that runs on each server with the Microsoft Azure Recovery Services (MARS) agent and reports its backups to the dashboard. Each server appears as one job, named <SERVER> - Azure Backup by default.

Not yet checked against a real MARS agent. The cmdlets are the agent's own (Get-OBJob, Get-OBPolicy, Get-OBSchedule), but the property names of the objects they return aren't documented. Before installing on the first server, run Get-MarsCollectorDiagnostics.ps1 and the collector with -DryRun (see below) to confirm what it reads.

Install (on the server, as an administrator)

Runs under Windows PowerShell 5.1 (powershell.exe), which the agent's MSOnlineBackup module targets and which every supported Windows Server has.

1. On the dashboard host, create a key for this server:

   python manage.py create-key mars-acme-fs01
   

2. Copy this folder to the server and run:

   .\Install-MarsCollector.ps1 -ApiUrl https://backups.example.com -Tenant "Acme Corp"
   

   Add -JobName "File Server" to choose the name shown on the dashboard. It prompts for the key, then:
   • writes C:\ProgramData\BackupDashboard\mars-collector.json (readable only by SYSTEM and Administrators)
   • copies the script to C:\Program Files\BackupDashboard\
   • registers the scheduled task Backup Dashboard - MARS 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-MarsBackupStatus.ps1' -DryRun
   powershell.exe -File 'C:\Program Files\BackupDashboard\Send-MarsBackupStatus.ps1' -LookbackHours 720
   

It can be installed alongside the Veeam collector: it uses its own config, state, log and task. Re-run the installer to change settings or update the script.

What it sends

Dashboard	MARS
Company	Tenant from the config
Job	One per server, ID mars:<computer name>, so changing JobName renames rather than duplicates it
Status	Backup job state: Failed → Failed. Completed with failed bytes or an error → Warning. Aborted/cancelled or unrecognised → Warning. In progress → Running. Restore jobs are ignored
Started / finished	Job start / end time
Next scheduled	Next slot from the backup policy schedule, or the System State policy's if that's sooner. Empty (so never Overdue) for schedules that run every 2+ weeks, since which week is next can't be told
Message	Job and per-datasource errors, and datasources with failed bytes
Size	Bytes transferred, summed across datasources

Each run covers the last 48 hours (LookbackHours). Jobs already delivered are recorded in mars-collector.state.json.

Troubleshooting

• Log: C:\ProgramData\BackupDashboard\mars-collector.log. Exit codes: 0 OK, 1 some runs failed to send (retried next run), 2 setup failed (config or MARS module).
• Wrong status, sizes or messages: run .\Get-MarsCollectorDiagnostics.ps1 (read-only). It prints the real structure of the objects the agent's cmdlets return.

Testing without MARS

. ./tests/MockMars.ps1
./Send-MarsBackupStatus.ps1 -ConfigPath ./my-test-config.json -DryRun