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.

Explain the typed helper's separate update lifecycle

pulse-triage[bot]b87c182407ef
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md
index 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, Diagnostics
run 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 Agents
Cloning an installed agent can copy its saved identity and credentials. Different
diff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.md
index 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, Diagnostics
run 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 Agents
Cloning an installed agent can copy its saved identity and credentials. Different
diff --git a/internal/agentupdate/helper_lifecycle_test.go b/internal/agentupdate/helper_lifecycle_test.go
new file mode 100644
index 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.go
index 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.py
new file mode 100644
index 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()