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.

Separate a stopped server from completed guest requests in backup help

pulse-triage[bot]1309370a88e8
diff --git a/docs/VM_DISK_MONITORING.md b/docs/VM_DISK_MONITORING.md
index 09480663a1..aeddc4cabc 100644
--- a/docs/VM_DISK_MONITORING.md
+++ b/docs/VM_DISK_MONITORING.md
@@ -75,7 +75,8 @@ the systemd commands below do not stop a containerised Pulse server.
```bash
sudo systemctl stop pulse.service
- systemctl show pulse.service --property=LoadState,ActiveState,MainPID
+ systemctl show pulse.service \
+ --property=LoadState,ActiveState,MainPID,Result,ExecMainCode,ExecMainStatus
```
Require `LoadState=loaded`, `ActiveState=inactive` and `MainPID=0` after a
@@ -84,6 +85,21 @@ the systemd commands below do not stop a containerised Pulse server.
**Pulse monitoring and alerts are unavailable while stopped.** Do not run
an update, start another Pulse instance or reboot its host during the pause.
+ For a server stopped in this step, also require `Result=success`,
+ `ExecMainCode=1` (normal process exit) and `ExecMainStatus=0`. A timeout,
+ signal termination, non-zero exit or unavailable shutdown result needs
+ normal maintenance before the backup. Do not force-kill Pulse or clear its
+ failed state to satisfy this check. Leave a previously inactive server
+ inactive; an old exit result is not evidence of a new shutdown.
+
+ **Stopping Pulse does not cancel a guest-agent request already issued.**
+ Even a successful process exit does not prove that an earlier request
+ finished inside Proxmox or the guest. Let existing guest/backup operations
+ finish normally before the planned backup, using your established task and
+ workload checks, not new guest-agent probes. If their state is unknown,
+ do not start the backup on the strength of a stopped service or an arbitrary
+ waiting period. A disk dash or cooldown is not evidence of completion.
+
4. **Verify the guest independently, then restore only what you paused.**
Keep Pulse stopped until the backup has ended **and** your established
guest-console or workload checks confirm all three: **thaw**, **fresh successful
diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
index 77dc13349a..fc0406dcf0 100644
--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md
+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
@@ -20,6 +20,23 @@
## Purpose
+### Systemd backup-pause help separates shutdown from remote completion
+
+The existing systemd precaution reads the stop result as well as the inactive
+service state. A newly stopped server requires a normal zero process exit;
+timeout, signal, non-zero or unknown results do not permit a planned backup.
+Previously inactive servers stay inactive, and failures must not be cleared
+to make the check pass. Even a successful shutdown does not cancel or prove
+completion of an already-issued guest-agent request. Existing guest/backup
+operations must finish normally, without new probes; unknown state, a disk
+dash, a cooldown or a waiting period is not completion evidence.
+
+`backupSafetyHelp.test.ts` verifies the rendered bounded state command, failure
+and in-flight gates, prior-state restoration and shipped mirror. This changes
+existing help, not service configuration, native shutdown/QGA recovery or
+release availability. The independent post-backup thaw/write/liveness and
+only-prior-active restoration boundary remains unchanged.
+
### Container backup-pause help preserves identity and prior state
The existing VM Disk Monitoring guide also covers a standalone Docker or plain
diff --git a/frontend-modern/public/docs/VM_DISK_MONITORING.md b/frontend-modern/public/docs/VM_DISK_MONITORING.md
index 09480663a1..aeddc4cabc 100644
--- a/frontend-modern/public/docs/VM_DISK_MONITORING.md
+++ b/frontend-modern/public/docs/VM_DISK_MONITORING.md
@@ -75,7 +75,8 @@ the systemd commands below do not stop a containerised Pulse server.
```bash
sudo systemctl stop pulse.service
- systemctl show pulse.service --property=LoadState,ActiveState,MainPID
+ systemctl show pulse.service \
+ --property=LoadState,ActiveState,MainPID,Result,ExecMainCode,ExecMainStatus
```
Require `LoadState=loaded`, `ActiveState=inactive` and `MainPID=0` after a
@@ -84,6 +85,21 @@ the systemd commands below do not stop a containerised Pulse server.
**Pulse monitoring and alerts are unavailable while stopped.** Do not run
an update, start another Pulse instance or reboot its host during the pause.
+ For a server stopped in this step, also require `Result=success`,
+ `ExecMainCode=1` (normal process exit) and `ExecMainStatus=0`. A timeout,
+ signal termination, non-zero exit or unavailable shutdown result needs
+ normal maintenance before the backup. Do not force-kill Pulse or clear its
+ failed state to satisfy this check. Leave a previously inactive server
+ inactive; an old exit result is not evidence of a new shutdown.
+
+ **Stopping Pulse does not cancel a guest-agent request already issued.**
+ Even a successful process exit does not prove that an earlier request
+ finished inside Proxmox or the guest. Let existing guest/backup operations
+ finish normally before the planned backup, using your established task and
+ workload checks, not new guest-agent probes. If their state is unknown,
+ do not start the backup on the strength of a stopped service or an arbitrary
+ waiting period. A disk dash or cooldown is not evidence of completion.
+
4. **Verify the guest independently, then restore only what you paused.**
Keep Pulse stopped until the backup has ended **and** your established
guest-console or workload checks confirm all three: **thaw**, **fresh successful
diff --git a/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts b/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts
index e903009c48..2c5482a816 100644
--- a/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts
+++ b/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts
@@ -168,7 +168,7 @@ describe('manual backup safety help', () => {
'systemctl show pulse.service --property=LoadState,ActiveState,MainPID',
'systemctl show pulse-update.timer --property=LoadState,ActiveState',
'sudo systemctl stop pulse-update.timer\nsystemctl show pulse-update.timer pulse-update.service \\\n --property=Id,LoadState,ActiveState,MainPID',
- 'sudo systemctl stop pulse.service\nsystemctl show pulse.service --property=LoadState,ActiveState,MainPID',
+ 'sudo systemctl stop pulse.service\nsystemctl show pulse.service \\\n --property=LoadState,ActiveState,MainPID,Result,ExecMainCode,ExecMainStatus',
'sudo systemctl start pulse.service\nsystemctl is-active pulse.service',
'sudo systemctl start pulse-update.timer\nsystemctl is-active pulse-update.timer',
]);
@@ -191,6 +191,29 @@ describe('manual backup safety help', () => {
expect(words).toContain('repeat the precaution for each affected backup window');
});
+ it('checks the new shutdown result without clearing failure or starting a previously inactive server', () => {
+ const text = render(section, 'VM_DISK_MONITORING').textContent?.replace(/\s+/g, ' ');
+ expect(read('frontend-modern/public/docs/VM_DISK_MONITORING.md')).toBe(guide);
+ expect(text).toContain('For a server stopped in this step');
+ expect(text).toContain('Result=success');
+ expect(text).toContain('ExecMainCode=1 (normal process exit)');
+ expect(text).toContain('ExecMainStatus=0');
+ expect(text).toContain('signal termination, non-zero exit or unavailable shutdown result');
+ expect(text).toContain('Do not force-kill Pulse or clear its failed state');
+ expect(text).toContain('an old exit result is not evidence of a new shutdown');
+ });
+
+ it('does not equate a stopped service or waiting period with completion of an issued guest request', () => {
+ const text = render(section, 'VM_DISK_MONITORING').textContent?.replace(/\s+/g, ' ');
+ expect(text).toContain('Stopping Pulse does not cancel a guest-agent request already issued');
+ expect(text).toContain('Even a successful process exit does not prove');
+ expect(text).toContain('Let existing guest/backup operations finish normally before the planned backup');
+ expect(text).toContain('not new guest-agent probes');
+ expect(text).toContain('If their state is unknown, do not start the backup');
+ expect(text).toContain('a stopped service or an arbitrary waiting period');
+ expect(text).toContain('A disk dash or cooldown is not evidence of completion');
+ });
+
it('requires independent workload writes before restart, never merely an OK task or an open console', () => {
expect(words).toContain('Keep Pulse stopped until');
expect(words).toContain('fresh successful workload writes');