Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Explain backup badge freshness for longer backup cycles
pulse-triage[bot]4511bb0a562d
diff --git a/docs/PBS.md b/docs/PBS.mdindex bfe3bb3981..bfb61548c9 100644--- a/docs/PBS.md+++ b/docs/PBS.md@@ -303,6 +303,39 @@ private keys. If help is needed, provide only the HTTP status, relevant redactederror and which expected reading is missing. Do not clear History or recreate aworking connection to make missing data look resolved.+### Backup age colours for a longer backup cycle++The VM/LXC backup shield uses **hours**, separately from the backup-age alert+thresholds in **days**. An amber age badge does not by itself mean that a+backup failed or that a notification was sent.++Open **Alerts → Thresholds → Proxmox**, then expand **Recovery**. In+**Global Defaults**:++| Control | What it changes |+| --- | --- |+| **Fresh Hours** | How long the latest completed backup keeps a green shield. The default is 24 hours. |+| **Stale Hours** | The end of the next age band, after which the backup is classified as overdue. Keep it at least as large as Fresh Hours. |+| **Warning Days** / **Critical Days** | Backup-age alert thresholds, not the shield's freshness window. Leave these unchanged unless you intend to change alert policy. |++For a three-day cycle, **Fresh Hours = 72** keeps a completed backup fresh+through 72 hours. **Stale Hours = 96**, for example, leaves a further day in+the stale band. Choose any scheduling margin to match your existing backup+policy; these are global display settings, not a change to the backup schedule.+Review the alert-day values before saving, then check the same guest's badge.+The completed backup's time does not change, and missing or unknown backup+evidence is not made healthy by a longer freshness window.++**v6.5.0 caution:** if **Critical Days** is Off while **Warning Days** is+enabled, do not save threshold edits on that version: its editor can re-enable+critical alerts at the warning age. Cancel rather than changing alert policy+just to remove an amber badge.++If the problem is missing backups or conflicting protection evidence rather+than an expected longer cycle, use the [backup health checks](#backups-are-visible-but-coverage-says-unprotected)+instead. Do not run another backup, change retention, disable alerts or clear+History just to change a colour.+### Backups are visible but Coverage says UnprotectedThe **Backup health** strip and the backup list answer different questions.diff --git a/frontend-modern/public/docs/PBS.md b/frontend-modern/public/docs/PBS.mdindex bfe3bb3981..bfb61548c9 100644--- a/frontend-modern/public/docs/PBS.md+++ b/frontend-modern/public/docs/PBS.md@@ -303,6 +303,39 @@ private keys. If help is needed, provide only the HTTP status, relevant redactederror and which expected reading is missing. Do not clear History or recreate aworking connection to make missing data look resolved.+### Backup age colours for a longer backup cycle++The VM/LXC backup shield uses **hours**, separately from the backup-age alert+thresholds in **days**. An amber age badge does not by itself mean that a+backup failed or that a notification was sent.++Open **Alerts → Thresholds → Proxmox**, then expand **Recovery**. In+**Global Defaults**:++| Control | What it changes |+| --- | --- |+| **Fresh Hours** | How long the latest completed backup keeps a green shield. The default is 24 hours. |+| **Stale Hours** | The end of the next age band, after which the backup is classified as overdue. Keep it at least as large as Fresh Hours. |+| **Warning Days** / **Critical Days** | Backup-age alert thresholds, not the shield's freshness window. Leave these unchanged unless you intend to change alert policy. |++For a three-day cycle, **Fresh Hours = 72** keeps a completed backup fresh+through 72 hours. **Stale Hours = 96**, for example, leaves a further day in+the stale band. Choose any scheduling margin to match your existing backup+policy; these are global display settings, not a change to the backup schedule.+Review the alert-day values before saving, then check the same guest's badge.+The completed backup's time does not change, and missing or unknown backup+evidence is not made healthy by a longer freshness window.++**v6.5.0 caution:** if **Critical Days** is Off while **Warning Days** is+enabled, do not save threshold edits on that version: its editor can re-enable+critical alerts at the warning age. Cancel rather than changing alert policy+just to remove an amber badge.++If the problem is missing backups or conflicting protection evidence rather+than an expected longer cycle, use the [backup health checks](#backups-are-visible-but-coverage-says-unprotected)+instead. Do not run another backup, change retention, disable alerts or clear+History just to change a colour.+### Backups are visible but Coverage says UnprotectedThe **Backup health** strip and the backup list answer different questions.diff --git a/frontend-modern/src/features/docs/__tests__/backupFreshnessDocs.test.ts b/frontend-modern/src/features/docs/__tests__/backupFreshnessDocs.test.tsnew file mode 100644index 0000000000..a5ea5fbdf8--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/backupFreshnessDocs.test.ts@@ -0,0 +1,74 @@+import { readFileSync } from 'node:fs';+import { resolve } from 'node:path';+import { createRoot } from 'solid-js';+import { describe, expect, it } from 'vitest';+import { getBackupInfo } from '@/utils/format';+import { ALERT_THRESHOLDS_SECTION_TITLE_BACKUPS } from '@/utils/alertThresholdsPresentation';+import { useThresholdsRecoveryDefaultsState } from '@/features/alerts/thresholds/hooks/useThresholdsRecoveryDefaultsState';+import type { ThresholdsTableProps } from '@/features/alerts/thresholds/types';+import { createGuideFixture } from './guideFixture';++const read = (name: string) => readFileSync(resolve(process.cwd(), '../docs', `${name}.md`), 'utf8');+const article = createGuideFixture(read);+const text = (node: Element) => node.textContent!.replace(/\s+/g, ' ').trim();+const now = new Date('2026-10-12T08:00:00Z');+const hour = 3_600_000;++describe('backup-cycle help matches the existing controls', () => {+ it('names the actual Recovery group and separates display hours from alert days', () => {+ const guide = article('PBS');+ const heading = guide.querySelector('#backup-age-colours-for-a-longer-backup-cycle');+ expect(heading).not.toBeNull();+ expect(text(guide)).toContain(`Alerts → Thresholds → Proxmox, then expand ${ALERT_THRESHOLDS_SECTION_TITLE_BACKUPS}`);+ expect(text(guide)).toContain('Global Defaults');+ const table = heading!.nextElementSibling!.nextElementSibling!.nextElementSibling!;+ expect(table.tagName).toBe('TABLE');+ expect([...table.querySelectorAll('tbody tr td:first-child')].map(text)).toEqual([+ 'Fresh Hours', 'Stale Hours', 'Warning Days / Critical Days',+ ]);+ expect(text(table)).toContain('not the shield\'s freshness window');+ expect(readFileSync(resolve(process.cwd(), 'public/docs/PBS.md'), 'utf8')).toBe(read('PBS'));+ });++ it('reproduces the one-day badge and validates the documented three-day boundary', () => {+ const completed = now.getTime() - 25 * hour;+ expect(getBackupInfo(completed, undefined, now).status).toBe('stale');+ const thresholds = { freshHours: 72, staleHours: 96 };+ expect(getBackupInfo(completed, thresholds, now).status).toBe('fresh');+ for (const [hours, expected] of [[72, 'fresh'], [73, 'stale'], [96, 'stale'], [97, 'overdue']] as const) {+ expect(getBackupInfo(now.getTime() - hours * hour, thresholds, now).status).toBe(expected);+ }+ expect(getBackupInfo(completed, thresholds, now).ageMs).toBe(25 * hour);+ expect(text(article('PBS'))).toContain('Fresh Hours = 72');+ expect(text(article('PBS'))).toContain('Stale Hours = 96');+ });++ it('does not turn missing, future or invalid evidence into a fresh backup', () => {+ const thresholds = { freshHours: 72, staleHours: 96 };+ expect(getBackupInfo(null, thresholds, now).status).toBe('never');+ expect(getBackupInfo('invalid', thresholds, now).status).toBe('unknown');+ expect(getBackupInfo(now.getTime() + hour, thresholds, now).status).toBe('unknown');+ const guide = article('PBS');+ expect(text(guide)).toContain('missing or unknown backup evidence is not made healthy');+ expect(guide.querySelector('a[href="#backups-are-visible-but-coverage-says-unprotected"]')).not.toBeNull();+ expect(text(guide)).toContain('Do not run another backup, change retention, disable alerts or clear History');+ });++ it('retains the stable-version caution while the repaired editor preserves Off', () => {+ const config = { enabled: true, warningDays: 3, criticalDays: 0, freshHours: 72, staleHours: 96 };+ const result = createRoot((dispose) => {+ const state = useThresholdsRecoveryDefaultsState({+ backupDefaults: () => config,+ snapshotDefaults: () => ({ enabled: false, warningDays: 0, criticalDays: 0 }),+ } as ThresholdsTableProps);+ const sanitized = state.sanitizeBackupConfig(config);+ dispose();+ return sanitized;+ });+ expect(result).toMatchObject(config);+ const guide = text(article('PBS'));+ expect(guide).toContain('v6.5.0 caution:');+ expect(guide).toContain('do not save threshold edits on that version');+ expect(guide).toContain('Cancel rather than changing alert policy');+ });+});