docs: clarify subuid/subgid mapping in rootless vs userns-remap

Author: lacatoire

content/manuals/engine/security/rootless/_index.md

@@ -20,6 +20,9 @@ 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: 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.

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.