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
Explain the typed helper's separate update lifecycle
pulse-triage[bot]b87c182407ef
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.mdindex ea750a7344..18a7916a4b 100644--- a/docs/UNIFIED_AGENT.md+++ b/docs/UNIFIED_AGENT.md@@ -1485,6 +1485,60 @@ including recovery already performed. Keep tokens, full copied commands,connection files and service environments private. No new update, Diagnosticsrun or full configuration export is required to ask for help.+### Updating the typed helper++**Automatic agent updates replace the collector only.** They do not replace or+restart `pulse-agent-helper`. A successful collector update, including a fresh+version in Agent Doctor, does not establish the helper's release version. The+helper is shipped with Pulse, not on a separate release schedule, but its+installation is managed separately by the agent installer.++The helper's health check confirms the requested protocol, not release-version+parity or support for every collector operation. The helper currently has no+`--version` option. Do not infer its version from `pulse-agent --version`, or+treat a healthy older helper as a monitoring failure solely because the+collector updated. Existing LXC or SMART readings remain separate evidence.++For a **planned helper update on a standard Linux systemd host**:++1. Update the trusted Pulse instance first. On the **affected agent host**,+ download and inspect its current `/install.sh` using the+ [HTTPS preparation above](#private-file-installation-linux-macos-and-nas).+ Keep any previous installer separately; do not execute a temporary failed+ download or overwrite an existing copy blindly. No new token is needed for+ an update using saved connection state. Do not substitute GitHub's top-level+ `install.sh`, which updates the Pulse server instead.+2. Run preflight with that inspected agent installer, then apply only if it+ succeeds and the host is ready for a brief monitoring interruption:++ ```bash+ sudo bash "$HOME/.config/pulse/agent-install.sh" --preflight-only --update+ ```++ ```bash+ sudo bash "$HOME/.config/pulse/agent-install.sh" --update+ ```++ `--update` recovers the saved connection, identity, collectors and existing+ least-privilege/typed-helper profile; it does not require those profile flags+ again. The installer verifies the collector and helper downloads, replaces+ their binaries, checks the helper's effective isolated unit and socket, and+ restarts the helper. Preflight is not installation or proof of recovery.+3. Check the install result and fresh reporting from that same host, including+ any LXC or SMART readings you rely on. Collector success alone still does+ not prove the helper was replaced. If the helper release must be established,+ compare its installed file's SHA-256 with the matching architecture's helper+ entry in that release's verified `checksums.txt`; a file digest does not+ establish which executable a pre-existing process is running.++Do not uninstall, re-enrol, copy a helper binary by hand, remove+`PrivateNetwork`, add sudo grants or change the collector's service user to+force an update. If preflight or installation fails, retain its existing+redacted error and reconcile installed state before another attempt. Never+publish tokens, connection files or full service configuration. This procedure+is a deliberate maintenance operation, not a diagnostic retest request for a+healthy host.+### Duplicate AgentsCloning an installed agent can copy its saved identity and credentials. Differentdiff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.mdindex ea750a7344..18a7916a4b 100644--- a/frontend-modern/public/docs/UNIFIED_AGENT.md+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md@@ -1485,6 +1485,60 @@ including recovery already performed. Keep tokens, full copied commands,connection files and service environments private. No new update, Diagnosticsrun or full configuration export is required to ask for help.+### Updating the typed helper++**Automatic agent updates replace the collector only.** They do not replace or+restart `pulse-agent-helper`. A successful collector update, including a fresh+version in Agent Doctor, does not establish the helper's release version. The+helper is shipped with Pulse, not on a separate release schedule, but its+installation is managed separately by the agent installer.++The helper's health check confirms the requested protocol, not release-version+parity or support for every collector operation. The helper currently has no+`--version` option. Do not infer its version from `pulse-agent --version`, or+treat a healthy older helper as a monitoring failure solely because the+collector updated. Existing LXC or SMART readings remain separate evidence.++For a **planned helper update on a standard Linux systemd host**:++1. Update the trusted Pulse instance first. On the **affected agent host**,+ download and inspect its current `/install.sh` using the+ [HTTPS preparation above](#private-file-installation-linux-macos-and-nas).+ Keep any previous installer separately; do not execute a temporary failed+ download or overwrite an existing copy blindly. No new token is needed for+ an update using saved connection state. Do not substitute GitHub's top-level+ `install.sh`, which updates the Pulse server instead.+2. Run preflight with that inspected agent installer, then apply only if it+ succeeds and the host is ready for a brief monitoring interruption:++ ```bash+ sudo bash "$HOME/.config/pulse/agent-install.sh" --preflight-only --update+ ```++ ```bash+ sudo bash "$HOME/.config/pulse/agent-install.sh" --update+ ```++ `--update` recovers the saved connection, identity, collectors and existing+ least-privilege/typed-helper profile; it does not require those profile flags+ again. The installer verifies the collector and helper downloads, replaces+ their binaries, checks the helper's effective isolated unit and socket, and+ restarts the helper. Preflight is not installation or proof of recovery.+3. Check the install result and fresh reporting from that same host, including+ any LXC or SMART readings you rely on. Collector success alone still does+ not prove the helper was replaced. If the helper release must be established,+ compare its installed file's SHA-256 with the matching architecture's helper+ entry in that release's verified `checksums.txt`; a file digest does not+ establish which executable a pre-existing process is running.++Do not uninstall, re-enrol, copy a helper binary by hand, remove+`PrivateNetwork`, add sudo grants or change the collector's service user to+force an update. If preflight or installation fails, retain its existing+redacted error and reconcile installed state before another attempt. Never+publish tokens, connection files or full service configuration. This procedure+is a deliberate maintenance operation, not a diagnostic retest request for a+healthy host.+### Duplicate AgentsCloning an installed agent can copy its saved identity and credentials. Differentdiff --git a/internal/agentupdate/helper_lifecycle_test.go b/internal/agentupdate/helper_lifecycle_test.gonew file mode 100644index 0000000000..62457fb72f--- /dev/null+++ b/internal/agentupdate/helper_lifecycle_test.go@@ -0,0 +1,72 @@+package agentupdate++import (+ "bytes"+ "context"+ "encoding/json"+ "strings"+ "testing"++ "github.com/rs/zerolog"+)++func TestRunLoopExplainsSeparateHelperLifecycleWithoutChangingHealth(t *testing.T) {+ for _, tc := range []struct {+ name string+ helper bool+ disabled bool+ version string+ wantNote bool+ }{+ {name: "typed_helper", helper: true, version: "v6.7.0", wantNote: true},+ {name: "ordinary_collector", version: "v6.7.0"},+ {name: "disabled", helper: true, disabled: true, version: "v6.7.0"},+ {name: "development", helper: true, version: "dev"},+ } {+ t.Run(tc.name, func(t *testing.T) {+ var output bytes.Buffer+ logger := zerolog.New(&output)+ cfg := Config{CurrentVersion: tc.version, Disabled: tc.disabled, Logger: &logger,+ PulseURL: "https://example.invalid", APIToken: "must-not-be-logged"}+ helper := &fakePrivilegedUpdate{root: t.TempDir()}+ if tc.helper {+ cfg.PrivilegedUpdate = helper+ }+ u := New(cfg)+ before := u.Snapshot()+ ctx, cancel := context.WithCancel(context.Background())+ cancel() // Reach startup output without a network check or a mutation.+ u.RunLoop(ctx)+ if got := u.Snapshot(); got.State != before.State || got.LastError != before.LastError || got.LastAttemptAt != nil {+ t.Fatalf("lifecycle explanation changed updater health: before=%+v after=%+v", before, got)+ }+ if len(helper.events) != 0 || strings.Contains(output.String(), cfg.APIToken) {+ t.Fatalf("startup explanation invoked helper or disclosed credential: events=%v", helper.events)+ }+ notes := 0+ decoder := json.NewDecoder(&output)+ for decoder.More() {+ var event map[string]any+ if err := decoder.Decode(&event); err != nil {+ t.Fatal(err)+ }+ if event["update_scope"] != "collector-only" {+ continue+ }+ notes+++ message, _ := event["message"].(string)+ if event["level"] != "info" || !strings.Contains(message, "agent installer --update") ||+ event["helper_update_guide"] != "https://github.com/rcourtman/Pulse/blob/main/docs/UNIFIED_AGENT.md#updating-the-typed-helper" {+ t.Fatalf("missing actionable helper lifecycle: %+v", event)+ }+ }+ want := 0+ if tc.wantNote {+ want = 1+ }+ if notes != want {+ t.Fatalf("helper lifecycle notes = %d, want %d", notes, want)+ }+ })+ }+}diff --git a/internal/agentupdate/update.go b/internal/agentupdate/update.goindex e1ef4b7e3b..e8bc025702 100644--- a/internal/agentupdate/update.go+++ b/internal/agentupdate/update.go@@ -315,6 +315,16 @@ func (u *Updater) RunLoop(ctx context.Context) {return}+ if u.cfg.PrivilegedUpdate != nil {+ // The closed helper protocol replaces the collector, not the root+ // helper itself. State this once per loop, before any update check,+ // without treating an unmeasured helper version as a health failure.+ u.logger.Info().+ Str("update_scope", "collector-only").+ Str("helper_update_guide", "https://github.com/rcourtman/Pulse/blob/main/docs/UNIFIED_AGENT.md#updating-the-typed-helper").+ Msg("Automatic updates replace pulse-agent only, not the typed privilege helper; use the agent installer --update for a separate helper update")+ }+// Initial check after a short delay (5s to quickly update outdated agents)initialDelayTimer := time.NewTimer(u.initialDelay)defer func() {diff --git a/scripts/tests/test_agent_helper_update_docs.py b/scripts/tests/test_agent_helper_update_docs.pynew file mode 100644index 0000000000..884bc638b5--- /dev/null+++ b/scripts/tests/test_agent_helper_update_docs.py@@ -0,0 +1,87 @@+#!/usr/bin/env python3+"""Exercise the documented helper-update commands without root or services."""++import json+import os+from pathlib import Path+import re+import subprocess+import tempfile+import unittest+++ROOT = Path(__file__).resolve().parents[2]+++class AgentHelperUpdateDocsTest(unittest.TestCase):+ def setUp(self):+ self.document = (ROOT / "docs/UNIFIED_AGENT.md").read_text()+ self.section = self.document.split("### Updating the typed helper\n", 1)[1].split(+ "\n### ", 1+ )[0]++ def test_copyable_commands_keep_saved_profile_and_preflight_separate(self):+ commands = re.findall(r"```bash\n(.*?)\n\s*```", self.section, re.S)+ self.assertEqual(len(commands), 2)+ # A recorder stands in for sudo; neither root nor the real installer is+ # executed. Spaces in HOME must survive both copied commands unchanged.+ with tempfile.TemporaryDirectory(prefix="helper update docs ") as tmp:+ root = Path(tmp)+ bin_dir = root / "bin"+ bin_dir.mkdir()+ sudo = bin_dir / "sudo"+ sudo.write_text(+ "#!/usr/bin/env python3\n"+ "import json, os, sys\n"+ "with open(os.environ['CALLS'], 'a') as out:\n"+ " out.write(json.dumps(sys.argv[1:]) + '\\n')\n"+ )+ sudo.chmod(0o700)+ calls = root / "calls.jsonl"+ env = {**os.environ, "HOME": str(root / "home with spaces"),+ "PATH": str(bin_dir) + os.pathsep + os.environ["PATH"],+ "CALLS": str(calls)}+ for command in commands:+ subprocess.run(["bash", "--noprofile", "--norc", "-eu", "-c", command],+ env=env, check=True, capture_output=True, text=True)+ observed = [json.loads(line) for line in calls.read_text().splitlines()]+ installer = str(root / "home with spaces/.config/pulse/agent-install.sh")+ self.assertEqual(observed, [+ ["bash", installer, "--preflight-only", "--update"],+ ["bash", installer, "--update"],+ ])++ def test_guidance_separates_versions_and_preserves_actual_boundaries(self):+ text = " ".join(self.section.split())+ for required in (+ "Automatic agent updates replace the collector only.",+ "do not replace or restart `pulse-agent-helper`",+ "does not establish the helper's release version",+ "health check confirms the requested protocol",+ "no `--version` option",+ "No new token is needed",+ "Preflight is not installation or proof of recovery",+ "least-privilege/typed-helper profile",+ "effective isolated unit and socket",+ "Do not uninstall, re-enrol",+ "remove `PrivateNetwork`",+ "not a diagnostic retest request for a healthy host",+ ):+ with self.subTest(required=required):+ self.assertIn(required, text)+ self.assertEqual((ROOT / "frontend-modern/public/docs/UNIFIED_AGENT.md").read_bytes(),+ (ROOT / "docs/UNIFIED_AGENT.md").read_bytes())+ helper_flags = (ROOT / "cmd/pulse-agent-helper/main.go").read_text().split(+ "func parseFlags(", 1)[1].split("\nfunc ", 1)[0]+ self.assertNotRegex(helper_flags, r'\.(?:Bool|String)\("version"')+ # Keep the procedure attached to the real installer option, not the+ # similarly named public server installer or an invented helper flag.+ installer = (ROOT / "scripts/install.sh").read_text()+ self.assertIn('--update) UPDATE_ONLY="true"; shift ;;', installer)+ self.assertIn('recover_connection_state "$lifecycle_conn_env"', installer)+ self.assertIn('verify_download_signature "$TMP_HELPER_BIN" "$helper_signature"', installer)+ self.assertIn('provision_typed_privileged_helper', installer)+++if __name__ == "__main__":+ unittest.main()