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.

Preserve agent recovery state when the saved server is unavailable

pulse-triage[bot]1fe3fab006c9
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 2a64440a3f..ced4188f9f 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -386,8 +386,16 @@ sudo systemctl disable --now pulse-agent.service
```
If the Pulse server is still reachable, use its generated uninstall command so
-the agent can deregister cleanly. Otherwise, stopping the service is the safe
-first step before platform-local cleanup.
+the agent can deregister cleanly. If it is unreachable or the saved server URL
+is missing, **stopping retries is not completed removal or credential
+revocation**. Keep the agent's saved identity, credentials, connection files and
+needed logs private and intact; do not reinstall, create a new token or delete
+state to bypass a removal refusal. Temporary loss of connectivity does not
+establish that the server is gone. Follow the
+[saved-state removal guidance](UNIFIED_AGENT.md#uninstall) before local cleanup;
+Unix credential-bearing removal needs confirmation from the same trusted Pulse
+instance. The stop command above is for systemd, not Windows or other service
+managers.
#### Filter Pulse's systemd journal by severity
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md
index b3b991e433..6833ce0997 100644
--- a/docs/UNIFIED_AGENT.md
+++ b/docs/UNIFIED_AGENT.md
@@ -936,8 +936,19 @@ On Linux systemd, full removal also tears down the separately installed action
runner and typed helper. If only remediation should stop, use the runner-only
path below instead. Unix removal with a known Pulse URL and an existing
collector credential requires authenticated server confirmation before local
-collector teardown. Missing connection state can leave only local removal;
-it is not proof that Pulse removed the record or revoked every credential.
+collector teardown. **Do not attempt removal if a collector credential remains
+but the saved Pulse URL is missing.** The current Unix installer refuses before
+stopping services or deleting local state. An older served or prepared script
+may not have this refusal; do not rerun uninstall to test it. Keep the saved
+identity, credentials and connection files; do not erase
+them to force a local-only removal. Recover the original connection state or
+provide `--url` for the **same trusted Pulse instance** to the inspected
+installer, without a token on the command line. A different server or a new
+token cannot confirm removal of the original record. Retry only after restoring
+that connection; keep certificate verification enabled.
+
+Credential-free Unix state can still be removed locally, but local cleanup is
+not proof that Pulse removed a server record or revoked every credential.
For Windows, use the [privately prepared PowerShell installer](#windows-powershell-run-as-administrator)
in an Administrator session, not the Unix script. Use the same prepared
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index 2a64440a3f..ced4188f9f 100644
--- a/frontend-modern/public/docs/TROUBLESHOOTING.md
+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md
@@ -386,8 +386,16 @@ sudo systemctl disable --now pulse-agent.service
```
If the Pulse server is still reachable, use its generated uninstall command so
-the agent can deregister cleanly. Otherwise, stopping the service is the safe
-first step before platform-local cleanup.
+the agent can deregister cleanly. If it is unreachable or the saved server URL
+is missing, **stopping retries is not completed removal or credential
+revocation**. Keep the agent's saved identity, credentials, connection files and
+needed logs private and intact; do not reinstall, create a new token or delete
+state to bypass a removal refusal. Temporary loss of connectivity does not
+establish that the server is gone. Follow the
+[saved-state removal guidance](UNIFIED_AGENT.md#uninstall) before local cleanup;
+Unix credential-bearing removal needs confirmation from the same trusted Pulse
+instance. The stop command above is for systemd, not Windows or other service
+managers.
#### Filter Pulse's systemd journal by severity
diff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.md
index b3b991e433..6833ce0997 100644
--- a/frontend-modern/public/docs/UNIFIED_AGENT.md
+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md
@@ -936,8 +936,19 @@ On Linux systemd, full removal also tears down the separately installed action
runner and typed helper. If only remediation should stop, use the runner-only
path below instead. Unix removal with a known Pulse URL and an existing
collector credential requires authenticated server confirmation before local
-collector teardown. Missing connection state can leave only local removal;
-it is not proof that Pulse removed the record or revoked every credential.
+collector teardown. **Do not attempt removal if a collector credential remains
+but the saved Pulse URL is missing.** The current Unix installer refuses before
+stopping services or deleting local state. An older served or prepared script
+may not have this refusal; do not rerun uninstall to test it. Keep the saved
+identity, credentials and connection files; do not erase
+them to force a local-only removal. Recover the original connection state or
+provide `--url` for the **same trusted Pulse instance** to the inspected
+installer, without a token on the command line. A different server or a new
+token cannot confirm removal of the original record. Retry only after restoring
+that connection; keep certificate verification enabled.
+
+Credential-free Unix state can still be removed locally, but local cleanup is
+not proof that Pulse removed a server record or revoked every credential.
For Windows, use the [privately prepared PowerShell installer](#windows-powershell-run-as-administrator)
in an Administrator session, not the Unix script. Use the same prepared
diff --git a/scripts/tests/test_agent_uninstall_docs.py b/scripts/tests/test_agent_uninstall_docs.py
index 04d5c64e76..9d15f2e294 100644
--- a/scripts/tests/test_agent_uninstall_docs.py
+++ b/scripts/tests/test_agent_uninstall_docs.py
@@ -31,6 +31,7 @@ def compact(value):
class AgentUninstallDocsTest(unittest.TestCase):
# Supports read-only actual-parent discrimination without editing source.
text = None
+ troubleshooting_text = None
def setUp(self):
self.help = section(self.text)
@@ -104,6 +105,51 @@ class AgentUninstallDocsTest(unittest.TestCase):
self.assertIn('[bool]$Uninstall = $false', (ROOT / "scripts/install.ps1").read_text())
self.assertNotIn('Remove-Item', self.help)
+ def test_missing_url_refusal_preserves_same_instance_recovery(self):
+ for fact in (
+ "Do not attempt removal if a collector credential remains but the saved Pulse URL is missing",
+ "current Unix installer refuses before stopping services or deleting local state",
+ "older served or prepared script may not have this refusal",
+ "do not rerun uninstall to test it",
+ "Keep the saved identity, credentials and connection files",
+ "do not erase them to force a local-only removal",
+ "provide `--url` for the same trusted Pulse instance",
+ "without a token on the command line",
+ "A different server or a new token cannot confirm removal of the original record",
+ "Retry only after restoring that connection",
+ "keep certificate verification enabled",
+ "Credential-free Unix state can still be removed locally",
+ ):
+ self.assertIn(fact, self.words)
+ # Bind the help to production admission, not a hypothetical policy.
+ admission = self.removal.split("if collector_credential_state_present; then", 1)[1]
+ missing_url = admission.split('if [[ -z "$PULSE_URL" ]]; then', 1)[1].split("\n fi", 1)[0]
+ self.assertIn("local credentials and services were retained", missing_url)
+ self.assertIn("same trusted Pulse instance", missing_url)
+ self.assertLess(admission.index("uninstall_collector_registration"),
+ admission.index("teardown_action_runner_service"))
+
+ def test_orphan_service_stop_is_not_destructive_cleanup_or_revocation(self):
+ text = self.troubleshooting_text
+ if text is None:
+ text = (ROOT / "docs/TROUBLESHOOTING.md").read_text()
+ heading = "#### Removed Pulse server but `pulse-agent` still logs connection failures\n"
+ advice = text.split(heading, 1)[1].split("\n#### ", 1)[0]
+ for fact in (
+ "stopping retries is not completed removal or credential revocation",
+ "saved identity, credentials, connection files and needed logs private and intact",
+ "do not reinstall, create a new token or delete state",
+ "Temporary loss of connectivity does not establish that the server is gone",
+ "UNIFIED_AGENT.md#uninstall",
+ "confirmation from the same trusted Pulse instance",
+ "systemd, not Windows or other service managers",
+ ):
+ self.assertIn(fact, compact(advice))
+ commands = re.findall(r"```bash\n(.*?)```", advice, re.DOTALL)
+ self.assertEqual(commands, ["sudo systemctl disable --now pulse-agent.service\n"])
+ self.assertEqual((ROOT / "frontend-modern/public/docs/TROUBLESHOOTING.md").read_bytes(),
+ (ROOT / "docs/TROUBLESHOOTING.md").read_bytes())
+
def test_copied_unix_commands_select_only_the_requested_route_and_keep_failures(self):
commands = re.findall(r"```bash\n(.*?)```", self.help, re.DOTALL)
self.assertEqual(len(commands), 2)