Merge pull request #12692 from giuseppe/fix-additional-ids-doc

[CI:DOCS] docs: document rootless userns mappings
containers · Dec 23, 2021 · a7f1c05 · a7f1c05
2 parents fbdfd55 + cb4f498
commit a7f1c05
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 0 deletions.
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
@@ -1142,10 +1142,20 @@ If for example _amount_ is **5** the second mapping step would look like:
 | _from_uid_ + 3       | _container_uid_ + 3 |
 | _from_uid_ + 4       | _container_uid_ + 4 |
 
+The current user ID is mapped to UID=0 in the rootless user namespace.
+Every additional range is added sequentially afterward:
+
+|   host                |rootless user namespace | length              |
+| -                     | -                      | -                   |
+| $UID                  | 0                      | 1                   |
+| 1                     | $FIRST_RANGE_ID        | $FIRST_RANGE_LENGTH |
+| 1+$FIRST_RANGE_LENGTH | $SECOND_RANGE_ID       | $SECOND_RANGE_LENGTH|
+
 Even if a user does not have any subordinate UIDs in  _/etc/subuid_,
 **--uidmap** could still be used to map the normal UID of the user to a
 container UID by running `podman create --uidmap $container_uid:0:1 --user $container_uid ...`.
 
+
 #### **--ulimit**=*option*
 
 Ulimit options

diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
@@ -1216,6 +1216,17 @@ If for example _amount_ is **5** the second mapping step would look like:
 | _from_uid_ + 3       | _container_uid_ + 3 |
 | _from_uid_ + 4       | _container_uid_ + 4 |
 
+When running as rootless, Podman will use all the ranges configured in the _/etc/subuid_ file.
+
+The current user ID is mapped to UID=0 in the rootless user namespace.
+Every additional range is added sequentially afterward:
+
+|   host                |rootless user namespace | length              |
+| -                     | -                      | -                   |
+| $UID                  | 0                      | 1                   |
+| 1                     | $FIRST_RANGE_ID        | $FIRST_RANGE_LENGTH |
+| 1+$FIRST_RANGE_LENGTH | $SECOND_RANGE_ID       | $SECOND_RANGE_LENGTH|
+
 Even if a user does not have any subordinate UIDs in  _/etc/subuid_,
 **--uidmap** could still be used to map the normal UID of the user to a
 container UID by running `podman run --uidmap $container_uid:0:1 --user $container_uid ...`.