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
Keep provider connection setup within intended trust and access
pulse-triage[bot]bdc42cf341e3
diff --git a/docs/MSP.md b/docs/MSP.mdindex 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 RFC1918subnets across client sites never collide inside Pulse: each workspace onlydiff --git a/frontend-modern/public/docs/MSP.md b/frontend-modern/public/docs/MSP.mdindex 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 RFC1918subnets across client sites never collide inside Pulse: each workspace onlydiff --git a/scripts/tests/test_msp_connection_docs.py b/scripts/tests/test_msp_connection_docs.pynew file mode 100644index 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()