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
Preserve agent recovery state when the saved server is unavailable
pulse-triage[bot]1fe3fab006c9
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 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 severitydiff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.mdindex 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 actionrunner and typed helper. If only remediation should stop, use the runner-onlypath below instead. Unix removal with a known Pulse URL and an existingcollector 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 prepareddiff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.mdindex 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 severitydiff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.mdindex 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 actionrunner and typed helper. If only remediation should stop, use the runner-onlypath below instead. Unix removal with a known Pulse URL and an existingcollector 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 prepareddiff --git a/scripts/tests/test_agent_uninstall_docs.py b/scripts/tests/test_agent_uninstall_docs.pyindex 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 = Nonedef 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)