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
Clarify legacy monitoring credentials and separate runner recovery help
pulse-triage[bot]d1c93855ff28
diff --git a/docs/DOCKER.md b/docs/DOCKER.mdindex 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 connectedsession**. 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 updatedetection; do not enable commands, broaden a token, change Proxmox permissionsor loosen TLS merely to diagnose the refusal. Keep saved identity and credentialsintact; 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 unknowndiff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.mdindex 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 thisseparate WebSocket channel is working. Changing Proxmox API permissions cannotrepair 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. Adiff --git a/frontend-modern/browser-tests/docker-update-guidance.cjs b/frontend-modern/browser-tests/docker-update-guidance.cjsindex 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.mdindex 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 connectedsession**. 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 updatedetection; do not enable commands, broaden a token, change Proxmox permissionsor loosen TLS merely to diagnose the refusal. Keep saved identity and credentialsintact; 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 unknowndiff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.mdindex 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 thisseparate WebSocket channel is working. Changing Proxmox API permissions cannotrepair 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. Adiff --git a/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts b/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.tsindex 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.pyindex 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",