# 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.

> **Checked against:** MARS agent 2.0.9274, a Files & Folders policy with completed backups only.
> Not yet seen on a real agent: a failed backup, a backup in progress, or a System State policy.
> Those paths are written to the same object model, but if one looks wrong, run
> `Get-MarsCollectorDiagnostics.ps1` while it's in that state and send the output.

## 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. Create a key for this server on the dashboard's **Admin** page, or on the dashboard host:
   ```bash
   python manage.py create-key mars-acme-fs01
   ```
2. Copy the whole `collectors` folder to the server (the installer needs `common`
   as well as this folder), then from `collectors\mars` run:
   ```powershell
   .\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
   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 other collectors: it uses its own config, state, log and task.
Re-run the installer to change settings or update the script. It also installs
`BackupDashboard.Collector.psm1`, the code shared by all collectors, next to 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. MARS reports these in UTC without marking them as UTC; the collector handles that |
| 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 (non-zero error codes), failed file counts, and the failed-file log path |
| 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

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