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.

Keep provider connection setup within intended trust and access

pulse-triage[bot]bdc42cf341e3
diff --git a/docs/MSP.md b/docs/MSP.md
index 94f463a90b..c58929a592 100644
--- a/docs/MSP.md
+++ b/docs/MSP.md
@@ -206,26 +206,53 @@ both paths in your firewall:
| Proxmox/PBS polling | provider → client site, through the tunnel | 8006 / 8007 |
| Agent check-in (hosts) | client site → provider agent ingest | `PULSE_AGENT_INGEST_PORT` (7656) |
-Per client, the steps are:
-
-1. Make the client's PVE/PBS API address reachable from the Docker host that
- runs the client workspaces (route or interface into that client's
- tunnel). From that host, make a bounded unauthenticated HTTPS request to
- the PVE/PBS API with certificate verification enabled. For a private or
- self-signed certificate, use `--cacert` with an independently verified
- certificate/CA. A TLS error is not proof of a blocked tunnel, and an HTTP
- response is not proof that Pulse's configured account can collect data.
-2. Open the client's workspace (portal → workspace → **Open**) and add the
- node under **Settings → Infrastructure**, using the tunnel-reachable
- address. The guided flow generates a setup command to run once on the
- client's Proxmox host (over SSH through the same tunnel); it creates the
- monitoring user, API token, and permissions. Self-signed certificates
- are handled automatically (the certificate fingerprint is pinned on
- first connect).
-3. If you create the token by hand instead, note that Proxmox
- privilege-separated tokens need ACLs on the **token** as well as the
- user, and the built-in `PVEAuditor` role is not sufficient on its own —
- see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for the exact role setup.
+Per client, choose the intended network, trust and access before adding the
+connection:
+
+1. Route the client's PVE/PBS API address to the **client workspace's Pulse
+ runtime**, through that client's tunnel. Reaching it from the Docker host
+ is only a preliminary check: the runtime can have different routes, DNS
+ and certificate trust. An HTTP response proves neither authenticated
+ collection nor access to every cluster member. Keep the API behind the
+ intended VPN and firewall; do not expose it publicly to bypass a routing
+ problem.
+2. Establish certificate trust through an independently trusted client console
+ or administration channel. For a private CA, the **runtime** needs the
+ intended CA chain and matching endpoint hostname; alternatively use an
+ independently verified SHA-256 leaf fingerprint. Guided registration can
+ capture and pin the certificate it first reaches, but **first-seen pinning
+ does not independently authenticate the server**. Do not accept a suggested
+ replacement solely from the failing connection, copy one member's pin to
+ its peers, or disable verification. See [certificate trust and renewal](TROUBLESHOOTING.md#proxmox-or-pbs-certificate-validation-failed).
+3. Choose a dedicated API identity restricted to the intended client resources.
+ For PVE, `PVEAuditor` provides baseline inventory and metrics; optional guest
+ reads can need additional privileges. With privilege separation enabled,
+ effective access is the **intersection of the user and token permissions**
+ at the affected resource path. Keep privilege separation enabled and do not
+ modify the built-in role or widen access to other departments merely to
+ silence errors. For PBS, use its [dedicated read-only token guidance](PBS.md#pbs-permissions).
+4. If choosing guided PVE setup, have the client's administrator inspect it
+ before execution. It is an **administrative change, not a read-only test**:
+ it creates or updates the monitoring identity, token and ACLs at `/`, and
+ can add `VM.GuestAgent.Audit` and `VM.GuestAgent.FileRead` on PVE 9, or the
+ broader legacy `VM.Monitor` fallback on PVE 8. An existing deliberately
+ scoped token can be entered directly instead. Keep token secrets in the
+ private setup prompt or connection form, never a command line or public
+ report. Do not rerun setup or rotate a working token to diagnose a missing
+ optional reading; [intentional optional denials](TROUBLESHOOTING.md#optional-proxmox-checks-return-403-repeatedly)
+ can remain unavailable without granting more access.
+5. Open the intended client's workspace (portal → workspace → **Open**) and
+ add its connection under **Settings → Infrastructure**, using the
+ tunnel-reachable endpoint and chosen trust and token. Check ordinary
+ polling for each intended member and reading; **Test Connection** on the
+ primary is not proof that all members or optional checks work. Keep
+ unavailable readings distinct from measured zero. Preserve existing
+ connections and credentials when a check fails; use the linked
+ troubleshooting guidance rather than repeating setup.
+
+During a backup, uncertain freeze/thaw or an unresponsive-guest incident,
+defer setup, live tests and guest-agent probes. Follow [backup safety](VM_DISK_MONITORING.md#backup-safety)
+first; this connection workflow is not guest recovery.
Because each client workspace is its own runtime, overlapping RFC1918
subnets across client sites never collide inside Pulse: each workspace only
diff --git a/frontend-modern/public/docs/MSP.md b/frontend-modern/public/docs/MSP.md
index 94f463a90b..c58929a592 100644
--- a/frontend-modern/public/docs/MSP.md
+++ b/frontend-modern/public/docs/MSP.md
@@ -206,26 +206,53 @@ both paths in your firewall:
| Proxmox/PBS polling | provider → client site, through the tunnel | 8006 / 8007 |
| Agent check-in (hosts) | client site → provider agent ingest | `PULSE_AGENT_INGEST_PORT` (7656) |
-Per client, the steps are:
-
-1. Make the client's PVE/PBS API address reachable from the Docker host that
- runs the client workspaces (route or interface into that client's
- tunnel). From that host, make a bounded unauthenticated HTTPS request to
- the PVE/PBS API with certificate verification enabled. For a private or
- self-signed certificate, use `--cacert` with an independently verified
- certificate/CA. A TLS error is not proof of a blocked tunnel, and an HTTP
- response is not proof that Pulse's configured account can collect data.
-2. Open the client's workspace (portal → workspace → **Open**) and add the
- node under **Settings → Infrastructure**, using the tunnel-reachable
- address. The guided flow generates a setup command to run once on the
- client's Proxmox host (over SSH through the same tunnel); it creates the
- monitoring user, API token, and permissions. Self-signed certificates
- are handled automatically (the certificate fingerprint is pinned on
- first connect).
-3. If you create the token by hand instead, note that Proxmox
- privilege-separated tokens need ACLs on the **token** as well as the
- user, and the built-in `PVEAuditor` role is not sufficient on its own —
- see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for the exact role setup.
+Per client, choose the intended network, trust and access before adding the
+connection:
+
+1. Route the client's PVE/PBS API address to the **client workspace's Pulse
+ runtime**, through that client's tunnel. Reaching it from the Docker host
+ is only a preliminary check: the runtime can have different routes, DNS
+ and certificate trust. An HTTP response proves neither authenticated
+ collection nor access to every cluster member. Keep the API behind the
+ intended VPN and firewall; do not expose it publicly to bypass a routing
+ problem.
+2. Establish certificate trust through an independently trusted client console
+ or administration channel. For a private CA, the **runtime** needs the
+ intended CA chain and matching endpoint hostname; alternatively use an
+ independently verified SHA-256 leaf fingerprint. Guided registration can
+ capture and pin the certificate it first reaches, but **first-seen pinning
+ does not independently authenticate the server**. Do not accept a suggested
+ replacement solely from the failing connection, copy one member's pin to
+ its peers, or disable verification. See [certificate trust and renewal](TROUBLESHOOTING.md#proxmox-or-pbs-certificate-validation-failed).
+3. Choose a dedicated API identity restricted to the intended client resources.
+ For PVE, `PVEAuditor` provides baseline inventory and metrics; optional guest
+ reads can need additional privileges. With privilege separation enabled,
+ effective access is the **intersection of the user and token permissions**
+ at the affected resource path. Keep privilege separation enabled and do not
+ modify the built-in role or widen access to other departments merely to
+ silence errors. For PBS, use its [dedicated read-only token guidance](PBS.md#pbs-permissions).
+4. If choosing guided PVE setup, have the client's administrator inspect it
+ before execution. It is an **administrative change, not a read-only test**:
+ it creates or updates the monitoring identity, token and ACLs at `/`, and
+ can add `VM.GuestAgent.Audit` and `VM.GuestAgent.FileRead` on PVE 9, or the
+ broader legacy `VM.Monitor` fallback on PVE 8. An existing deliberately
+ scoped token can be entered directly instead. Keep token secrets in the
+ private setup prompt or connection form, never a command line or public
+ report. Do not rerun setup or rotate a working token to diagnose a missing
+ optional reading; [intentional optional denials](TROUBLESHOOTING.md#optional-proxmox-checks-return-403-repeatedly)
+ can remain unavailable without granting more access.
+5. Open the intended client's workspace (portal → workspace → **Open**) and
+ add its connection under **Settings → Infrastructure**, using the
+ tunnel-reachable endpoint and chosen trust and token. Check ordinary
+ polling for each intended member and reading; **Test Connection** on the
+ primary is not proof that all members or optional checks work. Keep
+ unavailable readings distinct from measured zero. Preserve existing
+ connections and credentials when a check fails; use the linked
+ troubleshooting guidance rather than repeating setup.
+
+During a backup, uncertain freeze/thaw or an unresponsive-guest incident,
+defer setup, live tests and guest-agent probes. Follow [backup safety](VM_DISK_MONITORING.md#backup-safety)
+first; this connection workflow is not guest recovery.
Because each client workspace is its own runtime, overlapping RFC1918
subnets across client sites never collide inside Pulse: each workspace only
diff --git a/scripts/tests/test_msp_connection_docs.py b/scripts/tests/test_msp_connection_docs.py
new file mode 100644
index 0000000000..f4fc9b2270
--- /dev/null
+++ b/scripts/tests/test_msp_connection_docs.py
@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Keep provider connection help within the chosen network and access boundary.
+
+Source/document consistency only: no setup script, provider call, ACL or guest
+operation is executed. The normal documentation shards discover this suite.
+"""
+
+from pathlib import Path
+import re
+import unittest
+
+ROOT = Path(__file__).resolve().parents[2]
+HEADING = "## Connecting a client's Proxmox or PBS over your VPN\n"
+
+
+def connection_help():
+ text = (ROOT / "docs/MSP.md").read_text(encoding="utf-8")
+ return text.split(HEADING, 1)[1].split("\n## ", 1)[0]
+
+
+class MSPConnectionDocsTest(unittest.TestCase):
+ def test_host_connectivity_is_not_runtime_or_collection_acceptance(self):
+ text = " ".join(connection_help().split())
+ for distinction in (
+ "client workspace's Pulse runtime", "only a preliminary check",
+ "different routes, DNS and certificate trust",
+ "neither authenticated collection nor access to every cluster member",
+ "do not expose it publicly", "ordinary polling for each intended member",
+ "primary is not proof that all members or optional checks work",
+ "unavailable readings distinct from measured zero",
+ ):
+ with self.subTest(distinction=distinction):
+ self.assertIn(distinction, text)
+
+ def test_first_seen_pin_is_not_independent_server_authentication(self):
+ text = " ".join(connection_help().split())
+ for boundary in (
+ "independently trusted client console", "**runtime** needs",
+ "matching endpoint hostname", "independently verified SHA-256",
+ "first-seen pinning does not independently authenticate the server",
+ "solely from the failing connection", "copy one member's pin",
+ "disable verification",
+ ):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, text)
+ self.assertNotIn("Self-signed certificates are handled automatically", text)
+ source = (ROOT / "internal/api/configapi/config_setup_handlers.go").read_text()
+ selection = source.split("func selectAutoRegisterHost(", 1)[1].split("\nfunc ", 1)[0]
+ self.assertIn("fetchTLSFingerprint(candidate)", selection)
+ self.assertIn("return candidate, fingerprint, true, candidates, nil", selection)
+
+ def test_generated_root_acls_and_optional_reads_are_not_required_baseline(self):
+ text = " ".join(connection_help().split())
+ for boundary in (
+ "`PVEAuditor` provides baseline inventory and metrics",
+ "intersection of the user and token permissions",
+ "Keep privilege separation enabled", "do not modify the built-in role",
+ "administrative change, not a read-only test", "ACLs at `/`",
+ "`VM.GuestAgent.Audit`", "`VM.GuestAgent.FileRead`", "`VM.Monitor`",
+ "existing deliberately scoped token can be entered directly",
+ "never a command line or public report", "Do not rerun setup",
+ "remain unavailable without granting more access",
+ ):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, text)
+ self.assertNotIn("`PVEAuditor` role is not sufficient on its own", text)
+ source = (ROOT / "internal/api/configapi/setup_script_render.go").read_text()
+ for marker in (
+ "pveum aclmod / -user pulse-monitor@pve -role PVEAuditor",
+ 'pveum aclmod / -token "$PULSE_TOKEN_ID" -role PulseMonitor',
+ 'EXTRA_PRIVS+=("VM.GuestAgent.Audit")',
+ 'EXTRA_PRIVS+=("VM.GuestAgent.FileRead")',
+ 'EXTRA_PRIVS+=("VM.Monitor")',
+ ):
+ self.assertIn(marker, source)
+
+ def test_existing_help_targets_safety_and_shipped_copy_remain_usable(self):
+ section = connection_help()
+ text = " ".join(section.split())
+ self.assertIn("defer setup, live tests and guest-agent probes", text)
+ self.assertIn("this connection workflow is not guest recovery", text)
+ self.assertNotIn("```", section, "reuse existing guidance, not a new secret-bearing command")
+ links = re.findall(r"\]\(([A-Z_]+\.md)#([a-z0-9-]+)\)", section)
+ self.assertGreaterEqual(len(links), 4)
+ for name, anchor in links:
+ target = (ROOT / "docs" / name).read_text(encoding="utf-8")
+ headings = re.findall(r"^#+ (.+)$", target, re.MULTILINE)
+ anchors = [re.sub(r"[^\w -]", "", h).strip().lower().replace(" ", "-") for h in headings]
+ with self.subTest(link=f"{name}#{anchor}"):
+ self.assertIn(anchor, anchors)
+ self.assertEqual(
+ (ROOT / "docs/MSP.md").read_bytes(),
+ (ROOT / "frontend-modern/public/docs/MSP.md").read_bytes(),
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()