From 4b91f5e3ece04803ddc99e5b741551c88cd8313d Mon Sep 17 00:00:00 2001 From: Louis-Arnaud Catoire Date: Tue, 21 Apr 2026 09:18:13 +0200 Subject: [PATCH 1/2] docs: clarify subuid/subgid mapping in rootless vs userns-remap --- .../manuals/engine/security/rootless/_index.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/content/manuals/engine/security/rootless/_index.md b/content/manuals/engine/security/rootless/_index.md index 45cc7875dd54..b2ca9579055f 100644 --- a/content/manuals/engine/security/rootless/_index.md +++ b/content/manuals/engine/security/rootless/_index.md @@ -20,6 +20,21 @@ with `userns-remap` mode, the daemon itself is running with root privileges, whereas in rootless mode, both the daemon and the container are running without root privileges. +The two modes also differ in how they map container UIDs and GIDs to the host: + +- In `userns-remap` mode, container UID `0` is mapped to the first subordinate + UID listed in `/etc/subuid` for the remap user, and container UID `n` is + mapped to `subuid + n`. +- In rootless mode, container UID `0` is mapped to the host UID of the user + running rootless Docker (the result of `id -u`); container UID `n` (for + `n >= 1`) is mapped to `subuid + (n - 1)`. + +GIDs follow the same rules using `/etc/subgid`. + +This difference matters when setting file permissions on bind-mounted +directories: in rootless mode, files owned by your host user appear as owned +by `root` inside the container. + Rootless mode does not use binaries with `SETUID` bits or file capabilities, except `newuidmap` and `newgidmap`, which are needed to allow multiple UIDs/GIDs to be used in the user namespace. From 2d4ef4656e939dc57a99490894fd2fac20d2d95f Mon Sep 17 00:00:00 2001 From: Louis-Arnaud Catoire Date: Tue, 21 Apr 2026 14:06:00 +0200 Subject: [PATCH 2/2] docs: move UID/GID mapping details to a subpage Addresses review feedback asking to keep _index.md concise. --- .../engine/security/rootless/_index.md | 34 +++++++------------ .../security/rootless/uid-gid-mapping.md | 22 ++++++++++++ 2 files changed, 34 insertions(+), 22 deletions(-) create mode 100644 content/manuals/engine/security/rootless/uid-gid-mapping.md diff --git a/content/manuals/engine/security/rootless/_index.md b/content/manuals/engine/security/rootless/_index.md index b2ca9579055f..1db60e4fc896 100644 --- a/content/manuals/engine/security/rootless/_index.md +++ b/content/manuals/engine/security/rootless/_index.md @@ -20,29 +20,16 @@ with `userns-remap` mode, the daemon itself is running with root privileges, whereas in rootless mode, both the daemon and the container are running without root privileges. -The two modes also differ in how they map container UIDs and GIDs to the host: - -- In `userns-remap` mode, container UID `0` is mapped to the first subordinate - UID listed in `/etc/subuid` for the remap user, and container UID `n` is - mapped to `subuid + n`. -- In rootless mode, container UID `0` is mapped to the host UID of the user - running rootless Docker (the result of `id -u`); container UID `n` (for - `n >= 1`) is mapped to `subuid + (n - 1)`. - -GIDs follow the same rules using `/etc/subgid`. - -This difference matters when setting file permissions on bind-mounted -directories: in rootless mode, files owned by your host user appear as owned -by `root` inside the container. +The two modes also differ in how they map container UIDs and GIDs to the +host: see [UID/GID mapping](uid-gid-mapping/) for details. Rootless mode does not use binaries with `SETUID` bits or file capabilities, except `newuidmap` and `newgidmap`, which are needed to allow multiple UIDs/GIDs to be used in the user namespace. - ## Prerequisites -- You must install `newuidmap` and `newgidmap` on the host. These commands +- You must install `newuidmap` and `newgidmap` on the host. These commands are provided by the `uidmap` package on most distributions. - `/etc/subuid` and `/etc/subgid` should contain at least 65,536 subordinate @@ -68,13 +55,15 @@ when the prerequisites are not satisfied. > [!NOTE] > > If the system-wide Docker daemon is already running, consider disabling it: ->```console ->$ sudo systemctl disable --now docker.service docker.socket ->$ sudo rm /var/run/docker.sock ->``` +> +> ```console +> $ sudo systemctl disable --now docker.service docker.socket +> $ sudo rm /var/run/docker.sock +> ``` +> > Should you choose not to shut down the `docker` service and socket, you will need to use the `--force` > parameter in the next section. There are no known issues, but until you shutdown and disable you're -> still running rootful Docker. +> still running rootful Docker. {{< tabs >}} {{< tab name="With packages (RPM/DEB)" >}} @@ -143,6 +132,7 @@ The binaries will be installed at `~/bin`. {{< /tabs >}} Run `docker info` to confirm that the `docker` client is connecting to the Rootless daemon: + ```console $ docker info Client: Docker Engine - Community @@ -159,4 +149,4 @@ Server: ... ``` -See [Troubleshooting](./troubleshoot.md) if you faced an error. \ No newline at end of file +See [Troubleshooting](./troubleshoot.md) if you faced an error. diff --git a/content/manuals/engine/security/rootless/uid-gid-mapping.md b/content/manuals/engine/security/rootless/uid-gid-mapping.md new file mode 100644 index 000000000000..8d90f7ad5216 --- /dev/null +++ b/content/manuals/engine/security/rootless/uid-gid-mapping.md @@ -0,0 +1,22 @@ +--- +description: How container UIDs and GIDs are mapped to the host in rootless mode +keywords: security, namespaces, rootless, uid, gid, subuid, subgid +title: UID/GID mapping +weight: 15 +--- + +Rootless mode and [`userns-remap` mode](../userns-remap.md) map container UIDs +and GIDs to the host differently. + +- In `userns-remap` mode, container UID `0` is mapped to the first subordinate + UID listed in `/etc/subuid` for the remap user, and container UID `n` is + mapped to `subuid + n`. +- In rootless mode, container UID `0` is mapped to the host UID of the user + running rootless Docker (the result of `id -u`); container UID `n` (for + `n >= 1`) is mapped to `subuid + (n - 1)`. + +GIDs follow the same rules using `/etc/subgid`. + +This difference matters when setting file permissions on bind-mounted +directories: in rootless mode, files owned by your host user appear as owned +by `root` inside the container.