mirror of
https://github.com/containers/podman.git
synced 2025-05-24 10:37:58 +08:00
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>
80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
#### **--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 <<subcommand>>** 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 <<subcommand>>** 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.
|