From 7195708176f5f4264ed33078ddec668a05bde38b Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Wed, 26 Feb 2025 14:17:23 -0800 Subject: [PATCH] Move rootless notes to a variant stub Also, add an explicit note about how to switch the UID/GID and drop the note about 19.03 (long since EOL). --- docker/content.md | 21 +-------------------- docker/variant-rootless.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 20 deletions(-) create mode 100644 docker/variant-rootless.md diff --git a/docker/content.md b/docker/content.md index d1c73c2f5f69..c8ac355a8afe 100644 --- a/docker/content.md +++ b/docker/content.md @@ -32,7 +32,7 @@ Inside the directory specified by `DOCKER_TLS_CERTDIR`, the entrypoint scripts w In order to make use of this functionality from a "client" container, at least the `client` subdirectory of the `$DOCKER_TLS_CERTDIR` directory needs to be shared (as illustrated in the following examples). -To disable this image behavior, simply override the container command or entrypoint to run `dockerd` directly (`... docker:dind dockerd ...` or `... --entrypoint dockerd docker:dind ...`). +To disable this image behavior, simply override the container command or entrypoint to run `dockerd` directly (`... %%IMAGE%%:dind dockerd ...` or `... --entrypoint dockerd %%IMAGE%%:dind ...`). ## Start a daemon instance @@ -205,25 +205,6 @@ $ docker run --privileged --name some-docker -d \ Some of these will not be supported based on the settings on the host's `dockerd`, such as `--ulimit nofile=-1`, giving errors that look like `error setting rlimit type 7: operation not permitted`, and some may inherit sane values from the host `dockerd` instance or may not apply for your usage of Docker-in-Docker (for example, you likely want to set `--oom-score-adj` to a value that's higher than `dockerd` on the host so that your Docker-in-Docker instance is killed before the host Docker instance is). -## Rootless - -For more information about using the experimental "rootless" image variants, see [docker-library/docker#174](https://github.com/docker-library/docker/pull/174). - -**Note:** just like the regular `dind` images, `--privileged` is required for Docker-in-Docker to function properly ([docker-library/docker#151](https://github.com/docker-library/docker/issues/151#issuecomment-483185972) & [docker-library/docker#281](https://github.com/docker-library/docker/issues/281#issuecomment-744766015)). For `19.03.x` rootless images, an argument of `--experimental` is required for `dockerd` ([docker/docker#40759](https://github.com/docker/docker/pull/40759)). - -Basic example usage: - -```console -$ docker run -d --name some-docker --privileged docker:dind-rootless -$ docker logs --tail=3 some-docker # to verify the daemon has finished generating TLS certificates and is listening successfully -time="xxx" level=info msg="Daemon has completed initialization" -time="xxx" level=info msg="API listen on /run/user/1000/docker.sock" -time="xxx" level=info msg="API listen on [::]:2376" -$ docker exec -it some-docker docker-entrypoint.sh sh # using "docker-entrypoint.sh" which auto-sets "DOCKER_HOST" appropriately -/ $ docker info --format '{{ json .SecurityOptions }}' -["name=seccomp,profile=default","name=rootless"] -``` - ## Where to Store Data Important note: There are several ways to store data used by applications that run in Docker containers. We encourage users of the `%%REPO%%` images to familiarize themselves with the options available, including: diff --git a/docker/variant-rootless.md b/docker/variant-rootless.md new file mode 100644 index 000000000000..8d8f20fb46b4 --- /dev/null +++ b/docker/variant-rootless.md @@ -0,0 +1,30 @@ +## `%%IMAGE%%:-rootless` + +For more information about using the experimental "rootless" image variants, see [docker-library/docker#174](https://github.com/docker-library/docker/pull/174). + +**Note:** just like the regular `dind` images, `--privileged` is required for Docker-in-Docker to function properly ([docker-library/docker#151](https://github.com/docker-library/docker/issues/151#issuecomment-483185972) & [docker-library/docker#281](https://github.com/docker-library/docker/issues/281#issuecomment-744766015)), which is a security issue that needs to be treated appropriately. + +Basic example usage: + +```console +$ docker run -d --name some-docker --privileged %%IMAGE%%:dind-rootless +$ docker logs --tail=3 some-docker # to verify the daemon has finished generating TLS certificates and is listening successfully +time="xxx" level=info msg="Daemon has completed initialization" +time="xxx" level=info msg="API listen on /run/user/1000/docker.sock" +time="xxx" level=info msg="API listen on [::]:2376" +$ docker exec -it some-docker docker-entrypoint.sh sh # using "docker-entrypoint.sh" which auto-sets "DOCKER_HOST" appropriately +/ $ docker info --format '{{ json .SecurityOptions }}' +["name=seccomp,profile=default","name=rootless"] +``` + +To run with a different UID/GID than the one baked into the image, modify `/etc/passwd`, `/etc/group`, and filesystem permissions (especially for the `rootless` user's home directory) as appropriate; for example: + +```dockerfile +FROM %%IMAGE%%:dind-rootless +USER root +RUN set -eux; \ + sed -i -e 's/^rootless:1000:1000:/rootless:1234:5678:/' /etc/passwd; \ + sed -i -e 's/^rootless:1000:/:5678:/' /etc/group; \ + chown -R rootless ~rootless +USER rootless +```