Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

Distinguish backup polling controls from guest safety pauses

pulse-triage[bot]1fe308b7ff40
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 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.md
index 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.ts
new file mode 100644
index 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/);
+ });
+});