erabo/spiegel_podman
1
0
Fork 0
mirror of https://github.com/podman-container-tools/podman.git synced 2026-08-22 00:08:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
spiegel_podman/docs/source/markdown/options/group-add.md
Satwik Sai Prakash Sahoo 02f0ee0de0
docs: document keep-groups limitation with systemd services 
When --group-add keep-groups (or GroupAdd=keep-groups in Quadlet) is
used, supplementary groups are inherited from the calling process. When
Podman is launched via a systemd user service, the calling process is
the systemd --user manager, which only has the groups assigned to the
user at the time the manager was started.

If the user was added to new groups after the systemd user session
started (e.g. via usermod), those groups will not be visible to the
container. This is expected Linux process credential behavior, but was
undocumented, causing confusion for Quadlet users.

Add notes to both option and Quadlet docs explaining this behavior and
the workaround (restarting the user's systemd manager).

Fixes: #27876
Signed-off-by: Satwik Sai Prakash Sahoo <sahoospsatwik@gmail.com>
2026-08-04 01:35:18 +05:30

1.6 KiB
Raw Blame History

####> This option file is used in: ####> podman build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, run ####> If file is edited, make sure the changes ####> are applicable to all of those. << if is_quadlet >>

GroupAdd=group | keep-groups

<< else >>

--group-add=group | keep-groups

<< endif >>

Assign additional groups to the 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, other groups cannot be specified with this flag. (Not available for remote commands, including Mac and Windows (excluding WSL2) machines)

Note: keep-groups passes the supplementary groups that the calling process already has into the container, it does not look the user's groups up at container start. When Podman is started from a systemd user service, for example a rootless Quadlet, the calling process is the systemd --user manager, which only holds the groups the user had when that manager was started. Groups the user is added to afterwards, for example with usermod, are therefore not passed into the container. Restart the user's systemd manager to pick them up, for example with loginctl terminate-user <user> followed by a new login, or by rebooting.