d7f134d687
Followup to #15174. These are the options that are easy(ish) to review: those that have only drifted slightly, and need only minor tweaks to bring back to sanity. For the most part, I went with the text in podman-run because that was cleaned up in #5192 way back in 2020. These diffs primarily consist of using '**' (star star) instead of backticks, plus other formatting and punctuation changes. This PR also adds a README in the options dir, and a new convention: <<container text...|pod text...>> which tries to do the right thing based on whether the man page name includes "-pod-" or not. Since that's kind of hairy code, I've also added a test suite for it. Finally, since this is impossible to review by normal means, I'm temporarily committing hack/markdown-preprocess-review, a script that will diff option-by-option. I will remove it once we finish this cleanup, but be advised that there are still 130+ options left to examine, and some of those are going to be really hard to reunite. Review script usage: simply run it (you need to have 'diffuse' installed). It isn't exactly obvious, but it shouldn't take more than a minute to figure out. The rightmost column (zzz-chosen.md) is the "winner", the actual content that will be used henceforth. You really want an ultrawide screen here. Signed-off-by: Ed Santiago <santiago@redhat.com>
3.6 KiB
--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.