c9c2f644da
In each options/foo.md, keep a list of where the option is used. This will be valuable to anyone making future edits, and to those reviewing those edits. This may be a controversial commit, because those crossref lists are autogenerated as a side effect of the script that reads them. It definitely violates POLA. And one day, some kind person will reconcile (e.g.) --label, using it in more man pages, and maybe forget to git-commit the rewritten file, and CI will fail. I think this is a tough tradeoff, but worth doing. Without this, it's much too easy for someone to change an option file in a way that renders it inapplicable/misleading for some podman commands. Signed-off-by: Ed Santiago <santiago@redhat.com>
3.8 KiB
####> This option file is used in: ####> podman create, run ####> If you edit this file, make sure your changes ####> are applicable to all of those.
--uidmap=container_uid:from_uid:amount
Run the container in a new user namespace using the supplied UID mapping. This option conflicts with the --userns and --subuidname options. This option provides a way to map host UIDs to container UIDs. It can be passed several times to map different ranges.
The from_uid value is based upon the user running the command, either rootful or rootless users.
- rootful user: container_uid:host_uid:amount
- rootless user: container_uid:intermediate_uid:amount
When podman <> is called by a privileged user, the option --uidmap works as a direct mapping between host UIDs and container UIDs.
host UID -> container UID
The amount specifies the number of consecutive UIDs that will be mapped. If for example amount is 4 the mapping would look like:
| host UID | container UID |
|---|---|
| from_uid | container_uid |
| from_uid + 1 | container_uid + 1 |
| from_uid + 2 | container_uid + 2 |
| from_uid + 3 | container_uid + 3 |
When podman <> is called by an unprivileged user (i.e. running rootless), the value from_uid is interpreted as an "intermediate UID". In the rootless case, host UIDs are not mapped directly to container UIDs. Instead the mapping happens over two mapping steps:
host UID -> intermediate UID -> container UID
The --uidmap option only influences the second mapping step.
The first mapping step is derived by Podman from the contents of the file /etc/subuid and the UID of the user calling Podman.
First mapping step:
| host UID | intermediate UID |
|---|---|
| UID for the user starting Podman | 0 |
| 1st subordinate UID for the user starting Podman | 1 |
| 2nd subordinate UID for the user starting Podman | 2 |
| 3rd subordinate UID for the user starting Podman | 3 |
| nth subordinate UID for the user starting Podman | n |
To be able to use intermediate UIDs greater than zero, the user needs to have subordinate UIDs configured in /etc/subuid. See subuid(5).
The second mapping step is configured with --uidmap.
If for example amount is 5 the second mapping step would look like:
| intermediate UID | container UID |
|---|---|
| from_uid | container_uid |
| from_uid + 1 | container_uid + 1 |
| from_uid + 2 | container_uid + 2 |
| 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 <<subcommand>> --uidmap $container_uid:0:1 --user $container_uid ....
Note: the --uidmap flag cannot be called in conjunction with the --pod flag as a uidmap cannot be set on the container level when in a pod.