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
Make observer telemetry and Proxmox access separate choices
pulse-triage[bot]78e6a9ebb47e
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.mdindex 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 observeroutage does not replay or block the primary stream. Observer responses cannotchange 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 Flagsdiff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.mdindex 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 observeroutage does not replay or block the primary stream. Observer responses cannotchange 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 Flagsdiff --git a/frontend-modern/src/features/docs/__tests__/agentObserverGuide.test.ts b/frontend-modern/src/features/docs/__tests__/agentObserverGuide.test.tsnew file mode 100644index 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.gonew file mode 100644index 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")+ }+ })+}