Merge pull request containers#9495 from rhatdan/groups

Add '--group-add keep-groups': supplementary groups into container

Makefile

@@ -149,7 +149,7 @@ err_if_empty = $(if $(strip $($(1))),$(strip $($(1))),$(error Required variable
 
 # Podman does not work w/o CGO_ENABLED, except in some very specific cases
 CGO_ENABLED ?= 1
-# Default to the native OS type and archetecture unless otherwise specified
+# Default to the native OS type and architecture unless otherwise specified
 GOOS ?= $(shell $(GO) env GOOS)
 ifeq ($(call err_if_empty,GOOS),windows)
 BINSFX := .exe
@@ -255,7 +255,7 @@ test/goecho/goecho: .gopathok $(wildcard test/goecho/*.go)
 
 .PHONY: codespell
 codespell:
-	codespell -S bin,vendor,.git,go.sum,changelog.txt,.cirrus.yml,"RELEASE_NOTES.md,*.xz,*.gz,*.tar,*.tgz,bin2img,*ico,*.png,*.1,*.5,copyimg,*.orig,apidoc.go" -L uint,iff,od,seeked,splitted,marge,ERRO,hist -w
+	codespell -S bin,vendor,.git,go.sum,changelog.txt,.cirrus.yml,"RELEASE_NOTES.md,*.xz,*.gz,*.tar,*.tgz,bin2img,*ico,*.png,*.1,*.5,copyimg,*.orig,apidoc.go" -L uint,iff,od,seeked,splitted,marge,ERRO,hist,ether -w
 
 .PHONY: validate
 validate: gofmt lint .gitvalidation validate.completions man-page-check swagger-check tests-included

RELEASE_PROCESS.md

@@ -196,7 +196,7 @@ spelled with complete minutiae.
    1. Merge the PR (or ask someone else to review and merge, to be safer).
    1. **Note:** This is the last point where any test-failures can be addressed
       by code changes. After pushing the new version-tag upstream, no further
-      changes can be made to the code without lots of unpleasent efforts.  Please
+      changes can be made to the code without lots of unpleasant efforts.  Please
       seek assistance if needed, before proceeding.
 
    1. Assuming the "Bump to ..." PR merged successfully, and you're **really**

cmd/podman/common/create.go

@@ -277,7 +277,7 @@ func DefineCreateFlags(cmd *cobra.Command, cf *ContainerCLIOpts) {
 	createFlags.StringSliceVar(
 		&cf.GroupAdd,
 		groupAddFlagName, []string{},
-		"Add additional groups to join",
+		"Add additional groups to the primary container process. 'keep-groups' allows container processes to use suplementary groups.",
 	)
 	_ = cmd.RegisterFlagCompletionFunc(groupAddFlagName, completion.AutocompleteNone)
 

cmd/podman/containers/create.go

@@ -193,6 +193,25 @@ func createInit(c *cobra.Command) error {
 		val := c.Flag("entrypoint").Value.String()
 		cliVals.Entrypoint = &val
 	}
+
+	if c.Flags().Changed("group-add") {
+		groups := []string{}
+		for _, g := range cliVals.GroupAdd {
+			if g == "keep-groups" {
+				if len(cliVals.GroupAdd) > 1 {
+					return errors.New("the '--group-add keep-groups' option is not allowed with any other --group-add options")
+				}
+				if registry.IsRemote() {
+					return errors.New("the '--group-add keep-groups' option is not supported in remote mode")
+				}
+				cliVals.Annotation = append(cliVals.Annotation, "run.oci.keep_original_groups=1")
+			} else {
+				groups = append(groups, g)
+			}
+		}
+		cliVals.GroupAdd = groups
+	}
+
 	if c.Flags().Changed("pids-limit") {
 		val := c.Flag("pids-limit").Value.String()
 		pidsLimit, err := strconv.ParseInt(val, 10, 32)

cmd/podman/machine/stop.go

@@ -30,7 +30,7 @@ func init() {
 	})
 }
 
-// TODO  Name shouldnt be required, need to create a default vm
+// TODO  Name shouldn't be required, need to create a default vm
 func stop(cmd *cobra.Command, args []string) error {
 	var (
 		err    error

completions/powershell/podman-remote.ps1

@@ -161,7 +161,7 @@ Register-ArgumentCompleter -CommandName 'podman-remote' -ScriptBlock {
 
     $Values | ForEach-Object {
 
-        # store temporay because switch will overwrite $_
+        # store temporary because switch will overwrite $_
         $comp = $_
 
         # PowerShell supports three different completion modes
@@ -216,7 +216,7 @@ Register-ArgumentCompleter -CommandName 'podman-remote' -ScriptBlock {
             Default {
                 # Like MenuComplete but we don't want to add a space here because
                 # the user need to press space anyway to get the completion.
-                # Description will not be shown because thats not possible with TabCompleteNext
+                # Description will not be shown because that's not possible with TabCompleteNext
                 [System.Management.Automation.CompletionResult]::new($($comp.Name | __podman-remote_escapeStringWithSpecialChars), "$($comp.Name)", 'ParameterValue', "$($comp.Description)")
             }
         }

completions/powershell/podman.ps1

@@ -161,7 +161,7 @@ Register-ArgumentCompleter -CommandName 'podman' -ScriptBlock {
 
     $Values | ForEach-Object {
 
-        # store temporay because switch will overwrite $_
+        # store temporary because switch will overwrite $_
         $comp = $_
 
         # PowerShell supports three different completion modes
@@ -216,7 +216,7 @@ Register-ArgumentCompleter -CommandName 'podman' -ScriptBlock {
             Default {
                 # Like MenuComplete but we don't want to add a space here because
                 # the user need to press space anyway to get the completion.
-                # Description will not be shown because thats not possible with TabCompleteNext
+                # Description will not be shown because that's not possible with TabCompleteNext
                 [System.Management.Automation.CompletionResult]::new($($comp.Name | __podman_escapeStringWithSpecialChars), "$($comp.Name)", 'ParameterValue', "$($comp.Description)")
             }
         }

contrib/cirrus/runner.sh

@@ -277,7 +277,7 @@ logformatter() {
             |& awk --file "${CIRRUS_WORKING_DIR}/${SCRIPT_BASE}/timestamp.awk" \
             |& "${CIRRUS_WORKING_DIR}/${SCRIPT_BASE}/logformatter" "$output_name"
     else
-        # Assume script is run by a human, they want output immediatly
+        # Assume script is run by a human, they want output immediately
         cat -
     fi
 }

docs/remote-docs.sh

@@ -6,7 +6,7 @@ PLATFORM=$1                         ## linux, windows or darwin
 TARGET=${2}                         ## where to output files
 SOURCES=${@:3}                      ## directories to find markdown files
 
-# Overriden for testing.  Native podman-remote binary expected filepaths
+# Overridden for testing.  Native podman-remote binary expected filepaths
 if [[ -z "$PODMAN" ]]; then
     case $(env -i HOME=$HOME PATH=$PATH go env GOOS) in
         windows)

docs/source/markdown/podman-build.1.md

@@ -688,7 +688,7 @@ Set the architecture variant of the image to be pulled.
    bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman
    container. (This option is not available with the remote Podman client)
 
-   The `OPTIONS` are a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup>
+   The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup>
 
    * [rw|ro]
    * [z|Z|O]

docs/source/markdown/podman-create.1.md

@@ -261,8 +261,8 @@ Note: if _host_device_ is a symbolic link then it will be resolved first.
 The container will only store the major and minor numbers of the host device.
 
 Note: if the user only has access rights via a group, accessing the device
-from inside a rootless container will fail. The **crun**(1) runtime offers a
-workaround for this by adding the option **\-\-annotation run.oci.keep_original_groups=1**.
+from inside a rootless container will fail. Use the `--group-add keep-groups`
+flag to pass the user's supplementary group access into the container.
 
 Podman may load kernel modules required for using the specified
 device. The devices that podman will load modules when necessary are:
@@ -361,9 +361,17 @@ GID map for the user namespace. Using this flag will run the container with user
 
 The following example maps uids 0-2000 in the container to the uids 30000-31999 on the host and gids 0-2000 in the container to the gids 30000-31999 on the host. `--gidmap=0:30000:2000`
 
-#### **\-\-group-add**=*group*
+#### **\-\-group-add**=*group|keep-groups*
 
-Add additional groups to run as
+Add additional groups to assign to primary user running within the container process.
+
+- `keep-groups` is a special flag that tells Podman to keep the supplementary group access.
+
+Allows container to use the user's supplementary group access. If file systems or
+devices are only accessible by the rootless user's group, this flag tells the OCI
+runtime to pass the group access into the container. Currently only available
+with the `crun` OCI runtime. Note: `keep-groups` is exclusive, you cannot add any other groups
+with this flag. (Not available for remote commands)
 
 #### **\-\-health-cmd**=*"command"* | *'["command", "arg1", ...]'*
 
@@ -634,7 +642,7 @@ Valid _mode_ values are:
 - **none**: no networking;
 - **container:**_id_: reuse another container's network stack;
 - **host**: use the Podman host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure;
-- _network-id_: connect to a user-defined network, multiple networks should be comma separated;
+- _network-id_: connect to a user-defined network, multiple networks should be comma-separated;
 - **ns:**_path_: path to a network namespace to join;
 - **private**: create a new namespace for the container (default)
 - **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options:
@@ -861,6 +869,8 @@ Security Options
 - `label=filetype:TYPE` : Set the label file type for the container files
 - `label=disable`       : Turn off label separation for the container
 
+Note: Labeling can be disabled for all containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf` or `$HOME/.config/containers/containers.conf`) file.
+
 - `mask=/path/1:/path/2` : The paths to mask separated by a colon. A masked path
   cannot be accessed inside the container.
 
@@ -869,13 +879,13 @@ Security Options
 - `seccomp=unconfined` : Turn off seccomp confinement for the container
 - `seccomp=profile.json` :  White listed syscalls seccomp Json file to be used as a seccomp filter
 
+- `proc-opts=OPTIONS` : Comma-separated list of options to use for the /proc mount. More details for the
+  possible mount options are specified in the **proc(5)** man page.
+
 - `unmask=ALL or /path/1:/path/2` : Paths to unmask separated by a colon. If set to **ALL**, it will
   unmask all the paths that are masked or made read only by default.
   The default masked paths are **/proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux.**  The default paths that are read only are **/proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup**.
 
-- `proc-opts=OPTIONS` : Comma separated list of options to use for the /proc mount. More details for the
-  possible mount options are specified at **proc(5)** man page.
-
 Note: Labeling can be disabled for all containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf` or `$HOME/.config/containers/containers.conf`) file.
 
 #### **\-\-shm-size**=*size*
@@ -1093,9 +1103,9 @@ Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman
 bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman
 container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume
 in the host to the container. If no such named volume exists, Podman will
-create one. The `OPTIONS` are a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup>  (Note when using the remote client, the volumes will be mounted from the remote server, not necessarly the client machine.)
+create one. The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup>  (Note when using the remote client, the volumes will be mounted from the remote server, not necessarly the client machine.)
 
-The _options_ is a comma delimited list and can be:
+The _options_ is a comma-separated list and can be:
 
 * **rw**|**ro**
 * **z**|**Z**
@@ -1185,7 +1195,7 @@ host into the container to allow speeding up builds.
 Content mounted into the container is labeled with the private label.
        On SELinux systems, labels in the source directory must be readable
 by the container label. Usually containers can read/execute `container_share_t`
-and can read/write `container_file_t`. If you can not change the labels on a
+and can read/write `container_file_t`. If you cannot change the labels on a
 source volume, SELinux container separation must be disabled for the container
 to work.
      - The source directory mounted into the container with an overlay mount
@@ -1245,10 +1255,14 @@ will convert /foo into a `shared` mount point. Alternatively one can directly
 change propagation properties of source mount. Say `/` is source mount for
 `/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount.
 
+Note: if the user only has access rights via a group, accessing the volume
+from inside a rootless container will fail. Use the `--group-add keep-groups`
+flag to pass the user's supplementary group access into the container.
+
 #### **\-\-volumes-from**[=*CONTAINER*[:*OPTIONS*]]
 
 Mount volumes from the specified container(s). Used to share volumes between
-containers. The *options* is a comma delimited list with the following available elements:
+containers. The *options* is a comma-separated list with the following available elements:
 
 * **rw**|**ro**
 * **z**
@@ -1351,6 +1365,11 @@ $ podman create --name container1 -t -i fedora bash
 $ podman create --name container2 -t -i fedora bash
 $ podman create --name container3 --requires container1,container2 -t -i fedora bash
 $ podman start --attach container3
+
+### Configure keep supplemental groups for access to volume
+
+```
+$ podman create -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
 ```
 
 ### Rootless Containers

docs/source/markdown/podman-pod-create.1.md

@@ -125,7 +125,7 @@ If another pod with the same name already exists, replace and remove it.  The de
 
 #### **\-\-share**=*namespace*
 
-A comma delimited list of kernel namespaces to share. If none or "" is specified, no namespaces will be shared. The namespaces to choose from are ipc, net, pid, uts.
+A comma-separated list of kernel namespaces to share. If none or "" is specified, no namespaces will be shared. The namespaces to choose from are ipc, net, pid, uts.
 
 The operator can identify a pod in three ways:
 UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)