Since we do not want the mapping to be applied to uids,
we should use the `g` flag in the mapping in the example
as well.
Follow up of #18173
Signed-off-by: Sergio Oller <sergioller@gmail.com>
Motivation
===========
This feature aims to make --uidmap and --gidmap easier to use, especially in rootless podman setups.
(I will focus here on the --gidmap option, although the same applies for --uidmap.)
In rootless podman, the user namespace mapping happens in two steps, through an intermediate mapping.
See https://docs.podman.io/en/latest/markdown/podman-run.1.html#uidmap-container-uid-from-uid-amount
for further detail, here is a summary:
First the user GID is mapped to 0 (root), and all subordinate GIDs (defined at /etc/subgid, and
usually >100000) are mapped starting at 1.
One way to customize the mapping is through the `--gidmap` option, that maps that intermediate mapping
to the final mapping that will be seen by the container.
As an example, let's say we have as main GID the group 1000, and we also belong to the additional GID 2000,
that we want to make accessible inside the container.
We first ask the sysadmin to subordinate the group to us, by adding "$user:2000:1" to /etc/subgid.
Then we need to use --gidmap to specify that we want to map GID 2000 into some GID inside the container.
And here is the first trouble:
Since the --gidmap option operates on the intermediate mapping, we first need to figure out where has
podman placed our GID 2000 in that intermediate mapping using:
podman unshare cat /proc/self/gid_map
Then, we may see that GID 2000 was mapped to intermediate GID 5. So our --gidmap option should include:
--gidmap 20000:5:1
This intermediate mapping may change in the future if further groups are subordinated to us (or we stop
having its subordination), so we are forced to verify the mapping with
`podman unshare cat /proc/self/gid_map` every time, and parse it if we want to script it.
**The first usability improvement** we agreed on #18333 is to be able to use:
--gidmap 20000:@2000:1
so podman does this lookup in the parent user namespace for us.
But this is only part of the problem. We must specify a **full** gidmap and not only what we want:
--gidmap 0:0:5 --gidmap 5:6:15000 --gidmap 20000:5:1
This is becoming complicated. We had to break the gidmap at 5, because the intermediate 5 had to
be mapped to another value (20000), and then we had to keep mapping all other subordinate ids... up to
close to the maximum number of subordinate ids that we have (or some reasonable value). This is hard
to explain to someone who does not understand how the mappings work internally.
To simplify this, **the second usability improvement** is to be able to use:
--gidmap "+20000:@2000:1"
where the plus flag (`+`) states that the given mapping should extend any previous/default mapping,
overriding any previous conflicting assignment.
Podman will set that mapping and fill the rest of mapped gids with all other subordinated gids, leading
to the same (or an equivalent) full gidmap that we were specifying before.
One final usability improvement related to this is the following:
By default, when podman gets a --gidmap argument but not a --uidmap argument, it copies the mapping.
This is convenient in many scenarios, since usually subordinated uids and gids are assigned in chunks
simultaneously, and the subordinated IDs in /etc/subuid and /etc/subgid for a given user match.
For scenarios with additional subordinated GIDs, this map copying is annoying, since it forces the user
to provide a --uidmap, to prevent the copy from being made. This means, that when the user wants:
--gidmap 0:0:5 --gidmap 5:6:15000 --gidmap 20000:5:1
The user has to include a uidmap as well:
--gidmap 0:0:5 --gidmap 5:6:15000 --gidmap 20000:5:1 --uidmap 0:0:65000
making everything even harder to understand without proper context.
For this reason, besides the "+" flag, we introduce the "u" and "g" flags. Those flags applied to a
mapping tell podman that the mapping should only apply to users or groups, and ignored otherwise.
Therefore we can use:
--gidmap "+g20000:@2000:1"
So the mapping only applies to groups and is ignored for uidmaps. If no "u" nor "g" flag is assigned
podman assumes the mapping applies to both users and groups as before, so we preserve backwards compatibility.
Co-authored-by: Tom Sweeney <tsweeney@redhat.com>
Signed-off-by: Sergio Oller <sergioller@gmail.com>
Specify that by default if only one of uidmap or gidmap is given, the other one is copied
Co-authored-by: Tom Sweeney <tsweeney@redhat.com>
Signed-off-by: Sergio Oller <sergioller@gmail.com>
The markdown-to-manpage sequence interprets
_from_uid_ and *from_uid* differently.
Use the latter syntax to get the expected result.
Fixes: https://github.com/containers/podman/issues/19171
Signed-off-by: Erik Sjölund <erik.sjolund@gmail.com>
The markdown-to-manpage sequence needs a long row of dashes,
not a single dash. A single dash, as used in this one option,
generates unreadable *roff.
Also, some tool somewhere doesn't like too-long columns. Shrtn thm.
Also, verify that there are no more three-or-fewer-dash columns:
$ ack '\|\s+-{1,3}\s' docs/source/markdown
Fixes: #19086
Signed-off-by: Ed Santiago <santiago@redhat.com>
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>
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>
