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.

Make observer telemetry and Proxmox access separate choices

pulse-triage[bot]78e6a9ebb47e
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md
index cd21a4d714..e6a9f9deb9 100644
--- a/docs/UNIFIED_AGENT.md
+++ b/docs/UNIFIED_AGENT.md
@@ -630,9 +630,21 @@ and persisted host-report buffers are isolated per destination, so an observer
outage does not replay or block the primary stream. Observer responses cannot
change configuration, execute commands, enroll the agent, or select updates.
-Create a separate API token on each observer and store every token in its own
-absolute-path file. On Unix, both the JSON file and token files must be regular,
-non-symlink files with no group or other permissions (for example mode `0600`).
+**Report-only is a control boundary, not a redaction boundary.** Each observer
+receives the enabled modules' reports, including their infrastructure identities
+and metadata; this is not a reduced or anonymised copy. Choose only destinations
+allowed to hold that data. Adding an observer does not replace the primary
+server, and its delivery health does not establish primary delivery or recovery.
+
+### Choose telemetry only or Proxmox registration
+
+For an additional telemetry destination, explicitly set **`provisionProxmox` to
+`false`**, as in this example. Create a separate API token on that observer and
+store it in its own absolute-path file; do not reuse the primary server's token.
+On Unix, both the JSON file and token files must be regular, non-symlink files
+with no group or other permissions (for example mode `0600`). They must be
+readable by the actual agent service account. Use a private editor, not a token
+in a command, URL, JSON field or issue report.
```json
{
@@ -643,30 +655,57 @@ non-symlink files with no group or other permissions (for example mode `0600`).
"url": "https://pulse-dev.example.test",
"tokenFile": "/etc/pulse-agent/dev-observer.token",
"serverFingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
- "provisionProxmox": true
+ "provisionProxmox": false
}
]
}
```
-Start or install the service with
-`--observers-file /etc/pulse-agent/observers.json`. Plaintext remote HTTP is
-rejected unless that observer explicitly sets `"allowPlaintextHTTP": true`.
-`insecureSkipVerify` is available per observer but should be replaced with a
-CA file or certificate fingerprint wherever possible.
+The fingerprint above is a placeholder, not a trusted certificate. Obtain the
+observer's actual fingerprint through a separately trusted path, or use
+`caCertPath` for a verified CA file. Keep HTTPS verification enabled. A
+certificate error is not a reason to enable `insecureSkipVerify` or change to
+HTTP. Every non-loopback HTTP observer, including a private-LAN address,
+requires its own `allowPlaintextHTTP` opt-in; that sends its API token and
+reports in cleartext. The primary server's HTTP consent does not authorise an
+observer.
-When Proxmox integration is enabled, each observer gets a distinct
-destination-scoped PVE/PBS API token and registration-state directory. Pulse
-must answer the registration check before the agent creates or rotates any
-Proxmox token; an unavailable destination therefore leaves existing
-credentials unchanged. Set `"provisionProxmox": false` when an observer should
-receive only Unified Agent telemetry and no separately registered PVE/PBS
-source.
+| Proxmox choice | Effect when Proxmox integration is enabled |
+| --- | --- |
+| `"provisionProxmox": false` | Sends agent telemetry without creating or repairing this observer's separately registered PVE/PBS source. It does not disable ordinary host, Docker/Podman or Kubernetes reports. |
+| `true`, or the field omitted | Includes this observer in Proxmox setup and periodic registration health checks. The agent can create or rotate a destination-scoped PVE/PBS API token and register its credentials with that Pulse server. |
+
+**Omitting the field defaults to `true`, not telemetry only.** Choose that
+additional API access deliberately; do not enable Proxmox integration or widen
+permissions merely to make observer telemetry appear. Pulse must answer the
+registration check before token creation or rotation; an unavailable
+destination leaves existing credentials unchanged. Each observer has a distinct
+Proxmox token and registration-state directory, not the primary's credentials.
+
+Changing the field to `false` is not revocation of a previously issued Proxmox
+token, removal of an existing Pulse connection, or deletion of reports already
+stored by the observer. Plan any intended credential or connection retirement
+separately, preserving the primary's access and monitoring; do not delete agent
+state or re-enrol it to change this choice.
+
+### Apply and check the intended destination
+
+For a planned installation, pass
+`--observers-file /etc/pulse-agent/observers.json` through the
+[private-file installation procedure](#private-file-installation-linux-macos-and-nas).
+For an existing service, preserve its primary URL, credential, identity and
+other saved settings when scheduling the change; do not reinstall or restart
+merely to diagnose missing reports. Follow [backup safety](VM_DISK_MONITORING.md#backup-safety)
+if a guest or freeze/thaw operation is uncertain.
Per-destination delivery status is exported on the health listener as
`pulse_agent_destination_configured` and
`pulse_agent_destination_delivery_up`, labelled by module, destination, and
-role.
+role. Check the intended destination and ordinary report timestamps separately;
+a configured destination is not an accepted report, and accepted agent
+telemetry is not confirmation of PVE/PBS registration. For a refused report,
+use the [401/403 reporting checks](#agent-lookup-returns-http-401-or-403), not
+broader permissions or another setup attempt.
### Advanced Flags
diff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.md
index cd21a4d714..e6a9f9deb9 100644
--- a/frontend-modern/public/docs/UNIFIED_AGENT.md
+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md
@@ -630,9 +630,21 @@ and persisted host-report buffers are isolated per destination, so an observer
outage does not replay or block the primary stream. Observer responses cannot
change configuration, execute commands, enroll the agent, or select updates.
-Create a separate API token on each observer and store every token in its own
-absolute-path file. On Unix, both the JSON file and token files must be regular,
-non-symlink files with no group or other permissions (for example mode `0600`).
+**Report-only is a control boundary, not a redaction boundary.** Each observer
+receives the enabled modules' reports, including their infrastructure identities
+and metadata; this is not a reduced or anonymised copy. Choose only destinations
+allowed to hold that data. Adding an observer does not replace the primary
+server, and its delivery health does not establish primary delivery or recovery.
+
+### Choose telemetry only or Proxmox registration
+
+For an additional telemetry destination, explicitly set **`provisionProxmox` to
+`false`**, as in this example. Create a separate API token on that observer and
+store it in its own absolute-path file; do not reuse the primary server's token.
+On Unix, both the JSON file and token files must be regular, non-symlink files
+with no group or other permissions (for example mode `0600`). They must be
+readable by the actual agent service account. Use a private editor, not a token
+in a command, URL, JSON field or issue report.
```json
{
@@ -643,30 +655,57 @@ non-symlink files with no group or other permissions (for example mode `0600`).
"url": "https://pulse-dev.example.test",
"tokenFile": "/etc/pulse-agent/dev-observer.token",
"serverFingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
- "provisionProxmox": true
+ "provisionProxmox": false
}
]
}
```
-Start or install the service with
-`--observers-file /etc/pulse-agent/observers.json`. Plaintext remote HTTP is
-rejected unless that observer explicitly sets `"allowPlaintextHTTP": true`.
-`insecureSkipVerify` is available per observer but should be replaced with a
-CA file or certificate fingerprint wherever possible.
+The fingerprint above is a placeholder, not a trusted certificate. Obtain the
+observer's actual fingerprint through a separately trusted path, or use
+`caCertPath` for a verified CA file. Keep HTTPS verification enabled. A
+certificate error is not a reason to enable `insecureSkipVerify` or change to
+HTTP. Every non-loopback HTTP observer, including a private-LAN address,
+requires its own `allowPlaintextHTTP` opt-in; that sends its API token and
+reports in cleartext. The primary server's HTTP consent does not authorise an
+observer.
-When Proxmox integration is enabled, each observer gets a distinct
-destination-scoped PVE/PBS API token and registration-state directory. Pulse
-must answer the registration check before the agent creates or rotates any
-Proxmox token; an unavailable destination therefore leaves existing
-credentials unchanged. Set `"provisionProxmox": false` when an observer should
-receive only Unified Agent telemetry and no separately registered PVE/PBS
-source.
+| Proxmox choice | Effect when Proxmox integration is enabled |
+| --- | --- |
+| `"provisionProxmox": false` | Sends agent telemetry without creating or repairing this observer's separately registered PVE/PBS source. It does not disable ordinary host, Docker/Podman or Kubernetes reports. |
+| `true`, or the field omitted | Includes this observer in Proxmox setup and periodic registration health checks. The agent can create or rotate a destination-scoped PVE/PBS API token and register its credentials with that Pulse server. |
+
+**Omitting the field defaults to `true`, not telemetry only.** Choose that
+additional API access deliberately; do not enable Proxmox integration or widen
+permissions merely to make observer telemetry appear. Pulse must answer the
+registration check before token creation or rotation; an unavailable
+destination leaves existing credentials unchanged. Each observer has a distinct
+Proxmox token and registration-state directory, not the primary's credentials.
+
+Changing the field to `false` is not revocation of a previously issued Proxmox
+token, removal of an existing Pulse connection, or deletion of reports already
+stored by the observer. Plan any intended credential or connection retirement
+separately, preserving the primary's access and monitoring; do not delete agent
+state or re-enrol it to change this choice.
+
+### Apply and check the intended destination
+
+For a planned installation, pass
+`--observers-file /etc/pulse-agent/observers.json` through the
+[private-file installation procedure](#private-file-installation-linux-macos-and-nas).
+For an existing service, preserve its primary URL, credential, identity and
+other saved settings when scheduling the change; do not reinstall or restart
+merely to diagnose missing reports. Follow [backup safety](VM_DISK_MONITORING.md#backup-safety)
+if a guest or freeze/thaw operation is uncertain.
Per-destination delivery status is exported on the health listener as
`pulse_agent_destination_configured` and
`pulse_agent_destination_delivery_up`, labelled by module, destination, and
-role.
+role. Check the intended destination and ordinary report timestamps separately;
+a configured destination is not an accepted report, and accepted agent
+telemetry is not confirmation of PVE/PBS registration. For a refused report,
+use the [401/403 reporting checks](#agent-lookup-returns-http-401-or-403), not
+broader permissions or another setup attempt.
### Advanced Flags
diff --git a/frontend-modern/src/features/docs/__tests__/agentObserverGuide.test.ts b/frontend-modern/src/features/docs/__tests__/agentObserverGuide.test.ts
new file mode 100644
index 0000000000..80a442a07d
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/agentObserverGuide.test.ts
@@ -0,0 +1,79 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { renderDocMarkdown } from '../docMarkdown';
+
+const frontendRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const readDoc = (name: string) =>
+ readFileSync(path.join(frontendRoot, '../docs', `${name}.md`), 'utf8');
+const source = readDoc('UNIFIED_AGENT');
+
+function observerSection() {
+ const article = document.createElement('article');
+ article.innerHTML = renderDocMarkdown(source, 'UNIFIED_AGENT');
+ const heading = article.querySelector('#observer-destinations');
+ expect(heading).not.toBeNull();
+ const section = document.createElement('section');
+ for (let node = heading!.nextElementSibling; node && node.id !== 'advanced-flags';) {
+ section.append(node.cloneNode(true));
+ node = node.nextElementSibling;
+ }
+ return section;
+}
+
+describe('Agent observer trust and API-access choice', () => {
+ it('renders a copyable explicit telemetry-only recipe with separate credentials and trust', () => {
+ const section = observerSection();
+ const fences = section.querySelectorAll('pre code');
+ expect(fences).toHaveLength(1);
+ const config = JSON.parse(fences[0].textContent!);
+ expect(config.version).toBe(1);
+ expect(config.observers).toHaveLength(1);
+ expect(config.observers[0]).toMatchObject({
+ url: 'https://pulse-dev.example.test',
+ tokenFile: '/etc/pulse-agent/dev-observer.token',
+ provisionProxmox: false,
+ });
+ expect(config.observers[0].serverFingerprint).toMatch(/^[0-9a-f]{64}$/);
+ expect(config.observers[0].token).toBeUndefined();
+ expect(config.observers[0].insecureSkipVerify).toBeUndefined();
+ expect(config.observers[0].allowPlaintextHTTP).toBeUndefined();
+ const text = section.textContent!.replace(/\s+/g, ' ');
+ expect(text).toContain('placeholder, not a trusted certificate');
+ expect(text).toContain('Report-only is a control boundary, not a redaction boundary');
+ });
+
+ it('keeps the omitted-field default and irreversible-access limits beside the choice', () => {
+ const section = observerSection();
+ const rows = [...section.querySelectorAll('tbody tr')];
+ expect(rows).toHaveLength(2);
+ expect(rows[0].textContent).toContain('"provisionProxmox": false');
+ expect(rows[1].textContent).toContain('true, or the field omitted');
+ const text = section.textContent!.replace(/\s+/g, ' ');
+ expect(text).toContain('Omitting the field defaults to true, not telemetry only');
+ expect(text).toContain('register its credentials with that Pulse server');
+ expect(text).toContain('not revocation of a previously issued Proxmox token');
+ expect(text).toContain('not a reduced or anonymised copy');
+ expect(text).toContain('primary server\'s HTTP consent does not authorise an observer');
+ });
+
+ it('retains real setup, safe-reporting and backup links through the consuming renderer', () => {
+ const section = observerSection();
+ const targets = [
+ ['UNIFIED_AGENT', 'private-file-installation-linux-macos-and-nas'],
+ ['UNIFIED_AGENT', 'agent-lookup-returns-http-401-or-403'],
+ ['VM_DISK_MONITORING', 'backup-safety'],
+ ];
+ for (const [doc, anchor] of targets) {
+ const href = doc === 'UNIFIED_AGENT' ? `#${anchor}` : `/docs/${doc}#${anchor}`;
+ expect(section.querySelector(`a[href="${href}"]`)).not.toBeNull();
+ const article = document.createElement('article');
+ article.innerHTML = renderDocMarkdown(readDoc(doc), doc);
+ expect(article.querySelector(`#${anchor}`)).not.toBeNull();
+ }
+ expect(readFileSync(path.join(frontendRoot, 'public/docs/UNIFIED_AGENT.md'), 'utf8')).toBe(
+ source,
+ );
+ });
+});
diff --git a/internal/agenttarget/documented_observer_test.go b/internal/agenttarget/documented_observer_test.go
new file mode 100644
index 0000000000..8bc5aa6fcb
--- /dev/null
+++ b/internal/agenttarget/documented_observer_test.go
@@ -0,0 +1,85 @@
+package agenttarget
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+// Exercise the shipped recipe through the actual parser. No provider request,
+// service installation or Proxmox credential operation is needed to choose it.
+func TestDocumentedObserverTelemetryChoice(t *testing.T) {
+ doc, err := os.ReadFile("../../docs/UNIFIED_AGENT.md")
+ if err != nil {
+ t.Fatal(err)
+ }
+ _, section, ok := strings.Cut(string(doc), "## Observer destinations\n")
+ if !ok {
+ t.Fatal("observer guide missing")
+ }
+ section, _, _ = strings.Cut(section, "### Advanced Flags\n")
+ _, fence, ok := strings.Cut(section, "```json\n")
+ if !ok {
+ t.Fatal("documented observer JSON missing")
+ }
+ fence, _, _ = strings.Cut(fence, "```")
+ var config observerFile
+ if err := json.Unmarshal([]byte(fence), &config); err != nil {
+ t.Fatal(err)
+ }
+ if config.Version != ConfigVersion || len(config.Observers) != 1 {
+ t.Fatal("documented observer shape changed")
+ }
+ target := &config.Observers[0]
+ if target.ProvisionProxmox == nil || *target.ProvisionProxmox || target.InsecureSkipVerify || target.AllowPlaintextHTTP || !strings.HasPrefix(target.URL, "https://") {
+ t.Fatal("telemetry recipe must explicitly avoid extra API provisioning and retain verified HTTPS")
+ }
+ if !filepath.IsAbs(target.TokenFile) || target.ServerFingerprint == "" {
+ t.Fatal("recipe must use a private token file and explicit trust")
+ }
+
+ dir := t.TempDir()
+ target.TokenFile = filepath.Join(dir, "observer.token")
+ writePrivateFile(t, target.TokenFile, "synthetic-docs-observer-token\n")
+ configPath := filepath.Join(dir, "observers.json")
+ load := func() ([]Observer, error) {
+ t.Helper()
+ data, err := json.Marshal(config)
+ if err != nil {
+ t.Fatal(err)
+ }
+ writePrivateFile(t, configPath, string(data))
+ return LoadObservers(configPath, "https://primary.example.test")
+ }
+ t.Run("documented-telemetry-only", func(t *testing.T) {
+ got, err := load()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(got) != 1 || got[0].ProvisionProxmox || got[0].Token != "synthetic-docs-observer-token" {
+ t.Fatal("documented choice did not survive actual loading")
+ }
+ })
+ t.Run("omission-is-not-telemetry-only", func(t *testing.T) {
+ saved := target.ProvisionProxmox
+ target.ProvisionProxmox = nil
+ defer func() { target.ProvisionProxmox = saved }()
+ got, err := load()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !got[0].ProvisionProxmox {
+ t.Fatal("guide's omitted-field warning must match the runtime default")
+ }
+ })
+ t.Run("primary-local-http-policy-is-not-observer-consent", func(t *testing.T) {
+ saved := target.URL
+ target.URL = "http://192.168.50.10:7655"
+ defer func() { target.URL = saved }()
+ if _, err := load(); err == nil {
+ t.Fatal("observer recipe must not silently accept private-LAN plaintext")
+ }
+ })
+}