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
Explain the agent-local private registry login boundary
pulse-triage[bot]ed33b67bcac6
diff --git a/docs/DOCKER.md b/docs/DOCKER.mdindex a8832a4a48..61435e27fd 100644--- a/docs/DOCKER.md+++ b/docs/DOCKER.md@@ -468,15 +468,64 @@ other container names, environments or registry credentials.### Private Registries-For private registries, log in with Docker on the container host **as the user the agent runs as** (the installer's systemd service runs the agent as root, so use `sudo docker login`):+Private-image update detection runs on the monitored host's unified agent,+not on the Pulse server. It uses the login visible to that agent process;+a successful pull in another user's shell does not prove the agent can+authenticate. Detection does not require enabling command execution.++**Native agent:** use its actual service account, home and service environment.+Root and least-privilege installations can use different accounts. Log in+interactively in the intended account and environment:```bashdocker login registry.example.com```-Pulling updates goes through the Docker daemon, which reads these credentials natively. Update **detection** reads the same credential store: `config.json` `auths` entries, configured `credsStore`/`credHelpers` credential helpers, and Podman's `auth.json` (`REGISTRY_AUTH_FILE` and `DOCKER_CONFIG` overrides are honored). The agent presents the stored login to the registry when it rejects anonymous digest checks, so private images get real update detection instead of a permanent failed check. Credentials never leave the host — they are only sent to the registry itself and are never reported to the Pulse server.--To keep update detection anonymous-only (no credential store reads, no credential helper execution), set `PULSE_DISABLE_REGISTRY_CREDENTIALS=true` (or pass `--disable-registry-credentials`) on the agent.+Use `sudo docker login` only for an agent that actually runs as root. Do not+switch the agent to root or make credentials world-readable to fix detection.+Use a dedicated pull-only registry account where the registry supports one.++The agent looks for credentials in these files, in order, using the first+usable login for the registry:++- `REGISTRY_AUTH_FILE`: an explicit Docker/Podman authentication file.+- `DOCKER_CONFIG`: a directory containing `config.json`, when set.+- `$HOME/.docker/config.json`: the agent process's home, not your interactive+ user's home.+- `$XDG_RUNTIME_DIR/containers/auth.json`: Podman's runtime login, when+ `XDG_RUNTIME_DIR` is set.++Docker `auths`, per-registry `credHelpers` and global `credsStore` are supported.+A configured credential helper needs its helper binary and its backing store+accessible in the agent's runtime, not just `config.json`.++**Containerised agent:** Docker socket access does not expose the host's login+files. Any credential file must be visible in the container's filesystem and+readable by its agent user. If supplying a dedicated authentication file, mount+only that file read-only and set `REGISTRY_AUTH_FILE` in the agent environment+to its container path. A read-only mount still lets the agent read its secrets.+Do not mount an entire home directory or copy logins into the Pulse server.+A helper-backed host login also needs the helper and backing store; mounting+`config.json` alone is not enough.++Credentials are sent directly to the registry or its authentication endpoint,+not reported to the Pulse server. Credential lookups are cached for up to+five minutes, including missing logins; a changed login may not be picked up+until the next ordinary scheduled check. Successful detection is not proof+that a workload update can pull or recreate the container: that is a separate+[reviewed action](#️-container-lifecycle-actions).++**“Check failed” is not evidence that the image is up to date.** Read its existing+short error before changing credentials: an authentication failure and a TLS or+network failure need different remedies. Do not disable TLS verification.+For help, give the agent version, native/container deployment and that short+error with registry/image names removed. Never share login files, helper output,+passwords or tokens.++To keep detection anonymous-only, set `PULSE_DISABLE_REGISTRY_CREDENTIALS=true`+(or pass `--disable-registry-credentials`) on the agent: no credential-file reads+or helper execution. Private images requiring authentication will then fail+the check rather than report a fabricated result.Paid Pulse Pro Docker installs use the private Pulse Pro registry rather thanthe public `rcourtman/pulse` image. Open <https://pulserelay.pro/download.html>,diff --git a/frontend-modern/public/docs/DOCKER.md b/frontend-modern/public/docs/DOCKER.mdindex a8832a4a48..61435e27fd 100644--- a/frontend-modern/public/docs/DOCKER.md+++ b/frontend-modern/public/docs/DOCKER.md@@ -468,15 +468,64 @@ other container names, environments or registry credentials.### Private Registries-For private registries, log in with Docker on the container host **as the user the agent runs as** (the installer's systemd service runs the agent as root, so use `sudo docker login`):+Private-image update detection runs on the monitored host's unified agent,+not on the Pulse server. It uses the login visible to that agent process;+a successful pull in another user's shell does not prove the agent can+authenticate. Detection does not require enabling command execution.++**Native agent:** use its actual service account, home and service environment.+Root and least-privilege installations can use different accounts. Log in+interactively in the intended account and environment:```bashdocker login registry.example.com```-Pulling updates goes through the Docker daemon, which reads these credentials natively. Update **detection** reads the same credential store: `config.json` `auths` entries, configured `credsStore`/`credHelpers` credential helpers, and Podman's `auth.json` (`REGISTRY_AUTH_FILE` and `DOCKER_CONFIG` overrides are honored). The agent presents the stored login to the registry when it rejects anonymous digest checks, so private images get real update detection instead of a permanent failed check. Credentials never leave the host — they are only sent to the registry itself and are never reported to the Pulse server.--To keep update detection anonymous-only (no credential store reads, no credential helper execution), set `PULSE_DISABLE_REGISTRY_CREDENTIALS=true` (or pass `--disable-registry-credentials`) on the agent.+Use `sudo docker login` only for an agent that actually runs as root. Do not+switch the agent to root or make credentials world-readable to fix detection.+Use a dedicated pull-only registry account where the registry supports one.++The agent looks for credentials in these files, in order, using the first+usable login for the registry:++- `REGISTRY_AUTH_FILE`: an explicit Docker/Podman authentication file.+- `DOCKER_CONFIG`: a directory containing `config.json`, when set.+- `$HOME/.docker/config.json`: the agent process's home, not your interactive+ user's home.+- `$XDG_RUNTIME_DIR/containers/auth.json`: Podman's runtime login, when+ `XDG_RUNTIME_DIR` is set.++Docker `auths`, per-registry `credHelpers` and global `credsStore` are supported.+A configured credential helper needs its helper binary and its backing store+accessible in the agent's runtime, not just `config.json`.++**Containerised agent:** Docker socket access does not expose the host's login+files. Any credential file must be visible in the container's filesystem and+readable by its agent user. If supplying a dedicated authentication file, mount+only that file read-only and set `REGISTRY_AUTH_FILE` in the agent environment+to its container path. A read-only mount still lets the agent read its secrets.+Do not mount an entire home directory or copy logins into the Pulse server.+A helper-backed host login also needs the helper and backing store; mounting+`config.json` alone is not enough.++Credentials are sent directly to the registry or its authentication endpoint,+not reported to the Pulse server. Credential lookups are cached for up to+five minutes, including missing logins; a changed login may not be picked up+until the next ordinary scheduled check. Successful detection is not proof+that a workload update can pull or recreate the container: that is a separate+[reviewed action](#️-container-lifecycle-actions).++**“Check failed” is not evidence that the image is up to date.** Read its existing+short error before changing credentials: an authentication failure and a TLS or+network failure need different remedies. Do not disable TLS verification.+For help, give the agent version, native/container deployment and that short+error with registry/image names removed. Never share login files, helper output,+passwords or tokens.++To keep detection anonymous-only, set `PULSE_DISABLE_REGISTRY_CREDENTIALS=true`+(or pass `--disable-registry-credentials`) on the agent: no credential-file reads+or helper execution. Private images requiring authentication will then fail+the check rather than report a fabricated result.Paid Pulse Pro Docker installs use the private Pulse Pro registry rather thanthe public `rcourtman/pulse` image. Open <https://pulserelay.pro/download.html>,diff --git a/scripts/tests/test_docker_registry_docs.py b/scripts/tests/test_docker_registry_docs.pynew file mode 100644index 0000000000..d731907b12--- /dev/null+++ b/scripts/tests/test_docker_registry_docs.py@@ -0,0 +1,83 @@+#!/usr/bin/env python3+"""Keep private-registry help faithful to the existing agent credential path.++These are documentation/safety checks, not installed registry acceptance.+Discovered by scripts/tests/run.sh and the documentation CI shards.+"""++from pathlib import Path+import re+import unittest+++ROOT = Path(__file__).resolve().parents[2]+++def section():+ return (ROOT / "docs/DOCKER.md").read_text().split(+ "### Private Registries\n", 1+ )[1].split("\n### Disabling Update Features", 1)[0]+++def prose():+ return " ".join(section().split())+++class DockerRegistryDocsTest(unittest.TestCase):+ def test_shipped_document_matches_source(self):+ self.assertEqual((ROOT / "docs/DOCKER.md").read_bytes(),+ (ROOT / "frontend-modern/public/docs/DOCKER.md").read_bytes())++ def test_login_follows_agent_account_not_an_assumed_root_service(self):+ text = prose()+ for fact in ("not on the Pulse server", "service account", "least-privilege",+ "service environment", "Do not switch the agent to root"):+ self.assertIn(fact, text)+ self.assertNotIn("the installer's systemd service runs the agent as root", text)+ self.assertIn("only for an agent that actually runs as root", text)++ def test_paths_and_cache_match_the_existing_producer(self):+ text = section()+ source = (ROOT / "internal/dockeragent/registry_credentials.go").read_text()+ for name in ("REGISTRY_AUTH_FILE", "DOCKER_CONFIG", "XDG_RUNTIME_DIR"):+ self.assertIn(f'c.getenv("{name}")', source)+ self.assertIn(f"`{name}`", text)+ for path in ("config.json", "auth.json", "$HOME/.docker/config.json",+ "$XDG_RUNTIME_DIR/containers/auth.json"):+ self.assertIn(path, text)+ self.assertRegex(source, r"credentialCacheTTL\s*=\s*5\s*\*\s*time.Minute")+ self.assertIn("up to five minutes, including missing logins", prose())+ self.assertIn("next ordinary scheduled check", prose())++ def test_container_and_helper_visibility_keep_least_privilege(self):+ text = prose()+ for fact in ("Docker socket access does not expose the host's login files",+ "container's filesystem", "read-only", "container path",+ "helper binary and its backing store", "not just `config.json`",+ "pull-only", "Do not mount an entire home directory",+ "make credentials world-readable"):+ self.assertIn(fact, text)++ def test_detection_and_workload_actions_are_not_conflated(self):+ text = prose()+ for fact in ("does not require enabling command execution",+ "not proof that a workload update can pull or recreate",+ "PULSE_DISABLE_REGISTRY_CREDENTIALS", "--disable-registry-credentials",+ "no credential-file reads or helper execution"):+ self.assertIn(fact, text)+ self.assertNotIn("daemon, which reads these credentials natively", text)++ def test_error_guidance_does_not_request_secrets_or_weaken_tls(self):+ text = prose()+ for fact in ("not evidence that the image is up to date", "existing short error",+ "TLS or network failure", "Do not disable TLS verification",+ "Never share login files, helper output, passwords or tokens",+ "registry or its authentication endpoint", "not reported to the Pulse server"):+ self.assertIn(fact, text)+ blocks = re.findall(r"```bash\n(.*?)```", section(), re.S)+ self.assertEqual(blocks, ["docker login registry.example.com\n"])+ self.assertNotRegex(text, r"(?i)(?:docker|podman) login[^`\n]*(?:--password(?:\s|=)|\s-p\s)")+++if __name__ == "__main__":+ unittest.main()