-{"body":"## Summary\n\nWhen `box-dind` is run with host-image passthrough **enabled** (the default,\n`DIND_HOST_PASSTHROUGH=public`) **and an explicit image allowlist set**\n(`DIND_HOST_PASSTHROUGH_IMAGES=...`), but the host Docker socket is **not**\nbind-mounted, passthrough is a **silent no-op**: the entrypoint copies nothing,\nprints nothing, and the nested daemon stays empty. The operator clearly opted in\n(they named the images they want passed through), yet the first nested\n`docker run` re-pulls the full image from the registry with no hint as to why.\n\nThis is a deliberate design choice today — see the comment at\n[`dind-entrypoint.sh` L401-L408](https://github.com/link-foundation/box/blob/b81aee7ab1dc2bda53733e80739e3b2284f38571/ubuntu/24.04/dind/dind-entrypoint.sh#L401-L408):\n\n```sh\n if ! host_docker_available; then\n # A socket file exists but is unreachable: surface it. Otherwise the common\n # \"no host socket mounted\" case stays silent so the default mode is free.\n if [ -n \"$DIND_HOST_DOCKER_SOCK\" ] \u0026\u0026 [ -e \"$DIND_HOST_DOCKER_SOCK\" ]; then\n warn \"host docker socket at ${DIND_HOST_DOCKER_SOCK} is not accessible; skipping passthrough\"\n fi\n return 0\n fi\n```\n\nStaying silent for plain `box-dind` containers that never intended passthrough is\nreasonable. But when the operator has set `DIND_HOST_PASSTHROUGH_IMAGES`, that is\nan unambiguous opt-in signal that they **expect** passthrough to work — and a\nmissing socket means it silently won't. That mismatch is a footgun.\n\n## Impact (real-world)\n\nThis bit us in `link-assistant/hive-mind`\n([#1914](https://github.com/link-assistant/hive-mind/issues/1914)): a Telegram\nbot runs inside `konard/hive-mind-dind` (based on `konard/box-dind`) and launches\nisolated tasks as nested `docker run konard/hive-mind-dind:latest`. The image is\n**30+ GB**. The deploy intended host passthrough but the bot container's\n`docker run` never mounted the host socket. Because passthrough was silent, the\nempty nested daemon re-pulled the entire 30 GB image on the first isolated task —\nwith no log line anywhere explaining that passthrough had been skipped. It took a\nsource dive to find the missing `-v` flag.\n\n## Reproducible example\n\n```bash\n# Host already has the image we want to reuse inside the nested daemon:\ndocker pull hello-world\n\n# Run box-dind with passthrough ENABLED + an explicit allowlist, but WITHOUT\n# mounting the host socket (the bug):\ndocker run --rm -it --privileged \\\n -e DIND_HOST_PASSTHROUGH=public \\\n -e DIND_HOST_PASSTHROUGH_IMAGES=\"hello-world\" \\\n konard/box-dind:latest \\\n bash -lc 'docker run --rm hello-world'\n# Observed: the nested daemon PULLS hello-world from the registry.\n# No warning that passthrough was skipped because no socket was mounted.\n\n# Correct invocation (what the operator forgot) — works as intended:\ndocker run --rm -it --privileged \\\n -v /var/run/docker.sock:/var/run/host-docker.sock:ro \\\n -e DIND_HOST_PASSTHROUGH=public \\\n -e DIND_HOST_PASSTHROUGH_IMAGES=\"hello-world\" \\\n konard/box-dind:latest \\\n bash -lc 'docker run --rm hello-world'\n# Observed: \"passthrough loading host image: hello-world:latest\" then reuse (no pull).\n```\n\n## Workaround\n\nMount the host socket read-only (this is the documented-but-easy-to-forget step):\n\n```\n-v /var/run/docker.sock:/var/run/host-docker.sock:ro\n```\n\n…or preload the image into the running container manually with\n`docker save … | docker load`.\n\n## Suggested fix (warn on opt-in + missing socket)\n\nKeep the default-mode silence, but add a single warning when there is a clear\nopt-in signal yet no socket. Minimal change to `passthrough_host_images`\n([L401-L408](https://github.com/link-foundation/box/blob/b81aee7ab1dc2bda53733e80739e3b2284f38571/ubuntu/24.04/dind/dind-entrypoint.sh#L401-L408)):\n\n```sh\n if ! host_docker_available; then\n if [ -n \"$DIND_HOST_DOCKER_SOCK\" ] \u0026\u0026 [ -e \"$DIND_HOST_DOCKER_SOCK\" ]; then\n # Socket file exists but is unreachable.\n warn \"host docker socket at ${DIND_HOST_DOCKER_SOCK} is not accessible; skipping passthrough\"\n elif [ -n \"$DIND_HOST_PASSTHROUGH_IMAGES\" ]; then\n # Operator opted in via an allowlist but no host socket is mounted: the\n # nested daemon will NOT be seeded and the first nested 'docker run' will\n # re-pull from the registry. Surface it instead of failing silently.\n warn \"host-image passthrough is enabled and DIND_HOST_PASSTHROUGH_IMAGES is set, but no host docker socket is mounted at ${DIND_HOST_DOCKER_SOCK}; the nested daemon will NOT be seeded from the host (first 'docker run' will pull from the registry). Mount it with: -v /var/run/docker.sock:${DIND_HOST_DOCKER_SOCK}:ro\"\n fi\n # Otherwise (no opt-in signal) the common \"no host socket mounted\" case stays\n # silent so plain box-dind containers are not spammed.\n return 0\n fi\n```\n\nRationale for gating on `DIND_HOST_PASSTHROUGH_IMAGES` (rather than warning\nwhenever the default `public` mode has no socket): a non-empty allowlist is an\nexplicit \"I want these images passed through\" signal, so a missing socket is\nalmost certainly a misconfiguration worth surfacing — while plain `box-dind`\nusers who never touched passthrough see no new noise. (If you'd prefer, the same\nwarning could also fire when `DIND_HOST_PASSTHROUGH` was *explicitly* set by the\noperator vs. defaulted, but the allowlist gate alone already covers the common\nopt-in case and needs no \"explicit vs default\" tracking.)\n\nOptionally, a one-line summary after a successful passthrough pass\n(`passthrough: copied N, skipped M`) would further improve observability, but the\nmissing-socket warning above is the important fix.\n\n## Notes\n\n- box already handles the *present-but-unreachable* socket correctly (it warns).\n This request is only about the *absent* socket + explicit opt-in case.\n- Downstream, we added a startup preflight in hive-mind that probes the nested\n daemon and prints this exact remediation, so we are covered operationally; this\n upstream change would help everyone who uses `box-dind` passthrough, not just us.\n- Observed on `konard/box-dind` at v2.3.1 / main `b81aee7`.\n","closed_at":"2026-06-13T13:03:43Z","created_at":"2026-06-13T11:40:19Z","html_url":"https://github.com/link-foundation/box/issues/102","number":102,"state":"closed","state_reason":"completed","title":"dind passthrough: silent no-op when DIND_HOST_PASSTHROUGH_IMAGES is set but no host socket is mounted"}
0 commit comments