incus-backup-ui/docs/issues.md

Issue Backlog

1. Persist final agent job status in management

Management currently records when a backup or restore was accepted by an agent, but it does not persist the final agent job result.

Goal

Persist reliable end-to-end job status in the management database.

Tasks

• Add polling for accepted agent jobs from management.
• Store final success or failed status in job_history.
• Store duration, finished timestamp, error message, and agent job logs summary.
• Store created Restic snapshot ID for successful backup jobs when available.
• Surface final status in the Operations page.

Acceptance Criteria

• A backup started through management eventually shows success or failed.
• A restore started through management eventually shows success or failed.
• Agent restart or management restart does not lose already persisted history.

2. Expand node-agent health checks

The current health endpoint should provide deeper operational checks for backup readiness.

Goal

Make /api/health useful for diagnosing whether a node can actually run backup and restore operations.

Tasks

• Check that required commands exist: incus, zfs, restic, udevadm, dd.
• Check that configured ZFS pool exists.
• Check that /dev/zvol is accessible.
• Check Restic repository access.
• Check S3/Restic credentials by running a safe Restic command.
• Include ZFS pool capacity and free space.
• Return structured check names and messages.

Acceptance Criteria

• Management UI shows degraded node health with actionable check names.
• A missing command, wrong pool, or wrong Restic credentials is visible in health output.

3. Add per-VM backup policy

Retention and schedule behavior is currently broad. Per-VM policies would make production usage more flexible.

Goal

Allow each VM to define its own backup policy.

Tasks

• Add management database table for VM backup policies.
• Support per-VM retention values: hourly, daily, weekly, monthly.
• Support per-VM schedule enablement, interval, and time.
• Add optional policy flag: backup only when VM is running.
• Update Scheduler UI to edit policies per node and VM.
• Send policy retention to the agent backup request or apply it in management scheduling.

Acceptance Criteria

• Two VMs on the same node can have different schedules.
• Two VMs on the same node can have different retention policies.
• Disabled policies do not trigger backups.

4. Improve restore safety workflow

Restore is destructive and should be guarded with a clearer preflight and confirmation flow.

Goal

Reduce the risk of accidental or unsafe restores.

Tasks

• Add restore preflight endpoint.
• Validate node health before restore.
• Show selected snapshot metadata before restore.
• Show target VM status and disk size before restore.
• Require explicit typed confirmation including VM name.
• Optionally offer “create backup before restore” when the VM is accessible.
• Log restore intent in audit log before dispatch.

Acceptance Criteria

• UI displays a restore plan before the final confirmation.
• Restore is blocked when required preflight checks fail.
• Audit log records restore attempts and results.

5. Add failure notifications

Operators need to know when scheduled backups or restores fail.

Goal

Send notifications for failed or degraded operations.

Tasks

• Add notification settings in management.
• Support webhook notifications first.
• Include node, VM, job type, error, and timestamp.
• Trigger notifications for failed scheduled backups.
• Trigger notifications for failed manual backups/restores.
• Add a “send test notification” action.

Acceptance Criteria

• A failed scheduled backup sends one notification.
• A test notification can be triggered from the UI.
• Notification failures are visible in Operations or audit logs.

6. Implement real snapshot file browsing

Current snapshot browsing shows Restic contents, which for block-level backups is usually only /vm.raw.

Goal

Allow browsing files inside a backed-up VM disk image.

Tasks

• Design a safe read-only raw image inspection workflow.
• Restore or mount raw image read-only in a temporary workspace.
• Detect partitions and filesystems.
• Browse directories through management UI.
• Allow downloading a single file.
• Ensure cleanup of mounts and temporary files.

Acceptance Criteria

• User can browse a Linux VM filesystem from a snapshot without restoring the VM.
• Mounted/temporary resources are cleaned up after use.
• The workflow refuses unsupported or unsafe disk images with a clear error.

7. Add agent and management version reporting

Multi-node setups need version visibility.

Goal

Show software version and compatibility state for management and each agent.

Tasks

• Add version field to management API.
• Add version field to agent health response.
• Show agent version in Nodes page.
• Flag unsupported or outdated agents.
• Document compatibility expectations.

Acceptance Criteria

• Nodes page displays agent version.
• Management can identify incompatible agents.
• Health output includes version information.