Merge pull request containers#18713 from zeehio/feat-gidmap-improvements

Mapping improvements to add additional groups

docs/source/markdown/options/gidmap.container.md

@@ -2,11 +2,11 @@
 ####>   podman create, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
-#### **--gidmap**=*container_gid:host_gid:amount*
+#### **--gidmap**=*[flags]container_uid:from_uid[:amount]*
 
 Run the container in a new user namespace using the supplied GID mapping. This
 option conflicts with the **--userns** and **--subgidname** options. This
 option provides a way to map host GIDs to container GIDs in the same way as
 __--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__.
 
-Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod.
+Note: the **--gidmap** option cannot be called in conjunction with the **--pod** option as a gidmap cannot be set on the container level when in a pod.

docs/source/markdown/options/uidmap.container.md

@@ -2,16 +2,23 @@
 ####>   podman create, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
-#### **--uidmap**=*container_uid:from_uid:amount*
+#### **--uidmap**=*[flags]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 possible values of the optional *flags* are discussed further down on this page.
+The *amount* value is optional and assumed to be **1** if not given.
+
 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*
+
+* rootful user:  [*flags*]*container_uid*:*host_uid*[:*amount*]
+* rootless user: [*flags*]*container_uid*:*intermediate_uid*[:*amount*]
+
+  `Rootful mappings`
+
 
 When **podman <<subcommand>>** is called by a privileged user, the option **--uidmap**
 works as a direct mapping between host UIDs and container UIDs.
@@ -28,6 +35,8 @@ If for example _amount_ is **4** the mapping looks like:
 | *from_uid* + 2 | *container_uid* + 2 |
 | *from_uid* + 3 | *container_uid* + 3 |
 
+  `Rootless mappings`
+
 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
@@ -76,8 +85,112 @@ Every additional range is added sequentially afterward:
 | 1                     | $FIRST_RANGE_ID         | $FIRST_RANGE_LENGTH |
 | 1+$FIRST_RANGE_LENGTH | $SECOND_RANGE_ID        | $SECOND_RANGE_LENGTH|
 
+  `Referencing a host ID from the parent namespace`
+
+As a rootless user, the given host ID in **--uidmap** or **--gidmap**
+is mapped from the *intermediate namespace* generated by Podman. Sometimes
+it is desirable to refer directly at the *host namespace*. It is possible
+to manually do so, by running `podman unshare cat /proc/self/gid_map`,
+finding the desired host id at the second column of the output, and getting
+the corresponding intermediate id from the first column.
+
+Podman can perform all that by preceding the host id in the mapping
+with the `@` symbol. For instance, by specifying `--gidmap 100000:@2000:1`,
+podman will look up the intermediate id corresponding to host id `2000` and
+it will map the found intermediate id to the container id `100000`. The
+given host id must have been subordinated (otherwise it would not be mapped
+into the intermediate space in the first place).
+
+If the length is greater than one, for instance with `--gidmap 100000:@2000:2`,
+Podman will map host ids `2000` and `2001` to `100000` and `100001`, respectively,
+regardless of how the intermediate mapping is defined.
+
+  `Extending previous mappings`
+
+Some mapping modifications may be cumbersome. For instance, a user
+starts with a mapping such as `--gidmap="0:0:65000"`, that needs to be
+changed such as the parent id `1000` is mapped to container id `100000`
+instead, leaving container id `1` unassigned. The corresponding `--gidmap`
+becomes `--gidmap="0:0:1" --gidmap="2:2:65534" --gidmap="100000:1:1"`.
+
+This notation can be simplified using the `+` flag, that takes care of
+breaking previous mappings removing any conflicting assignment with
+the given mapping. The flag is given before the container id
+as follows: `--gidmap="0:0:65000" --gidmap="+100000:1:1"`
+
+
+ Flag      | Example       | Description
+-----------|---------------|-------------
+ `+`       | `+100000:1:1` | Extend the previous mapping
+
+This notation leads to gaps in the assignment, so it may be convenient to
+fill those gaps afterwards: `--gidmap="0:0:65000" --gidmap="+100000:1:1" --gidmap="1:65001:1"`
+
+One specific use case for this flag is in the context of rootless
+users. A rootless user may specify mappings with the `+` flag as
+in `--gidmap="+100000:1:1"`. Podman will then "fill the gaps" starting
+from zero with all the remaining intermediate ids. This is convenient when
+a user wants to map a specific intermediate id to a container id, leaving
+the rest of subordinate ids to be mapped by Podman at will.
+
+  `Passing only one of --uidmap or --gidmap`
+
+Usually, subordinated user and group ids are assigned simultaneously, and
+for any user the subordinated user ids match the subordinated group ids.
+For convenience, if only one of **--uidmap** or **--gidmap** is given,
+podman assumes the mapping refers to both UIDs and GIDs and applies the
+given mapping to both. If only one value of the two needs to be changed,
+the mappings should include the `u` or the `g` flags to specify that
+they only apply to UIDs or GIDs and should not be copied over.
+
+ flag    | Example         | Description
+---------|-----------------|-----------------
+  `u`    | `u20000:2000:1` |The mapping only applies to UIDs
+  `g`    | `g10000:1000:1` |The mapping only applies to GIDs
+
+For instance given the command
+
+    podman <<subcommand>> --gidmap "0:0:1000" --gidmap "g2000:2000:1"
+
+Since no **--uidmap** is given, the **--gidmap** is copied to **--uidmap**,
+giving a command equivalent to
+
+    podman <<subcommand>> --gidmap "0:0:1000" --gidmap "2000:2000:1" --uidmap "0:0:1000"
+
+The `--gidmap "g2000:2000:1"` used the `g` flag and therefore it was
+not copied to **--uidmap**.
+
+  `Rootless mapping of additional host GIDs`
+
+A rootless user may desire to map a specific host group that has already been
+subordinated within _/etc/subgid_ without specifying the rest of the mapping.
+
+This can be done with **--gidmap "+g*container_gid*:@*host_gid*"**
+
+Where:
+
+- The host GID is given through the `@` symbol
+- The mapping of this GID is not copied over to **--usermap** thanks to the `g` flag.
+- The rest of the container IDs will be mapped starting from 0 to n,
+  with all the remaining subordinated GIDs, thanks to the `+` flag.
+
+For instance, if a user belongs to the group `2000` and that group is
+subordinated to that user (with `usermod --add-subgids 2000-2000 $USER`),
+the user can map the group into the container with: **--gidmap=+g100000:@2000**.
+
+If this mapping is combined with the option, **--group-add=keep-groups**, the
+process in the container will belong to group `100000`, and files belonging
+to group `2000` in the host will appear as being owned by group `100000`
+inside the container.
+
+    podman run --group-add=keep-groups --gidmap="+100000:@2000" ...
+
+  `No subordinate UIDs`
+
 Even if a user does not have any subordinate UIDs in  _/etc/subuid_,
 **--uidmap** can 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.
+  `Pods`
+
+The **--uidmap** option cannot be called in conjunction with the **--pod** option as a uidmap cannot be set on the container level when in a pod.

docs/tutorials/rootless_tutorial.md

@@ -87,6 +87,34 @@ grep johndoe /etc/subuid /etc/subgid
 /etc/subgid:johndoe:100000:65536
 ```
 
+#### Giving access to additional groups
+
+Users can fully map additional groups to a container namespace if
+those groups subordinated to the user:
+
+```
+usermod --add-subgids 2000-2000 johndoe
+grep johndoe /etc/subgid
+```
+
+This means the user `johndoe` can "impersonate" the group `2000` inside the
+container. Note that it is usually not a good idea to subordinate active
+user ids to other users, because it would allow user impersonation.
+
+`johndoe` can use `--group-add keep-groups` to preserve the additional
+groups, and `--gidmap="+g102000:@2000"` to map the group `2000` in the host
+to the group `102000` in the container:
+
+```
+podman run \
+  --rm \
+  --group-add keep-groups \
+  --gidmap="+g102000:@2000" \
+  --volume "$PWD:/data:ro" \
+  --workdir /data \
+  alpine ls -lisa
+```
+
 ### Enable unprivileged `ping`
 
 Users running in a non-privileged container may not be able to use the `ping` utility from that container.

pkg/domain/infra/runtime_libpod.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io/fs"
 	"os"
 	"os/signal"
 	"sync"
@@ -17,6 +18,7 @@ import (
 	"github.com/containers/podman/v4/pkg/domain/entities"
 	"github.com/containers/podman/v4/pkg/namespaces"
 	"github.com/containers/podman/v4/pkg/rootless"
+	"github.com/containers/podman/v4/pkg/util"
 	"github.com/containers/storage/pkg/idtools"
 	"github.com/containers/storage/types"
 	"github.com/sirupsen/logrus"
@@ -333,11 +335,22 @@ func ParseIDMapping(mode namespaces.UsernsMode, uidMapSlice, gidMapSlice []strin
 		options.UIDMap = mappings.UIDs()
 		options.GIDMap = mappings.GIDs()
 	}
-	parsedUIDMap, err := idtools.ParseIDMap(uidMapSlice, "UID")
+
+	parentUIDMap, parentGIDMap, err := rootless.GetAvailableIDMaps()
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
+			// The kernel-provided files only exist if user namespaces are supported
+			logrus.Debugf("User or group ID mappings not available: %s", err)
+		} else {
+			return nil, err
+		}
+	}
+
+	parsedUIDMap, err := util.ParseIDMap(uidMapSlice, "UID", parentUIDMap)
 	if err != nil {
 		return nil, err
 	}
-	parsedGIDMap, err := idtools.ParseIDMap(gidMapSlice, "GID")
+	parsedGIDMap, err := util.ParseIDMap(gidMapSlice, "GID", parentGIDMap)
 	if err != nil {
 		return nil, err
 	}