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
Distinguish backup polling controls from guest safety pauses
pulse-triage[bot]1fe308b7ff40
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.mdindex 4c7238c5d2..a89c89d910 100644--- a/docs/CONFIGURATION.md+++ b/docs/CONFIGURATION.md@@ -222,8 +222,8 @@ Numeric intervals are **seconds** unless noted otherwise.| `pvePollingInterval` | PVE polling interval || `pbsPollingInterval` | PBS polling interval || `pmgPollingInterval` | PMG polling interval |-| `backupPollingInterval` | Backup polling interval (`0` = auto) |-| `backupPollingEnabled` | Enable backup polling |+| `backupPollingInterval` | Backup-record polling interval (`0` = auto, not disabled). See [Backup polling and guest safety](#backup-polling-and-guest-safety). |+| `backupPollingEnabled` | Enable scheduled backup-record collection, not a guest-agent pause. See [Backup polling and guest safety](#backup-polling-and-guest-safety). || `adaptivePollingEnabled` | Enable adaptive polling || `adaptivePollingBaseInterval` | Base interval for adaptive polling || `adaptivePollingMinInterval` | Minimum adaptive polling interval |@@ -379,8 +379,8 @@ When `allowEmbedding` is `false`, Pulse sends `X-Frame-Options: DENY` and `frame| `PMG_POLLING_INTERVAL` | PMG metrics polling frequency | `60s` || `CONNECTION_TIMEOUT` | API connection timeout | `60s` || `BACKUP_POLLING_CYCLES` | Poll cycles between backup checks | `10` |-| `ENABLE_BACKUP_POLLING` | Enable backup job monitoring | `true` |-| `BACKUP_POLLING_INTERVAL` | Backup polling frequency | `0` (Auto) |+| `ENABLE_BACKUP_POLLING` | Enable scheduled backup-record collection, not a guest-agent pause. See [Backup polling and guest safety](#backup-polling-and-guest-safety). | `true` |+| `BACKUP_POLLING_INTERVAL` | Backup-record polling interval (`0` = auto, not disabled). See [Backup polling and guest safety](#backup-polling-and-guest-safety). | `0` (Auto) || `ENABLE_TEMPERATURE_MONITORING` | Enable temperature monitoring (where supported) | `true` || `SSH_PORT` | SSH port for temperature collection over SSH | `22` || `ADAPTIVE_POLLING_ENABLED` | Enable smart polling for large clusters | `false` |@@ -400,6 +400,42 @@ When `allowEmbedding` is `false`, Pulse sends `X-Frame-Options: DENY` and `frame| `PULSE_TELEMETRY` | Outbound usage telemetry ([details](PRIVACY.md)); set `false` to disable | `true` || `PULSE_DEPLOYMENT_METHOD` | Optional closed telemetry label: `docker_compose`, `docker_run`, `container_other`, `systemd`, `binary_other`, or `other`; invalid values are reported only as the safe runtime fallback | Inferred as `container_other` or `binary_other` |+### Backup polling and guest safety++The Recovery panel's **Enable backup polling** switch (`backupPollingEnabled`,+or `ENABLE_BACKUP_POLLING`) controls whether Pulse schedules collection of+Proxmox/PBS backup records and guest snapshots. **Turning it off does not pause+ordinary PVE monitoring or its QEMU Guest Agent disk, memory and metadata+reads.** It does not stop Proxmox or PBS from running backup jobs, and changing+the setting does not cancel work already in flight. Do not use this switch as+a freeze-enabled backup safety precaution.++`backupPollingInterval` and `BACKUP_POLLING_INTERVAL` control that collection's+cadence. **`0` means automatic cadence, not disabled.** Longer intervals delay+backup evidence refresh; disabled polling leaves it unrefreshed. A retained+backup row or posture is not proof of a current observation, a successful+restore or guest thaw. Check the matching workload, datastore, namespace and+artifact time in the provider's own tools before relying on it; do not clear+history or run another backup to repair a Pulse display. Environment overrides+take precedence over `system.json` and lock the corresponding UI controls.+Schedule configuration changes outside backup or freeze/thaw windows.++For an affected installation, follow the deployment-specific+[backup safety precaution](VM_DISK_MONITORING.md#backup-safety) before a planned+freeze-enabled backup: pause the actual Pulse server and prevent its updater or+deployment controller from restarting it. This is not incident recovery, and+stopping Pulse does not cancel a guest-agent request already issued. Keep Pulse+stopped until the backup has ended and independent post-backup checks confirm+**thaw, fresh successful workload writes to every filesystem covered by the+backup, and workload liveness**. Use established checks independent of Pulse+and the QEMU Guest Agent, not new probes or forced writes. If any check fails or+is unavailable, leave Pulse and its updater paused and use the guest/platform's+recovery procedure. After all checks pass, restore **only services and timers+that were active before the pause**; do not guess unknown pre-pause states.+**Pulse monitoring and alerts are unavailable while stopped**: arrange+independent outage coverage. This precaution does not establish a fixed+monitoring defect.+### Logging Overrides| Variable | Description | Default |diff --git a/frontend-modern/public/docs/CONFIGURATION.md b/frontend-modern/public/docs/CONFIGURATION.mdindex 4c7238c5d2..a89c89d910 100644--- a/frontend-modern/public/docs/CONFIGURATION.md+++ b/frontend-modern/public/docs/CONFIGURATION.md@@ -222,8 +222,8 @@ Numeric intervals are **seconds** unless noted otherwise.| `pvePollingInterval` | PVE polling interval || `pbsPollingInterval` | PBS polling interval || `pmgPollingInterval` | PMG polling interval |-| `backupPollingInterval` | Backup polling interval (`0` = auto) |-| `backupPollingEnabled` | Enable backup polling |+| `backupPollingInterval` | Backup-record polling interval (`0` = auto, not disabled). See [Backup polling and guest safety](#backup-polling-and-guest-safety). |+| `backupPollingEnabled` | Enable scheduled backup-record collection, not a guest-agent pause. See [Backup polling and guest safety](#backup-polling-and-guest-safety). || `adaptivePollingEnabled` | Enable adaptive polling || `adaptivePollingBaseInterval` | Base interval for adaptive polling || `adaptivePollingMinInterval` | Minimum adaptive polling interval |@@ -379,8 +379,8 @@ When `allowEmbedding` is `false`, Pulse sends `X-Frame-Options: DENY` and `frame| `PMG_POLLING_INTERVAL` | PMG metrics polling frequency | `60s` || `CONNECTION_TIMEOUT` | API connection timeout | `60s` || `BACKUP_POLLING_CYCLES` | Poll cycles between backup checks | `10` |-| `ENABLE_BACKUP_POLLING` | Enable backup job monitoring | `true` |-| `BACKUP_POLLING_INTERVAL` | Backup polling frequency | `0` (Auto) |+| `ENABLE_BACKUP_POLLING` | Enable scheduled backup-record collection, not a guest-agent pause. See [Backup polling and guest safety](#backup-polling-and-guest-safety). | `true` |+| `BACKUP_POLLING_INTERVAL` | Backup-record polling interval (`0` = auto, not disabled). See [Backup polling and guest safety](#backup-polling-and-guest-safety). | `0` (Auto) || `ENABLE_TEMPERATURE_MONITORING` | Enable temperature monitoring (where supported) | `true` || `SSH_PORT` | SSH port for temperature collection over SSH | `22` || `ADAPTIVE_POLLING_ENABLED` | Enable smart polling for large clusters | `false` |@@ -400,6 +400,42 @@ When `allowEmbedding` is `false`, Pulse sends `X-Frame-Options: DENY` and `frame| `PULSE_TELEMETRY` | Outbound usage telemetry ([details](PRIVACY.md)); set `false` to disable | `true` || `PULSE_DEPLOYMENT_METHOD` | Optional closed telemetry label: `docker_compose`, `docker_run`, `container_other`, `systemd`, `binary_other`, or `other`; invalid values are reported only as the safe runtime fallback | Inferred as `container_other` or `binary_other` |+### Backup polling and guest safety++The Recovery panel's **Enable backup polling** switch (`backupPollingEnabled`,+or `ENABLE_BACKUP_POLLING`) controls whether Pulse schedules collection of+Proxmox/PBS backup records and guest snapshots. **Turning it off does not pause+ordinary PVE monitoring or its QEMU Guest Agent disk, memory and metadata+reads.** It does not stop Proxmox or PBS from running backup jobs, and changing+the setting does not cancel work already in flight. Do not use this switch as+a freeze-enabled backup safety precaution.++`backupPollingInterval` and `BACKUP_POLLING_INTERVAL` control that collection's+cadence. **`0` means automatic cadence, not disabled.** Longer intervals delay+backup evidence refresh; disabled polling leaves it unrefreshed. A retained+backup row or posture is not proof of a current observation, a successful+restore or guest thaw. Check the matching workload, datastore, namespace and+artifact time in the provider's own tools before relying on it; do not clear+history or run another backup to repair a Pulse display. Environment overrides+take precedence over `system.json` and lock the corresponding UI controls.+Schedule configuration changes outside backup or freeze/thaw windows.++For an affected installation, follow the deployment-specific+[backup safety precaution](VM_DISK_MONITORING.md#backup-safety) before a planned+freeze-enabled backup: pause the actual Pulse server and prevent its updater or+deployment controller from restarting it. This is not incident recovery, and+stopping Pulse does not cancel a guest-agent request already issued. Keep Pulse+stopped until the backup has ended and independent post-backup checks confirm+**thaw, fresh successful workload writes to every filesystem covered by the+backup, and workload liveness**. Use established checks independent of Pulse+and the QEMU Guest Agent, not new probes or forced writes. If any check fails or+is unavailable, leave Pulse and its updater paused and use the guest/platform's+recovery procedure. After all checks pass, restore **only services and timers+that were active before the pause**; do not guess unknown pre-pause states.+**Pulse monitoring and alerts are unavailable while stopped**: arrange+independent outage coverage. This precaution does not establish a fixed+monitoring defect.+### Logging Overrides| Variable | Description | Default |diff --git a/frontend-modern/src/utils/__tests__/backupPollingSafetyHelp.test.ts b/frontend-modern/src/utils/__tests__/backupPollingSafetyHelp.test.tsnew file mode 100644index 0000000000..d96d41f67e--- /dev/null+++ b/frontend-modern/src/utils/__tests__/backupPollingSafetyHelp.test.ts@@ -0,0 +1,132 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, it } from 'vitest';++import { renderDocMarkdown } from '@/features/docs/docMarkdown';++const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');+const read = (name: string) => readFileSync(path.join(root, name), 'utf8');+const guide = read('docs/CONFIGURATION.md');+const fragment = 'backup-polling-and-guest-safety';++function render(markdown: string, slug: string): HTMLElement {+ const article = document.createElement('article');+ article.innerHTML = renderDocMarkdown(markdown, slug);+ return article;+}++function help() {+ const section = guide.split('### Backup polling and guest safety')[1]?.split('\n### ')[0];+ expect(section).toBeTruthy();+ const article = render(section!, 'CONFIGURATION');+ return { article, text: article.textContent?.replace(/\s+/g, ' ') ?? '' };+}++describe('backup polling safety help', () => {+ it('ships one safety explanation in the public configuration guide', () => {+ expect(read('frontend-modern/public/docs/CONFIGURATION.md')).toBe(guide);+ const article = render(guide, 'CONFIGURATION');+ expect(article.querySelector(`#${fragment}`)?.textContent).toBe('Backup polling and guest safety');+ expect(article.querySelectorAll(`[id="${fragment}"]`)).toHaveLength(1);+ });++ it('makes the distinction reachable from each stored and environment setting', () => {+ const article = render(guide, 'CONFIGURATION');+ for (const key of [+ 'backupPollingEnabled',+ 'backupPollingInterval',+ 'ENABLE_BACKUP_POLLING',+ 'BACKUP_POLLING_INTERVAL',+ ]) {+ const cell = [...article.querySelectorAll('tbody tr td:first-child')].find(+ (element) => element.textContent === key,+ );+ expect(cell, key).toBeDefined();+ const link = cell!.parentElement?.querySelector(`a[href="#${fragment}"]`);+ expect(link?.textContent, key).toBe('Backup polling and guest safety');+ expect(link?.hasAttribute('data-doc-link'), key).toBe(true);+ }+ expect(article.querySelector(`#${fragment}`)).not.toBeNull();+ });++ it('distinguishes record collection from guest-agent reads and provider backup execution', () => {+ const { text } = help();+ expect(text).toContain('Enable backup polling');+ expect(text).toContain('controls whether Pulse schedules collection of Proxmox/PBS backup records');+ expect(text).toContain(+ 'Turning it off does not pause ordinary PVE monitoring or its QEMU Guest Agent disk, memory and metadata reads',+ );+ expect(text).toContain('It does not stop Proxmox or PBS from running backup jobs');+ expect(text).toContain('does not cancel work already in flight');+ expect(text).toContain('Do not use this switch as a freeze-enabled backup safety precaution');+ });++ it('keeps automatic cadence and override precedence distinct from disabling collection', () => {+ const { text } = help();+ expect(text).toContain('backupPollingInterval and BACKUP_POLLING_INTERVAL');+ expect(text).toContain('0 means automatic cadence, not disabled');+ expect(text).toContain('Environment overrides take precedence over system.json');+ expect(text).toContain('lock the corresponding UI controls');+ expect(text).toContain('Schedule configuration changes outside backup or freeze/thaw windows');+ const article = render(guide, 'CONFIGURATION');+ for (const key of ['backupPollingInterval', 'BACKUP_POLLING_INTERVAL']) {+ const row = [...article.querySelectorAll('tbody tr')].find(+ (element) => element.querySelector('td')?.textContent === key,+ );+ expect(row?.textContent, key).toContain('0 = auto, not disabled');+ }+ });++ it('does not turn retained backup evidence into current protection or a disruptive diagnostic', () => {+ const { article, text } = help();+ expect(text).toContain('Longer intervals delay backup evidence refresh');+ expect(text).toContain('disabled polling leaves it unrefreshed');+ expect(text).toContain(+ 'A retained backup row or posture is not proof of a current observation, a successful restore or guest thaw',+ );+ expect(text).toContain('matching workload, datastore, namespace and artifact time');+ expect(text).toContain("provider's own tools");+ expect(text).toContain('do not clear history or run another backup');+ expect(article.querySelector('pre')).toBeNull();+ });++ it('keeps the complete independent safety boundary rather than accepting an OK task or responsiveness', () => {+ const { text } = help();+ expect(text).toContain('pause the actual Pulse server');+ expect(text).toContain('prevent its updater or deployment controller from restarting it');+ expect(text).toContain('This is not incident recovery');+ expect(text).toContain('stopping Pulse does not cancel a guest-agent request already issued');+ expect(text).toContain('until the backup has ended and independent post-backup checks confirm');+ expect(text).toContain(+ 'thaw, fresh successful workload writes to every filesystem covered by the backup, and workload liveness',+ );+ expect(text).toContain('independent of Pulse and the QEMU Guest Agent');+ expect(text).toContain('not new probes or forced writes');+ expect(text).toContain('If any check fails or is unavailable, leave Pulse and its updater paused');+ expect(text).toContain('only services and timers that were active before the pause');+ expect(text).toContain('do not guess unknown pre-pause states');+ expect(text).toContain('Pulse monitoring and alerts are unavailable while stopped');+ expect(text).toContain('arrange independent outage coverage');+ expect(text).toContain('does not establish a fixed monitoring defect');+ });++ it('links to the existing deployment-specific precaution without adding a probe command', () => {+ const { article } = help();+ expect(article.querySelector('a[href="/docs/VM_DISK_MONITORING#backup-safety"]')?.textContent).toBe(+ 'backup safety precaution',+ );+ const safety = read('docs/VM_DISK_MONITORING.md');+ expect(read('frontend-modern/public/docs/VM_DISK_MONITORING.md')).toBe(safety);+ const target = render(safety, 'VM_DISK_MONITORING');+ for (const id of [+ 'backup-safety',+ 'pause-pulse-for-a-planned-freeze-enabled-backup',+ 'pause-a-docker-or-compose-server-for-a-planned-backup',+ ]) {+ expect(target.querySelector(`#${id}`), id).not.toBeNull();+ }+ expect(article.querySelector('pre')).toBeNull();+ expect(article.textContent).not.toMatch(/qm agent|pvesh|guest-fsfreeze|force-reset|disable backup freezing/);+ });+});