Podman Rootless Tips: Using `--Group-Add Keep-Groups` to Solve Volume Group Permission Issues

AI generated + manually edited

For developers using Podman Rootless mode, accessing directories managed by group permissions on the host from within containers is a tricky problem. This article introduces a practical technique to elegantly solve this permission issue by using the --group-add keep-groups parameter when starting containers.

Scenario Setup

Example scenario:

• Running Environment: You are running Podman Rootless containers as a non-root user (e.g., nite, UID 1000).
• Host User Groups: Your user nite belongs to the git group.
• Shared Directory: There is a directory named repos on the host with permissions set to allow read-write access for members of the git group.
• Container Requirements: You want to smoothly access and operate the repos directory within the Podman container.

When you try to mount the repos directory as a volume into the container, you often encounter permission issues. A typical phenomenon is that when viewing the ownership of this directory inside the container, it shows as nobody:nobody and you get a Permission denied error when trying to access it.

User Namespaces in Rootless Containers

To understand the root cause of this problem, we need to understand the core mechanism of Podman Rootless mode: User Namespaces.

In Rootless mode, Podman creates a user namespace that maps the ordinary user running the container on the host (e.g., nite, UID 1000) to the root user (UID 0) inside the container. Similarly, user group GIDs on the host are also mapped. This mapping mechanism is the cornerstone of Rootless container security, ensuring that even if a user has root privileges inside the container, they remain just an ordinary user on the host.

However, problems arise when dealing with directories on the host that grant permissions through supplementary groups. By default, when starting a container, processes inside the container do not inherit the supplementary group relationships of the host user. This is why even though the nite user on the host can access the repos directory because they belong to the git group, processes inside the container cannot access it.

Solution: --group-add keep-groups

To solve this problem, Podman provides a powerful parameter: --group-add keep-groups.

This parameter works by making processes inside the container keep (keep) the supplementary groups of their parent process (i.e., the user running the podman run command on the host) when starting the container.

Specifically, when using this parameter, Podman instructs the underlying OCI runtime (such as crun) not to call the setgroups system call when creating container processes. setgroups typically resets the process’s group information to the groups defined inside the container, thereby discarding groups inherited from the parent process. By skipping this step, processes inside the container “inherit” the group relationships of the host user.

Therefore, your startup command would look like this:

podman run -it --rm \
  -v /path/to/your/repos:/repos \
  --group-add keep-groups \
  your-image:tag

The “Mysterious” nobody:nobody

An interesting and potentially confusing phenomenon is that even after using the --group-add keep-groups parameter, when you execute ls -l inside the container to view the mounted repos directory, its owner and group may still display as nobody:nobody.

This is because the GID of the repos directory on the host (the GID of the git group) is not mapped to the user namespace inside the container. Therefore, the container cannot resolve this GID to a known group name and can only display it as nobody or an overflow GID.

However, this does not affect actual access permissions. Since processes inside the container have already inherited the host git group membership through keep-groups, the kernel will correctly determine that the process has permission to access this directory.