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 stopped agent commands without credential or state churn

pulse-triage[bot]ed2107bee0d6
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 0a63961e8c..dc2a7fe2c6 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -15,11 +15,26 @@ See [INSTALL.md](INSTALL.md) for all options (Docker Compose, Kubernetes, system
Go to **Settings → Infrastructure → Install on a host** for systems that should
run the unified agent directly.
-- **Recommended (agent setup)**: copy the generated install command and run it on the target host.
+- **Agent setup**: use the generated command on the target host, entering the
+ token only at its private prompt, never in the command itself. Alternatively,
+ follow the [private-file preparation](UNIFIED_AGENT.md#private-file-installation-linux-macos-and-nas).
- **Manual/API-backed platforms**: use **Settings → Infrastructure** (**Add infrastructure**) for systems such as Proxmox, PBS, PMG, or TrueNAS that connect over an API instead of running the agent locally.
If you want Pulse to find servers automatically, open **Settings → Infrastructure**, select **Configure discovery** (it reads **Settings** once discovery is on), turn on **Automatic scanning** in the Discovery settings dialog, and then review discovered servers in the same section.
+### Why does the copied agent command say no installation was attempted?
+
+That message describes a stopped preparation step, not the health of an agent
+already installed. If it follows `stty: command not found`, the private token
+prompt cannot prepare the terminal; having an interactive shell does not supply
+the missing tool. Do not remove the privacy check, put a token in the command,
+generate another token or uninstall the existing agent to get past it.
+
+Use the [agent command failure guide](UNIFIED_AGENT.md#copied-agent-command-fails-before-installation)
+to distinguish the prompt, preflight and removal paths. Keep the original error
+and existing state; a failed new command does not explain an earlier outage or
+automatic-update failure.
+
### How do I change the port?
Distinguish Pulse's web listener from a container's published host port.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 00b3f1e3b9..ea17e5d042 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -24,6 +24,10 @@ establish safe recovery.
[agent authentication and reporting evidence](UNIFIED_AGENT.md#agent-lookup-returns-http-401-or-403)
before replacing a token or reinstalling. Installer success is not an accepted
report.
+- **Copied agent install or removal command failed:** distinguish its
+ [preparation, private prompt and lifecycle action](UNIFIED_AGENT.md#copied-agent-command-fails-before-installation).
+ A stopped new command does not diagnose the existing agent. Keep state and
+ credentials; do not repeat removal or installation to obtain an error.
- **Guest readings are missing or disagree:** distinguish
[current, retained and unavailable disks](VM_DISK_MONITORING.md#current-retained-and-unavailable-disk-readings)
from [guest memory pressure](TROUBLESHOOTING.md#guest-memory-is-high-but-available-memory-is-plentiful).
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md
index 6833ce0997..391ecce817 100644
--- a/docs/UNIFIED_AGENT.md
+++ b/docs/UNIFIED_AGENT.md
@@ -1040,6 +1040,49 @@ Set `--health-addr=""` or `PULSE_HEALTH_ADDR=off` to disable the health/metrics
## Troubleshooting
+### Copied agent command fails before installation
+
+The copied Unix command prepares a download and, for installation, runs a
+`--preflight-only` check before entering a private token prompt. Passing
+preflight is **not installation** or accepted reporting. Read the original
+error to identify which step stopped; do not run the command again to find out.
+
+- **`stty: command not found`, followed by a terminal-required message:** the
+ command's environment cannot run the tool used to prepare the private prompt.
+ A real terminal can still produce this error. It does not establish that the
+ token is invalid, that the target platform cannot run an agent, or that an
+ existing agent was removed.
+- **A terminal-required or interrupted-input message without that error:**
+ token entry did not complete safely. Keep it separate from an installer's
+ later result; do not assume a missing tool from the terminal message alone.
+- **`Safe-profile migration is unsupported on this platform`:** this concerns
+ the Linux safe-profile migration path. `--safe-profile-inspect` is a
+ standalone **read-only** action, not removal; `--uninstall` is a separate,
+ destructive action. The inspection can produce this error on an unsupported
+ platform such as QNAP. The error alone does not prove that removal ran. Do
+ not combine those flags or request a broader-privilege fallback.
+
+**Stop rather than bypass the private prompt.** Do not enable token echo, put a
+secret in command arguments or an environment assignment, weaken TLS, generate
+a replacement token or delete installed identity, connection files or logs.
+For a planned first installation where the prompt is unavailable, the
+[private-file installation](#private-file-installation-linux-macos-and-nas)
+uses a private editor and `--token-file`, with the same download trust and
+collector choices. It is not an instruction to repeat a failed recovery attempt.
+
+For an existing unavailable or outdated agent, retain that original failure
+separately and use [reporting checks](#agent-lookup-returns-http-401-or-403) or
+[update guidance](#auto-update). If removal was intentional, read its
+[state-preservation and result checks](#uninstall) before another action. A
+failed new command does not establish the cause of the earlier outage or
+automatic-update failure.
+
+When reporting a command failure, share only the original failure stage and
+manually redacted error. If the action is consequential, name only the flag
+already used (`--safe-profile-inspect` or `--uninstall`), or say **unknown**.
+Do not post the full copied command, a token, its file contents or service
+configuration, and do not repeat installation or removal to complete a report.
+
### Collect agent logs safely
Prefer existing observations from the original failure. On a **Linux systemd
diff --git a/frontend-modern/public/docs/FAQ.md b/frontend-modern/public/docs/FAQ.md
index 0a63961e8c..dc2a7fe2c6 100644
--- a/frontend-modern/public/docs/FAQ.md
+++ b/frontend-modern/public/docs/FAQ.md
@@ -15,11 +15,26 @@ See [INSTALL.md](INSTALL.md) for all options (Docker Compose, Kubernetes, system
Go to **Settings → Infrastructure → Install on a host** for systems that should
run the unified agent directly.
-- **Recommended (agent setup)**: copy the generated install command and run it on the target host.
+- **Agent setup**: use the generated command on the target host, entering the
+ token only at its private prompt, never in the command itself. Alternatively,
+ follow the [private-file preparation](UNIFIED_AGENT.md#private-file-installation-linux-macos-and-nas).
- **Manual/API-backed platforms**: use **Settings → Infrastructure** (**Add infrastructure**) for systems such as Proxmox, PBS, PMG, or TrueNAS that connect over an API instead of running the agent locally.
If you want Pulse to find servers automatically, open **Settings → Infrastructure**, select **Configure discovery** (it reads **Settings** once discovery is on), turn on **Automatic scanning** in the Discovery settings dialog, and then review discovered servers in the same section.
+### Why does the copied agent command say no installation was attempted?
+
+That message describes a stopped preparation step, not the health of an agent
+already installed. If it follows `stty: command not found`, the private token
+prompt cannot prepare the terminal; having an interactive shell does not supply
+the missing tool. Do not remove the privacy check, put a token in the command,
+generate another token or uninstall the existing agent to get past it.
+
+Use the [agent command failure guide](UNIFIED_AGENT.md#copied-agent-command-fails-before-installation)
+to distinguish the prompt, preflight and removal paths. Keep the original error
+and existing state; a failed new command does not explain an earlier outage or
+automatic-update failure.
+
### How do I change the port?
Distinguish Pulse's web listener from a container's published host port.
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index 00b3f1e3b9..ea17e5d042 100644
--- a/frontend-modern/public/docs/TROUBLESHOOTING.md
+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md
@@ -24,6 +24,10 @@ establish safe recovery.
[agent authentication and reporting evidence](UNIFIED_AGENT.md#agent-lookup-returns-http-401-or-403)
before replacing a token or reinstalling. Installer success is not an accepted
report.
+- **Copied agent install or removal command failed:** distinguish its
+ [preparation, private prompt and lifecycle action](UNIFIED_AGENT.md#copied-agent-command-fails-before-installation).
+ A stopped new command does not diagnose the existing agent. Keep state and
+ credentials; do not repeat removal or installation to obtain an error.
- **Guest readings are missing or disagree:** distinguish
[current, retained and unavailable disks](VM_DISK_MONITORING.md#current-retained-and-unavailable-disk-readings)
from [guest memory pressure](TROUBLESHOOTING.md#guest-memory-is-high-but-available-memory-is-plentiful).
diff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.md
index 6833ce0997..391ecce817 100644
--- a/frontend-modern/public/docs/UNIFIED_AGENT.md
+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md
@@ -1040,6 +1040,49 @@ Set `--health-addr=""` or `PULSE_HEALTH_ADDR=off` to disable the health/metrics
## Troubleshooting
+### Copied agent command fails before installation
+
+The copied Unix command prepares a download and, for installation, runs a
+`--preflight-only` check before entering a private token prompt. Passing
+preflight is **not installation** or accepted reporting. Read the original
+error to identify which step stopped; do not run the command again to find out.
+
+- **`stty: command not found`, followed by a terminal-required message:** the
+ command's environment cannot run the tool used to prepare the private prompt.
+ A real terminal can still produce this error. It does not establish that the
+ token is invalid, that the target platform cannot run an agent, or that an
+ existing agent was removed.
+- **A terminal-required or interrupted-input message without that error:**
+ token entry did not complete safely. Keep it separate from an installer's
+ later result; do not assume a missing tool from the terminal message alone.
+- **`Safe-profile migration is unsupported on this platform`:** this concerns
+ the Linux safe-profile migration path. `--safe-profile-inspect` is a
+ standalone **read-only** action, not removal; `--uninstall` is a separate,
+ destructive action. The inspection can produce this error on an unsupported
+ platform such as QNAP. The error alone does not prove that removal ran. Do
+ not combine those flags or request a broader-privilege fallback.
+
+**Stop rather than bypass the private prompt.** Do not enable token echo, put a
+secret in command arguments or an environment assignment, weaken TLS, generate
+a replacement token or delete installed identity, connection files or logs.
+For a planned first installation where the prompt is unavailable, the
+[private-file installation](#private-file-installation-linux-macos-and-nas)
+uses a private editor and `--token-file`, with the same download trust and
+collector choices. It is not an instruction to repeat a failed recovery attempt.
+
+For an existing unavailable or outdated agent, retain that original failure
+separately and use [reporting checks](#agent-lookup-returns-http-401-or-403) or
+[update guidance](#auto-update). If removal was intentional, read its
+[state-preservation and result checks](#uninstall) before another action. A
+failed new command does not establish the cause of the earlier outage or
+automatic-update failure.
+
+When reporting a command failure, share only the original failure stage and
+manually redacted error. If the action is consequential, name only the flag
+already used (`--safe-profile-inspect` or `--uninstall`), or say **unknown**.
+Do not post the full copied command, a token, its file contents or service
+configuration, and do not repeat installation or removal to complete a report.
+
### Collect agent logs safely
Prefer existing observations from the original failure. On a **Linux systemd
diff --git a/frontend-modern/src/features/docs/__tests__/unifiedAgentBootstrapGuide.test.ts b/frontend-modern/src/features/docs/__tests__/unifiedAgentBootstrapGuide.test.ts
index 498eab8734..64c5d2dabf 100644
--- a/frontend-modern/src/features/docs/__tests__/unifiedAgentBootstrapGuide.test.ts
+++ b/frontend-modern/src/features/docs/__tests__/unifiedAgentBootstrapGuide.test.ts
@@ -7,13 +7,14 @@ import { renderDocMarkdown } from '../docMarkdown';
const frontendRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
const source = readFileSync(path.join(frontendRoot, '../docs/UNIFIED_AGENT.md'), 'utf8');
-function setupSection() {
+function docSection(markdown: string, docPath: string, id: string) {
const article = document.createElement('article');
- article.innerHTML = renderDocMarkdown(source, 'UNIFIED_AGENT');
- const heading = article.querySelector('#private-file-installation-linux-macos-and-nas')!;
+ article.innerHTML = renderDocMarkdown(markdown, docPath);
+ const heading = article.querySelector(`#${id}`);
+ expect(heading, `${docPath}#${id} must be a real rendered destination`).not.toBeNull();
const section = document.createElement('section');
for (
- let node = heading.nextElementSibling;
+ let node = heading!.nextElementSibling;
node && !/^H[23]$/.test(node.tagName);
node = node.nextElementSibling
) {
@@ -22,6 +23,10 @@ function setupSection() {
return section;
}
+function setupSection() {
+ return docSection(source, 'UNIFIED_AGENT', 'private-file-installation-linux-macos-and-nas');
+}
+
describe('Unified Agent private-file setup help', () => {
it('renders preparation and download as self-contained fences before installation', () => {
const section = setupSection();
@@ -61,3 +66,86 @@ describe('Unified Agent private-file setup help', () => {
);
});
});
+
+describe('Stopped agent-command help', () => {
+ const failureId = 'copied-agent-command-fails-before-installation';
+ const faq = readFileSync(path.join(frontendRoot, '../docs/FAQ.md'), 'utf8');
+ const troubleshooting = readFileSync(
+ path.join(frontendRoot, '../docs/TROUBLESHOOTING.md'),
+ 'utf8',
+ );
+ const normalizedText = (section: HTMLElement) => section.textContent!.replace(/\s+/g, ' ');
+
+ it('makes the same failure destination reachable from setup and troubleshooting', () => {
+ for (const [name, markdown] of [
+ ['FAQ', faq],
+ ['TROUBLESHOOTING', troubleshooting],
+ ]) {
+ const article = document.createElement('article');
+ article.innerHTML = renderDocMarkdown(markdown, name);
+ expect(
+ article.querySelector(`a[data-doc-link][href="/docs/UNIFIED_AGENT#${failureId}"]`),
+ ).not.toBeNull();
+ expect(readFileSync(path.join(frontendRoot, `public/docs/${name}.md`), 'utf8')).toBe(
+ markdown,
+ );
+ }
+ const setup = docSection(faq, 'FAQ', 'how-do-i-add-a-node');
+ expect(
+ setup.querySelector(
+ 'a[href="/docs/UNIFIED_AGENT#private-file-installation-linux-macos-and-nas"]',
+ ),
+ ).not.toBeNull();
+ expect(normalizedText(setup)).toContain('token only at its private prompt');
+ });
+
+ it('distinguishes stopped prompt, read-only inspection and destructive removal', () => {
+ const section = docSection(source, 'UNIFIED_AGENT', failureId);
+ const text = normalizedText(section);
+ expect(section.querySelectorAll(':scope > ul > li')).toHaveLength(3);
+ for (const fact of [
+ 'Passing preflight is not installation',
+ 'A real terminal can still produce this error',
+ 'do not assume a missing tool from the terminal message alone',
+ 'standalone read-only action, not removal',
+ 'The error alone does not prove that removal ran',
+ 'failed new command does not establish the cause of the earlier outage',
+ ]) {
+ expect(text).toContain(fact);
+ }
+ const producer = readFileSync(
+ path.join(frontendRoot, 'src/utils/agentInstallCommand.ts'),
+ 'utf8',
+ );
+ expect(producer).toContain('--preflight-only');
+ expect(producer).toContain('--token-file "$token_file"');
+ const installer = readFileSync(path.join(frontendRoot, '../scripts/install.sh'), 'utf8');
+ expect(installer).toContain('--safe-profile-inspect is a standalone read-only action');
+ expect(installer).toContain('Safe-profile migration is unsupported on this platform');
+ });
+
+ it('links to existing private preparation and recovery without another executable recipe', () => {
+ const section = docSection(source, 'UNIFIED_AGENT', failureId);
+ const article = document.createElement('article');
+ article.innerHTML = renderDocMarkdown(source, 'UNIFIED_AGENT');
+ for (const id of [
+ 'private-file-installation-linux-macos-and-nas',
+ 'agent-lookup-returns-http-401-or-403',
+ 'auto-update',
+ 'uninstall',
+ ]) {
+ expect(section.querySelector(`a[href="#${id}"]`)).not.toBeNull();
+ expect(article.querySelector(`#${id}`)).not.toBeNull();
+ }
+ expect(section.querySelector('pre')).toBeNull();
+ for (const boundary of [
+ 'Stop rather than bypass the private prompt',
+ 'not an instruction to repeat a failed recovery attempt',
+ 'name only the flag already used',
+ 'Do not post the full copied command',
+ 'do not repeat installation or removal to complete a report',
+ ]) {
+ expect(normalizedText(section)).toContain(boundary);
+ }
+ });
+});