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.

Clarify legacy monitoring credentials and separate runner recovery help

pulse-triage[bot]d1c93855ff28
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 05414793dd..17f3903460 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -326,16 +326,40 @@ grants exec` describe local authority and credential scope, **not a connected
session**. A missing Privilege line is unknown, not proof that commands are off.
Fresh monitoring or an available image update does not prove command transport.
-For a command-capable host, follow the existing
+`root` identifies the collector's OS user, not its server-side permission.
+`commands legacy` identifies an older, unmarked compatibility profile; it does
+not establish that commands are enabled. `monitoring credential` means the
+known collector credential has no execution scope and cannot authenticate the
+legacy command channel. Do not add execution rights to that token as a repair.
+
+Inspect **Action runner** separately. `Credential not issued` and `Runner not
+connected` describe the separate typed runner, not monitoring health. An absent
+runner alone does not rule out an authorised legacy command connection. If
+**Safe collector not confirmed** is shown, that is not proof of a broken
+collector or permission to convert it merely to clear the update error.
+
+For a command-enabled, execution-scoped legacy connection, follow the existing
[command-channel connection and admission checks](UNIFIED_AGENT.md#commands-enabled-but-remote-control-blocked).
A monitoring-only setup is intentional when you only need readings and update
detection; do not enable commands, broaden a token, change Proxmox permissions
or loosen TLS merely to diagnose the refusal. Keep saved identity and credentials
intact; do not reinstall or retry the workload update as a connection test.
+You can keep working monitoring and manage any needed update through your usual
+Docker or Podman administration tool, after checking the workload's existing
+image/state and recovery path. Deliberately opting into Pulse-managed changes
+is a separate trust decision: the
+[agent privilege model](AGENT_SECURITY.md#agent-privilege-model) explains the
+legacy combined command profile, and the
+[least-privilege profile](AGENT_SECURITY.md#least-privilege-agent-profile)
+describes the supported separate runner. Neither is a diagnostic prerequisite;
+do not change a working profile just to obtain evidence.
+
For help, retain the original error, time and stage plus the existing command
-authority/scope wording, or say it is unavailable. Share only those distinctions,
-not a full Agent Doctor report, token hint, agent ID or service configuration.
+authority/scope and Action runner wording, or say it is unavailable. If relevant,
+say whether command execution was deliberately selected at installation;
+unknown is valid. Share only those distinctions, not a full Agent Doctor report,
+token hint, agent ID or service configuration.
The connection refusal does not settle an earlier missing receipt.
#### Action was sent or its outcome is unknown
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md
index b7eb55ca73..76c916541b 100644
--- a/docs/UNIFIED_AGENT.md
+++ b/docs/UNIFIED_AGENT.md
@@ -1385,8 +1385,23 @@ monitoring report or **Automatic updates ready** also does not prove that this
separate WebSocket channel is working. Changing Proxmox API permissions cannot
repair a Pulse command-channel connection.
+Before treating this as a connection failure, read the existing **Privilege**
+and **Action runner** lines. `root` is the collector's OS user; `commands legacy`
+is a compatibility profile, not proof that commands are enabled. A
+`monitoring credential` cannot authenticate the legacy command channel.
+`Credential not issued` or `Runner not connected` concerns the separate typed
+runner, not collector health; an absent runner alone does not exclude an
+authorised legacy command connection. Use the
+[workload-update authority guidance](DOCKER.md#command-agent-is-not-connected)
+to distinguish these cases without widening a token or converting the collector.
+Keep an intentionally monitoring-only installation unchanged. Choosing an
+execution-capable installation is a separate trust decision, not a connection
+test; remember whether that choice was made, or say it is unknown.
+
For a systemd agent, inspect the recent journal **locally on the affected node**
-with the [bounded agent log reader](#collect-agent-logs-safely).
+with the [bounded agent log reader](#collect-agent-logs-safely) only when an
+authorised command connection was intended and its failure stage is still
+unknown. Do not collect more logs just to confirm the known monitoring scope.
Look for **Connected and registered with Pulse command server**, or
**WebSocket connection failed repeatedly, reconnecting** and its error. A
diff --git a/frontend-modern/browser-tests/docker-update-guidance.cjs b/frontend-modern/browser-tests/docker-update-guidance.cjs
index a820270495..f035f7500f 100644
--- a/frontend-modern/browser-tests/docker-update-guidance.cjs
+++ b/frontend-modern/browser-tests/docker-update-guidance.cjs
@@ -139,7 +139,38 @@ const { chromium, webkit } = require('playwright');
dispatchEvent(new PopStateEvent('popstate'));
});
await waitForHeading('command-agent-is-not-connected');
+ const authorityGuide = (await page.locator('article').innerText()).replace(/\s+/g, ' ');
+ for (const phrase of [
+ "root identifies the collector's OS user, not its server-side permission",
+ 'commands legacy identifies an older, unmarked compatibility profile',
+ 'cannot authenticate the legacy command channel',
+ 'An absent runner alone does not rule out an authorised legacy command connection',
+ 'not proof of a broken collector',
+ 'your usual Docker or Podman administration tool',
+ 'Neither is a diagnostic prerequisite',
+ 'unknown is valid',
+ ])
+ assert.ok(authorityGuide.includes(phrase), phrase);
await page.screenshot({ path: path.join(artifacts, `${engine}-authority.png`) });
+ // The existing profile choices are optional operator decisions. Both
+ // links must be usable by keyboard; do not exercise any install action.
+ for (const [name, id] of [
+ ['agent privilege model', 'agent-privilege-model'],
+ ['least-privilege profile', 'least-privilege-agent-profile'],
+ ]) {
+ await page.getByRole('link', { name, exact: true }).focus();
+ if (id === 'agent-privilege-model') {
+ await page.screenshot({ path: path.join(artifacts, `${engine}-profile-choice.png`) });
+ }
+ await page.keyboard.press('Enter');
+ await waitForHeading(id);
+ assert.ok(page.url().endsWith(`/docs/AGENT_SECURITY#${id}`));
+ await page.evaluate(() => {
+ history.pushState({}, '', '/docs/DOCKER#command-agent-is-not-connected');
+ dispatchEvent(new PopStateEvent('popstate'));
+ });
+ await waitForHeading('command-agent-is-not-connected');
+ }
await page
.getByRole('link', {
name: 'command-channel connection and admission checks',
@@ -165,6 +196,8 @@ const { chromium, webkit } = require('playwright');
refusedSentUnknownStages: true,
commandGuidanceBeforeShellChecks: true,
keyboardTroubleshootingAndCommandChannelLinks: true,
+ legacyCredentialAndIndependentRunnerDistinguished: true,
+ keyboardOptionalProfileLinks: true,
headingsFocusedAndVisible: true,
noHorizontalOverflow: true,
errors,
diff --git a/frontend-modern/public/docs/DOCKER.md b/frontend-modern/public/docs/DOCKER.md
index 05414793dd..17f3903460 100644
--- a/frontend-modern/public/docs/DOCKER.md
+++ b/frontend-modern/public/docs/DOCKER.md
@@ -326,16 +326,40 @@ grants exec` describe local authority and credential scope, **not a connected
session**. A missing Privilege line is unknown, not proof that commands are off.
Fresh monitoring or an available image update does not prove command transport.
-For a command-capable host, follow the existing
+`root` identifies the collector's OS user, not its server-side permission.
+`commands legacy` identifies an older, unmarked compatibility profile; it does
+not establish that commands are enabled. `monitoring credential` means the
+known collector credential has no execution scope and cannot authenticate the
+legacy command channel. Do not add execution rights to that token as a repair.
+
+Inspect **Action runner** separately. `Credential not issued` and `Runner not
+connected` describe the separate typed runner, not monitoring health. An absent
+runner alone does not rule out an authorised legacy command connection. If
+**Safe collector not confirmed** is shown, that is not proof of a broken
+collector or permission to convert it merely to clear the update error.
+
+For a command-enabled, execution-scoped legacy connection, follow the existing
[command-channel connection and admission checks](UNIFIED_AGENT.md#commands-enabled-but-remote-control-blocked).
A monitoring-only setup is intentional when you only need readings and update
detection; do not enable commands, broaden a token, change Proxmox permissions
or loosen TLS merely to diagnose the refusal. Keep saved identity and credentials
intact; do not reinstall or retry the workload update as a connection test.
+You can keep working monitoring and manage any needed update through your usual
+Docker or Podman administration tool, after checking the workload's existing
+image/state and recovery path. Deliberately opting into Pulse-managed changes
+is a separate trust decision: the
+[agent privilege model](AGENT_SECURITY.md#agent-privilege-model) explains the
+legacy combined command profile, and the
+[least-privilege profile](AGENT_SECURITY.md#least-privilege-agent-profile)
+describes the supported separate runner. Neither is a diagnostic prerequisite;
+do not change a working profile just to obtain evidence.
+
For help, retain the original error, time and stage plus the existing command
-authority/scope wording, or say it is unavailable. Share only those distinctions,
-not a full Agent Doctor report, token hint, agent ID or service configuration.
+authority/scope and Action runner wording, or say it is unavailable. If relevant,
+say whether command execution was deliberately selected at installation;
+unknown is valid. Share only those distinctions, not a full Agent Doctor report,
+token hint, agent ID or service configuration.
The connection refusal does not settle an earlier missing receipt.
#### Action was sent or its outcome is unknown
diff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.md
index b7eb55ca73..76c916541b 100644
--- a/frontend-modern/public/docs/UNIFIED_AGENT.md
+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md
@@ -1385,8 +1385,23 @@ monitoring report or **Automatic updates ready** also does not prove that this
separate WebSocket channel is working. Changing Proxmox API permissions cannot
repair a Pulse command-channel connection.
+Before treating this as a connection failure, read the existing **Privilege**
+and **Action runner** lines. `root` is the collector's OS user; `commands legacy`
+is a compatibility profile, not proof that commands are enabled. A
+`monitoring credential` cannot authenticate the legacy command channel.
+`Credential not issued` or `Runner not connected` concerns the separate typed
+runner, not collector health; an absent runner alone does not exclude an
+authorised legacy command connection. Use the
+[workload-update authority guidance](DOCKER.md#command-agent-is-not-connected)
+to distinguish these cases without widening a token or converting the collector.
+Keep an intentionally monitoring-only installation unchanged. Choosing an
+execution-capable installation is a separate trust decision, not a connection
+test; remember whether that choice was made, or say it is unknown.
+
For a systemd agent, inspect the recent journal **locally on the affected node**
-with the [bounded agent log reader](#collect-agent-logs-safely).
+with the [bounded agent log reader](#collect-agent-logs-safely) only when an
+authorised command connection was intended and its failure stage is still
+unknown. Do not collect more logs just to confirm the known monitoring scope.
Look for **Connected and registered with Pulse command server**, or
**WebSocket connection failed repeatedly, reconnecting** and its error. A
diff --git a/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts b/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts
index 780105d37f..19a665f455 100644
--- a/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts
+++ b/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts
@@ -25,6 +25,37 @@ function section(article: HTMLElement, id: string): string {
}
describe('shipped monitored-container update guide', () => {
+ it('separates a legacy monitoring credential from independent runner posture and operator intent', () => {
+ const text = section(renderGuide(), 'command-agent-is-not-connected');
+ for (const phrase of [
+ "root identifies the collector's OS user, not its server-side permission",
+ 'commands legacy identifies an older, unmarked compatibility profile',
+ 'cannot authenticate the legacy command channel',
+ 'Do not add execution rights to that token as a repair',
+ 'Credential not issued and Runner not connected',
+ 'An absent runner alone does not rule out an authorised legacy command connection',
+ 'not proof of a broken collector',
+ 'your usual Docker or Podman administration tool',
+ 'Neither is a diagnostic prerequisite',
+ 'unknown is valid',
+ ]) {
+ expect(text).toContain(phrase);
+ }
+ });
+
+ it('links deliberate command-profile choices to shipped security guidance rather than a forced conversion', () => {
+ const article = renderGuide();
+ const security = document.createElement('article');
+ security.innerHTML = renderDocMarkdown(
+ readFileSync(path.join(repoRoot, 'docs/AGENT_SECURITY.md'), 'utf8'),
+ 'AGENT_SECURITY',
+ );
+ for (const id of ['agent-privilege-model', 'least-privilege-agent-profile']) {
+ expect(article.querySelector(`a[href="/docs/AGENT_SECURITY#${id}"]`)).not.toBeNull();
+ expect(security.querySelector(`#${id}`)).not.toBeNull();
+ }
+ });
+
it('separates a refused plan from a sent or unknown action before any shell check', () => {
const article = renderGuide();
const checks = section(article, 'check-a-failed-or-pending-workload-update');
diff --git a/scripts/tests/test_update_recovery_docs.py b/scripts/tests/test_update_recovery_docs.py
index 8106a0922f..17ec488413 100644
--- a/scripts/tests/test_update_recovery_docs.py
+++ b/scripts/tests/test_update_recovery_docs.py
@@ -344,6 +344,38 @@ class UpdateRecoveryDocsTest(unittest.TestCase):
doctor = (ROOT / "frontend-modern/src/components/Settings/InfrastructureAgentDoctorPage.tsx").read_text()
self.assertIn("· Privilege: {target.privilegeLabel}", doctor)
+ def test_legacy_monitoring_help_does_not_require_runner_migration_or_more_logs(self):
+ docker = " ".join(section("DOCKER", "Command agent is not connected", "####").split())
+ for phrase in (
+ "`root` identifies the collector's OS user", "`commands legacy`",
+ "does not establish that commands are enabled", "`monitoring credential`",
+ "cannot authenticate the legacy command channel",
+ "Do not add execution rights to that token as a repair",
+ "`Credential not issued` and `Runner not connected`",
+ "An absent runner alone does not rule out an authorised legacy command connection",
+ "not proof of a broken collector", "your usual Docker or Podman administration tool",
+ "Neither is a diagnostic prerequisite", "unknown is valid",
+ ):
+ with self.subTest(phrase=phrase):
+ self.assertIn(phrase, docker)
+ model = (ROOT / "frontend-modern/src/components/Settings/infrastructureAgentUpdateCommandsModel.ts").read_text()
+ for label in ("Credential not issued", "Runner not connected"):
+ self.assertIn(label, model)
+ self.assertIn("privilege.actionRunnerCredentialIssued", model)
+ self.assertIn("privilege.actionRunnerConnected", model)
+ self.assertIn("!privilege.credentialExec", model)
+
+ unified = " ".join(section("UNIFIED_AGENT", "Commands enabled but remote control blocked", "###").split())
+ for phrase in (
+ "DOCKER.md#command-agent-is-not-connected",
+ "without widening a token or converting the collector",
+ "an authorised command connection was intended",
+ "Do not collect more logs just to confirm the known monitoring scope",
+ ):
+ self.assertIn(phrase, unified)
+ self.assertEqual(guide("UNIFIED_AGENT"),
+ (ROOT / "frontend-modern/public/docs/UNIFIED_AGENT.md").read_text())
+
def test_update_failure_entry_reuses_bounded_readers_before_any_recovery(self):
text = " ".join(section("AUTO_UPDATE", "Update failed", "###").split())
for phrase in ("**Pulse server**", "UNIFIED_AGENT.md#auto-update",