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
Retain Unix agent credentials when the saved server URL is missing
pulse-triage[bot]03b8808c045c
diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.mdindex 5bdce283b9..b8355cfbee 100644--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md@@ -15,6 +15,29 @@## Purpose+### Unix removal retains credentials when connection recovery is incomplete++After existing installed-state recovery, the unified Unix installer checks for+collector credentials before considering whether a Pulse URL was recovered.+Any inline credential or selected/runtime/legacy/helper token-file entry,+including an empty or unreadable file, broken symlink or FIFO, requires+an authenticated exact-record removal confirmation before local teardown.+A missing URL fails with a credential-safe same-instance recovery message;+it cannot turn credential-bearing removal into the local-only path. No+transport request, process stop, service stop or state deletion follows that+refusal. Server refusal, unknown confirmation and identity mismatch retain+state as before; confirmation does not widen trusted path-removal authority.+Credential-free removal remains local-only, with or without a saved URL.++`TestInstallSHUninstallRetainsCredentialsWhenSavedURLIsMissing` runs the+production admission, credential-presence, record-confirmation and initial+state-directory cleanup functions through `agent_uninstall_state.py`. Its+seventeen confined cases use private files and service/transport doubles,+not a privileged installer or native service manager. These checks do not+establish Windows, actual TLS, saved-state discovery, a published fix or+whole-issue installed removal acceptance.++### Selected agent credential files retain their own authorityThe real agent flag-loading path resolves a non-empty explicit `--token` beforediff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.mdindex c85ff3cd20..1017f993b5 100644--- a/docs/release-control/v6/internal/subsystems/deployment-installability.md+++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md@@ -15,6 +15,29 @@## Purpose+### Unix removal retains credentials when connection recovery is incomplete++After existing installed-state recovery, the unified Unix installer checks for+collector credentials before considering whether a Pulse URL was recovered.+Any inline credential or selected/runtime/legacy/helper token-file entry,+including an empty or unreadable file, broken symlink or FIFO, requires+an authenticated exact-record removal confirmation before local teardown.+A missing URL fails with a credential-safe same-instance recovery message;+it cannot turn credential-bearing removal into the local-only path. No+transport request, process stop, service stop or state deletion follows that+refusal. Server refusal, unknown confirmation and identity mismatch retain+state as before; confirmation does not widen trusted path-removal authority.+Credential-free removal remains local-only, with or without a saved URL.++`TestInstallSHUninstallRetainsCredentialsWhenSavedURLIsMissing` runs the+production admission, credential-presence, record-confirmation and initial+state-directory cleanup functions through `agent_uninstall_state.py`. Its+seventeen confined cases use private files and service/transport doubles,+not a privileged installer or native service manager. These checks do not+establish Windows, actual TLS, saved-state discovery, a published fix or+whole-issue installed removal acceptance.++### Docker server update plans preserve the saved deploymentThe existing update-plan API and banner's copyable instructions must not guessdiff --git a/scripts/install.sh b/scripts/install.shindex 2902338145..9ed853a20f 100755--- a/scripts/install.sh+++ b/scripts/install.sh@@ -5533,7 +5533,10 @@ if [[ "$UNINSTALL" == "true" ]]; then# A credential-bearing install must durably remove its exact server record# through the same CA/fingerprint/no-proxy transport used by lifecycle# migration before any local credential or service state is deleted.- if [[ -n "$PULSE_URL" ]] && collector_credential_state_present; then+ if collector_credential_state_present; then+ if [[ -z "$PULSE_URL" ]]; then+ fail "The saved Pulse URL is missing; local credentials and services were retained. Restore saved connection state or provide --url for the same trusted Pulse instance and retry uninstall." "$EXIT_MISSING_ARGS"+ filog_info "Authenticating Pulse server removal before local teardown..."if ! uninstall_collector_registration; thenfail "Pulse did not durably confirm collector removal; local credentials and services were retained. Restore trusted server connectivity and retry uninstall." "$EXIT_GENERAL"diff --git a/scripts/installtests/agent_uninstall_state.py b/scripts/installtests/agent_uninstall_state.pynew file mode 100644index 0000000000..530f5c4693--- /dev/null+++ b/scripts/installtests/agent_uninstall_state.py@@ -0,0 +1,174 @@+#!/usr/bin/env python3+"""Execute the Unix uninstall admission and initial teardown, not a root installer.++Production credential detection, record confirmation and directory-authority+functions remain intact. Only transport and service/process operations are+private doubles; deletion is confined to three owned temporary directories.+These controls are not native installation, TLS or provider acceptance.+"""++import os+from pathlib import Path+import shlex+import stat+import subprocess+import tempfile+import unittest++ROOT = Path(__file__).resolve().parents[2]+SOURCE = Path(os.environ.get("PULSE_AGENT_UNINSTALL_SOURCE", ROOT / "scripts/install.sh"))+++def function(source, name):+ return name + "() {" + source.split(name + "() {", 1)[1].split("\n}\n", 1)[0] + "\n}\n"+++def snapshot(root):+ result = {}+ for path in sorted(root.rglob("*")):+ if path.name == "events":+ continue+ mode = path.lstat().st_mode+ payload = os.readlink(path) if stat.S_ISLNK(mode) else (+ path.read_bytes() if stat.S_ISREG(mode) and mode & stat.S_IRUSR else None)+ result[str(path.relative_to(root))] = (mode, payload, path.lstat().st_size, path.lstat().st_ino)+ return result+++class UnixUninstallState(unittest.TestCase):+ source = SOURCE.read_text()++ def exercise(self, credential="runtime", url="", reply="confirmed", authority=True):+ source = self.source+ # Keep the real entry and all initial credential/service/state teardown.+ # Stop before unrelated platform boot/log cleanup; never run it on a host.+ entry = source.split("# --- Uninstall Logic ---\n", 1)[1].split(+ " # Remove least-privilege helper artifacts.", 1)[0] + "fi\n"+ names = ("collector_credential_state_present", "uninstall_collector_registration",+ "remove_authorized_runtime_dir", "remove_agent_state_dir",+ "remove_privileged_helper_state_dir", "remove_safe_profile_state_dir", "fail")+ with tempfile.TemporaryDirectory() as temporary:+ root = Path(temporary)+ state, helper, profile = (root / name for name in ("state", "helper", "profile"))+ for directory in (state, helper, profile):+ directory.mkdir(mode=0o700)+ (directory / "identity").write_text("owned-instance\n")+ (state / "connection.env").write_text("PULSE_AGENT_ID='owned-agent'\n")+ (state / "agent-id").write_text("owned-agent\n")+ service = root / "service"+ service.write_text("active\n")+ (root / "unrelated").write_text("do not change\n")+ token = ""+ selected = root / "selected-token"+ if credential == "inline":+ token = "synthetic-collector-credential"+ elif credential != "none":+ path = {"legacy": state / "token", "selected": selected,+ "helper": helper / "token"}.get(credential, state / "runtime.token")+ if credential == "broken-link":+ path.symlink_to(root / "missing-token")+ elif credential == "fifo":+ os.mkfifo(path, 0o600)+ else:+ path.write_text("" if credential == "empty" else "synthetic-collector-credential\n")+ path.chmod(0 if credential == "unreadable" else 0o600)+ before = snapshot(root)+ values = {"STATE_DIR": state, "PRIVILEGED_HELPER_STATE_DIR": helper,+ "PRIVILEGED_HELPER_CREDENTIAL_DIR": helper, "SAFE_PROFILE_STATE_DIR": profile,+ "STATE_DIR_REMOVAL_AUTHORITY": state if authority else "",+ "PRIVILEGED_HELPER_STATE_DIR_REMOVAL_AUTHORITY": helper,+ "SAFE_PROFILE_STATE_DIR_REMOVAL_AUTHORITY": profile,+ "PULSE_TOKEN": token, "RUNTIME_TOKEN_FILE": selected,+ "PULSE_URL": url, "AGENT_ID": "owned-agent", "HOSTNAME_OVERRIDE": "owned-host",+ "EVENTS": root / "events", "SERVICE": service, "REPLY": reply}+ setup = "\n".join(f"{key}={shlex.quote(str(value))}" for key, value in values.items())+ functions = "\n".join(function(source, name) for name in names)+ # A whitelist protects the fixture even if production cleanup changes.+ shell = r'''+set -euo pipefail+UNINSTALL=true AGENT_NAME=pulse-agent EXIT_GENERAL=1 EXIT_MISSING_ARGS=16+OUTPUT_FORMAT=text NON_INTERACTIVE=true+log_info() { :; }+log_warn() { printf 'warning:%s\n' "$*"; }+log_error() { printf 'error:%s\n' "$*"; }+recover_agent_id_from_state_file() { printf 'owned-agent\n'; }+run_collector_lifecycle_command() {+ printf 'request:%s\n' "$*" >> "$EVENTS"+ case "$REPLY" in+ confirmed) printf 'owned-agent\n' ;;+ mismatch) printf 'different-agent\n' ;;+ empty) : ;;+ refused|lost-response) return 1 ;;+ *) return 90 ;;+ esac+}+pkill() { printf 'process-stop\n' >> "$EVENTS"; }+sleep() { :; }+systemctl() { return 91; }+teardown_action_runner_service() { printf 'runner-stop\n' >> "$EVENTS"; }+teardown_privileged_helper_service() { printf 'helper-stop\n' >> "$EVENTS"; }+teardown_systemd_agent_service() { printf 'service-stop\n' >> "$EVENTS"; printf 'stopped\n' > "$SERVICE"; }+rm() {+ [[ $# == 3 && "$1" == -rf && "$2" == -- ]] || return 92+ [[ "$3" == "$STATE_DIR" || "$3" == "$PRIVILEGED_HELPER_STATE_DIR" || "$3" == "$SAFE_PROFILE_STATE_DIR" ]] || return 93+ printf 'state-remove\n' >> "$EVENTS"+ command rm "$@"+}+'''+ result = subprocess.run(["bash", "-c", shell + "\n" + setup + "\n" + functions ++ "\nmain() {\n" + entry + "}\nmain\n"],+ capture_output=True, text=True, timeout=5)+ events = (root / "events").read_text() if (root / "events").exists() else ""+ after = snapshot(root)+ return result, events, before, after++ def test_missing_url_retains_every_credential_representation_without_a_request(self):+ for kind in ("inline", "runtime", "legacy", "selected", "helper", "empty",+ "unreadable", "broken-link", "fifo"):+ with self.subTest(credential=kind):+ result, events, before, after = self.exercise(kind)+ self.assertEqual(result.returncode, 16, result.stderr)+ self.assertIn("same trusted Pulse instance", result.stdout)+ self.assertNotIn("synthetic-collector-credential", result.stdout + result.stderr)+ self.assertEqual(events, "")+ self.assertEqual(after, before)++ def test_server_refusal_unknown_or_other_identity_retains_service_and_state(self):+ for reply in ("refused", "lost-response", "empty", "mismatch"):+ with self.subTest(reply=reply):+ result, events, before, after = self.exercise(url="https://pulse.invalid", reply=reply)+ self.assertEqual(result.returncode, 1, result.stderr)+ self.assertEqual(events, "request:collector-uninstall --agent-id owned-agent --hostname owned-host\n")+ self.assertEqual(after, before)++ def test_exact_confirmation_precedes_process_service_and_state_teardown(self):+ result, events, before, after = self.exercise(url="https://pulse.invalid")+ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertEqual(events.splitlines(), [+ "request:collector-uninstall --agent-id owned-agent --hostname owned-host",+ "process-stop", "process-stop", "runner-stop", "helper-stop", "service-stop",+ "state-remove", "state-remove", "state-remove"])+ self.assertEqual(set(after), {"service", "unrelated"})+ self.assertEqual(after["service"][1], b"stopped\n")+ self.assertEqual(after["unrelated"], before["unrelated"])++ def test_credential_free_local_only_removal_needs_no_url_or_request(self):+ for url in ("", "https://pulse.invalid"):+ with self.subTest(url=url):+ result, events, before, after = self.exercise("none", url=url)+ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertNotIn("request:", events)+ self.assertEqual(set(after), {"service", "unrelated"})+ self.assertEqual(after["unrelated"], before["unrelated"])++ def test_server_confirmation_does_not_grant_unknown_path_removal(self):+ result, events, before, after = self.exercise(url="https://pulse.invalid", authority=False)+ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertEqual(events.count("state-remove\n"), 2)+ self.assertIn("without exact trusted lifecycle authority", result.stdout)+ for name in ("state", "state/runtime.token", "state/agent-id", "state/connection.env"):+ self.assertEqual(after[name], before[name])+++if __name__ == "__main__":+ unittest.main()diff --git a/scripts/installtests/install_sh_test.go b/scripts/installtests/install_sh_test.goindex 2acfad95e3..d1de72ef47 100644--- a/scripts/installtests/install_sh_test.go+++ b/scripts/installtests/install_sh_test.go@@ -8259,3 +8259,30 @@ func TestInstallSHLegacyAgentIDRecoveryAccountsForEveryByte(t *testing.T) {})}}++// Run the production Unix removal gate through private state/service/transport+// doubles. Native platform installation and actual transport remain separate.+func TestInstallSHUninstallRetainsCredentialsWhenSavedURLIsMissing(t *testing.T) {+ ctx, cancel := context.WithTimeout(context.Background(), time.Minute)+ defer cancel()+ cmd := exec.CommandContext(ctx, "python3", repoFile("scripts", "installtests", "agent_uninstall_state.py"), "-v")+ output, err := cmd.CombinedOutput()+ if err != nil {+ t.Fatalf("Unix removal state controls: %v\n%s", err, output)+ }+ for _, name := range []string{+ "test_missing_url_retains_every_credential_representation_without_a_request",+ "test_server_refusal_unknown_or_other_identity_retains_service_and_state",+ "test_exact_confirmation_precedes_process_service_and_state_teardown",+ "test_credential_free_local_only_removal_needs_no_url_or_request",+ "test_server_confirmation_does_not_grant_unknown_path_removal",+ } {+ if !strings.Contains(string(output), name+" (__main__.UnixUninstallState."+name+") ... ok") {+ t.Fatalf("Unix removal control %s did not pass:\n%s", name, output)+ }+ }+ if !strings.Contains(string(output), "\nRan 5 tests in ") || !strings.Contains(string(output), "\nOK\n") {+ t.Fatalf("incomplete Unix removal state verdict:\n%s", output)+ }+ t.Logf("%s", output)+}