diff --git a/docs/AGENT_SECURITY.md b/docs/AGENT_SECURITY.md index 93a2924702..ffc3302179 100644 --- a/docs/AGENT_SECURITY.md +++ b/docs/AGENT_SECURITY.md @@ -54,8 +54,8 @@ contents. Local `--disk-exclude` rules still take precedence. Fresh installs use a local `monitoring-only` command-authority ceiling and a credential without `agent:exec`. Remote configuration cannot promote that -service. Selecting the advanced legacy combined command profile at install time -adds `--enable-commands`, records `command-capable`, and issues an execution- +service. Selecting **Allow Pulse to run commands on this host** at install time (the combined +command profile) adds `--enable-commands`, records `command-capable`, and issues an execution- scoped credential. The root monitoring process can then also accept server command requests through the existing policy and approval surfaces. Existing unmarked services upgrade as `legacy` during the migration window so upgrades diff --git a/docs/DOCKER.md b/docs/DOCKER.md index a06e2d243f..e21b1dfde8 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -364,7 +364,7 @@ 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 +combined command profile behind **Allow Pulse to run commands on this host**, 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. @@ -485,7 +485,8 @@ Pulse can start, stop, and restart Docker / Podman containers directly from the - **Pulse Agent** installed on the container host (see [Unified Agent](UNIFIED_AGENT.md)) and currently connected - **Command execution enabled** on the agent — it is disabled by default. Either: - start the agent with `--enable-commands` (or `PULSE_ENABLE_COMMANDS=true`), or - - tick **Enable legacy combined command profile** in **Settings → Infrastructure** before copying the install command, which adds the flag and grants the token the command execution permission (this is the transitional combined profile, not a least-privilege setting) + - tick **Allow Pulse to run commands on this host** in the token step of **Settings → Infrastructure** before copying the install command, which adds the flag and grants the token the command execution permission. Pulse can then run commands as root on that host: this is the full-trust combined profile, not a least-privilege setting + - an agent installed without it cannot be switched on from Pulse; run the new install command on the host - **Admin approval**: every lifecycle action requires confirmation by an admin in the UI before it runs. The agent then verifies the container's state before the change and confirms it actually reached the requested state afterwards. ### Limitations diff --git a/docs/PRODUCTION_SECURITY.md b/docs/PRODUCTION_SECURITY.md index 7f4eedebf9..b0d61e87b0 100644 --- a/docs/PRODUCTION_SECURITY.md +++ b/docs/PRODUCTION_SECURITY.md @@ -58,7 +58,8 @@ The fresh-install posture limits that boundary: - Proxmox guest Docker inventory through `pct exec` is disabled by default and requires an explicit server setting. -The advanced **legacy combined command profile** is a separate trust decision. +The **Allow Pulse to run commands on this host** install option (the combined command +profile) is a separate trust decision. It marks the root collector command-capable and gives its credential execution scope so the same process can accept governed server requests. Existing unmarked installations remain in a visible `legacy` compatibility state during diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md index a9c065030b..d9ce114795 100644 --- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md +++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md @@ -15,6 +15,25 @@ ## Purpose +### Command access is a named token-step choice, not a legacy option (21 October 2026) + +The installer's command-access checkbox reads **Allow Pulse to run commands on +this host** and sits in the token step, before the credential is minted, +instead of behind the advanced connection options as "Enable legacy combined +command profile". The behaviour behind it is unchanged: default off, an +explicit choice adds `--enable-commands`, records `command-capable`, and mints +an execution-scoped token; toggling after a mint still regenerates and revokes +the superseded token, and a `monitoring-only` install still cannot be promoted +remotely. The old name told the users who need Docker/Podman updates not to +use the only working route: Docker updates dispatch through the agent command +session, the separate action runner's container actions are unqualified, and +rootful Docker under the safe collector profile carries no update checks or +actions. The label is owned by `getUnifiedAgentCommandAccessOptionLabel`, which +the locked Docker update pill and the Proxmox setup guide also read, so copy +that sends users to it cannot drift from the checkbox. +`InfrastructureInstallerSection.test.tsx` pins the checkbox in the token step +with its root-access description. + ### Manual update checks skip images with no registry tag (21 October 2026) A manual container update check counts a `local image` status as skipped, diff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.md index 3e09582e45..e8d381d27e 100644 --- a/docs/release-control/v6/internal/subsystems/api-contracts.md +++ b/docs/release-control/v6/internal/subsystems/api-contracts.md @@ -21,6 +21,15 @@ ## Purpose +### Proxmox setup guide names the command-access option by its shared label (21 October 2026) + +The Proxmox node setup guide's Docker-in-LXC note now points to the Pulse +Agent installer option through `getUnifiedAgentCommandAccessOptionLabel` +("Allow Pulse to run commands on this host") instead of the "combined command +profile" wording. The node setup client still sends `enableCommands: false` +and mints monitoring-only credentials; no request or scope changes. +`settingsArchitecture.test.ts` pins the shared label. + ### Reporting telemetry observes canonical generation and delivery boundaries `internal/api/reporting_activity.go` records best-effort content-free events to diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.md index f6401aa9de..4685ea2727 100644 --- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md +++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md @@ -20,6 +20,14 @@ ## Purpose +### Locked update pill names the command-access option by its shared label (21 October 2026) + +For a host whose agent was installed without command access, the locked pill +names the installer option through `getUnifiedAgentCommandAccessOptionLabel` +("Allow Pulse to run commands on this host") and the host to run the new +install command on, instead of the retired "legacy combined command profile" +wording and its advanced-options path. + ### Container update control offers only what the server advertises (21 October 2026) `UpdateButton` is live only when the server advertises the `update` capability diff --git a/frontend-modern/browser-verification/ea7d7fee1ca69bdb.json b/frontend-modern/browser-verification/ea7d7fee1ca69bdb.json new file mode 100644 index 0000000000..ab1bc8eedc --- /dev/null +++ b/frontend-modern/browser-verification/ea7d7fee1ca69bdb.json @@ -0,0 +1,51 @@ +{ + "version": 1, + "base_sha": "68a59805c99f78f1f69ce1853f5d507a6dfe5e8f", + "verified_at": "2026-10-21T14:41:00Z", + "result": "passed", + "changed_paths": [ + "frontend-modern/src/components/Settings/InfrastructureInstallerSection.tsx", + "frontend-modern/src/components/Settings/NodeModalSetupGuideSection.tsx", + "frontend-modern/src/components/shared/containerUpdateBadgeModel.ts", + "frontend-modern/src/utils/unifiedAgentInventoryPresentation.ts" + ], + "content_sha256": { + "frontend-modern/src/components/Settings/InfrastructureInstallerSection.tsx": "60ada62ddc528bee9c5a394350a59c4b440f95a40e33ebd1b33805e07359a879", + "frontend-modern/src/components/Settings/NodeModalSetupGuideSection.tsx": "208d237386ae98e3c9b502213150c757bdba7c9eb0936fff00a2fad94f5be041", + "frontend-modern/src/components/shared/containerUpdateBadgeModel.ts": "9b855b0ed510168c73c768beb756afbb6bd0f0dcdbcf9132231420564ddc70ce", + "frontend-modern/src/utils/unifiedAgentInventoryPresentation.ts": "2ba26a0b11445fc1483fcf825c30cd2b4245f9a0a097612f0cfe2d437b78943c" + }, + "routes": [ + "/docker", + "/settings/infrastructure?add=linux-host", + "/settings/infrastructure?add=docker", + "/settings/infrastructure?add=pve" + ], + "viewports": [ + { + "width": 1400, + "height": 900 + }, + { + "width": 375, + "height": 812 + } + ], + "states": [ + "Install Pulse Agent (Linux, macOS, Windows host): 'Allow Pulse to run commands on this host' checkbox visible in step 1 under the token summary, before any token exists, unchecked by default, with its root-access description", + "Token summary bullet reads 'Monitoring only. Pulse cannot run commands or change containers on this host.' when unchecked and 'Pulse can run commands as root on this host, including container updates and Patrol actions.' when checked", + "Advanced connection and install options now hold only the Agent URL, CA, TLS and profile controls; the only other checkbox there is Skip TLS certificate verification", + "Docker installer: the Docker inside Proxmox LXCs note names the new option and the Proxmox VE node profile; no horizontal overflow at 375 px", + "Proxmox VE Host Telemetry Agent guide: the Docker-in-LXC note names 'Allow Pulse to run commands on this host'", + "No console errors", + "The 'installed without command access' pill variant cannot render on mock data (no mock docker-host carries an agent facet); its copy is covered by containerUpdateBadgeModel and ContainerUpdateBadge tests" + ], + "interactions": [ + "Opened Settings, Infrastructure, Add infrastructure, Install Pulse Agent", + "Ticked the option before generating a token, then generated one: toast confirmed command execution permission and every install command carried --enable-commands or PULSE_ENABLE_COMMANDS", + "Unticked it afterwards: token regenerated without command execution, toast told the user to copy the command again, no install command carried the flag", + "Opened the advanced options and listed their checkboxes", + "Opened the Docker installer at the mobile viewport and scrolled to the option", + "Opened the Proxmox VE flow and chose Host Telemetry Agent" + ] +} diff --git a/frontend-modern/public/docs/AGENT_SECURITY.md b/frontend-modern/public/docs/AGENT_SECURITY.md index 93a2924702..ffc3302179 100644 --- a/frontend-modern/public/docs/AGENT_SECURITY.md +++ b/frontend-modern/public/docs/AGENT_SECURITY.md @@ -54,8 +54,8 @@ contents. Local `--disk-exclude` rules still take precedence. Fresh installs use a local `monitoring-only` command-authority ceiling and a credential without `agent:exec`. Remote configuration cannot promote that -service. Selecting the advanced legacy combined command profile at install time -adds `--enable-commands`, records `command-capable`, and issues an execution- +service. Selecting **Allow Pulse to run commands on this host** at install time (the combined +command profile) adds `--enable-commands`, records `command-capable`, and issues an execution- scoped credential. The root monitoring process can then also accept server command requests through the existing policy and approval surfaces. Existing unmarked services upgrade as `legacy` during the migration window so upgrades diff --git a/frontend-modern/public/docs/DOCKER.md b/frontend-modern/public/docs/DOCKER.md index a06e2d243f..e21b1dfde8 100644 --- a/frontend-modern/public/docs/DOCKER.md +++ b/frontend-modern/public/docs/DOCKER.md @@ -364,7 +364,7 @@ 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 +combined command profile behind **Allow Pulse to run commands on this host**, 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. @@ -485,7 +485,8 @@ Pulse can start, stop, and restart Docker / Podman containers directly from the - **Pulse Agent** installed on the container host (see [Unified Agent](UNIFIED_AGENT.md)) and currently connected - **Command execution enabled** on the agent — it is disabled by default. Either: - start the agent with `--enable-commands` (or `PULSE_ENABLE_COMMANDS=true`), or - - tick **Enable legacy combined command profile** in **Settings → Infrastructure** before copying the install command, which adds the flag and grants the token the command execution permission (this is the transitional combined profile, not a least-privilege setting) + - tick **Allow Pulse to run commands on this host** in the token step of **Settings → Infrastructure** before copying the install command, which adds the flag and grants the token the command execution permission. Pulse can then run commands as root on that host: this is the full-trust combined profile, not a least-privilege setting + - an agent installed without it cannot be switched on from Pulse; run the new install command on the host - **Admin approval**: every lifecycle action requires confirmation by an admin in the UI before it runs. The agent then verifies the container's state before the change and confirms it actually reached the requested state afterwards. ### Limitations diff --git a/frontend-modern/public/docs/PRODUCTION_SECURITY.md b/frontend-modern/public/docs/PRODUCTION_SECURITY.md index 7f4eedebf9..b0d61e87b0 100644 --- a/frontend-modern/public/docs/PRODUCTION_SECURITY.md +++ b/frontend-modern/public/docs/PRODUCTION_SECURITY.md @@ -58,7 +58,8 @@ The fresh-install posture limits that boundary: - Proxmox guest Docker inventory through `pct exec` is disabled by default and requires an explicit server setting. -The advanced **legacy combined command profile** is a separate trust decision. +The **Allow Pulse to run commands on this host** install option (the combined command +profile) is a separate trust decision. It marks the root collector command-capable and gives its credential execution scope so the same process can accept governed server requests. Existing unmarked installations remain in a visible `legacy` compatibility state during diff --git a/frontend-modern/src/components/Settings/InfrastructureInstallerSection.tsx b/frontend-modern/src/components/Settings/InfrastructureInstallerSection.tsx index bd00dd6d1e..fbd837df34 100644 --- a/frontend-modern/src/components/Settings/InfrastructureInstallerSection.tsx +++ b/frontend-modern/src/components/Settings/InfrastructureInstallerSection.tsx @@ -11,6 +11,7 @@ import { getUnifiedAgentLookupStatusPresentation } from '@/utils/unifiedAgentSta import { getUnifiedAgentClipboardCopyErrorMessage, getUnifiedAgentClipboardCopySuccessMessage, + getUnifiedAgentCommandAccessOptionLabel, } from '@/utils/unifiedAgentInventoryPresentation'; import { INSTALL_PROFILE_OPTIONS, @@ -41,6 +42,8 @@ type InfrastructureInstallerFocusPresentation = { platforms: readonly AgentPlatform[]; }; +const COMMAND_ACCESS_OPTION_LABEL = getUnifiedAgentCommandAccessOptionLabel(); + const ALL_AGENT_PLATFORMS: readonly AgentPlatform[] = ['linux', 'macos', 'freebsd', 'windows']; const INSTALLER_FOCUS_PRESENTATION: Record< @@ -119,7 +122,7 @@ const getCommandSectionDescription = ( return 'Use the Linux installer from Unraid terminal or SSH. The agent stores its local uninstall helper under the Unraid plugin path.'; } if (focus === 'docker') { - return 'Use the Linux installer on a standalone Docker or Podman host. Docker discovery inside Proxmox LXCs currently requires the advanced, command-capable Proxmox install profile.'; + return 'Use the Linux installer on a standalone Docker or Podman host. Docker discovery inside Proxmox LXCs needs the Proxmox VE node profile with command access allowed.'; } if (focus === 'kubernetes') { return 'Use the Linux installer on a Kubernetes node. Commands in this flow include the Kubernetes profile.'; @@ -289,12 +292,12 @@ export const InfrastructureInstallerSection: Component

Docker inside Proxmox LXCs

- Install the agent on the Proxmox node, not inside every LXC. In advanced options, - select Proxmox VE node and enable{' '} - the legacy combined command profile. This is a - temporary full command-capable runtime, not a least-privilege monitoring install. Then - turn on Discover Docker in LXC guests in Settings → - System → General (admin only), or set{' '} + Install the agent on the Proxmox node, not inside every LXC. Turn on{' '} + {COMMAND_ACCESS_OPTION_LABEL} below, and in advanced + options select Proxmox VE node. This gives Pulse + command access to the node; it is not a monitoring-only install. Then turn on{' '} + Discover Docker in LXC guests in Settings → System → + General (admin only), or set{' '} PULSE_ENABLE_PROXMOX_GUEST_DOCKER_INVENTORY=true in the server environment to lock it on. Optionally restrict it with{' '} PULSE_PROXMOX_GUEST_DOCKER_INVENTORY_VMIDS=101,102. Pulse uses bounded{' '} @@ -340,8 +343,9 @@ export const InfrastructureInstallerSection: Component ✓ - Read-only by default. Assistant chat actions and host shell stay off until you opt - in per host from Settings → Infrastructure. + {state.enableCommands() + ? 'Pulse can run commands as root on this host, including container updates and Patrol actions.' + : 'Monitoring only. Pulse cannot run commands or change containers on this host.'}

  • @@ -355,6 +359,28 @@ export const InfrastructureInstallerSection: Component +
    + +

    + Needed to update, start, stop or restart Docker and Podman containers from Pulse, and + for Patrol actions. Pulse can then run commands as root on this host, so leave it off + if you only want monitoring. It cannot be switched on later from Pulse: rerun the + install command with this selected. +

    +
    +

    Default commands use the auto-detected Pulse URL. Open this only if the target - host needs a different URL, custom CA trust, TLS override, command execution, - or a specific install profile. + host needs a different URL, custom CA trust, TLS override, or a specific + install profile.