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.

Explain the agent-local private registry login boundary

pulse-triage[bot]ed33b67bcac6
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 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:
```bash
docker 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 than
the 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.md
index 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:
```bash
docker 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 than
the 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.py
new file mode 100644
index 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()