[Container - Podman] Basic Setup and Use of Podman in a Rootless environment

Podman Rootless

Prior to allowing users without root privileges to run Podman, the administrator must install or build Podman and complete the following configurations.

Enable user namespaces (on RHEL7 machines)

The number of user namespaces that are allowed on the system is specified in the file /proc/sys/user/max_user_namespaces. On most Linux platforms this is preset by default and no adjustment is necessary. However, on RHEL7 machines, a user with root privileges may need to set that to a reasonable value by using this command: sysctl user.max_user_namespaces=15000.

1
2
3
$ echo "user.max_user_namespaces=15000" > /etc/sysctl.d/userns.conf

$ sysctl -p /etc/sysctl.d/userns.conf

/etc/subuid and /etc/subgid configuration

Rootless Podman requires the user running it to have a range of UIDs listed in the files /etc/subuid and /etc/subgid. The shadow-utils or newuid package provides these files on different distributions and they must be installed on the system. Root privileges are required to add or update entries within these files. The following is a summary from the How does rootless Podman work? - https://opensource.com/article/19/2/how-does-rootless-podman-work article by Dan Walsh on opensource.com

For each user that will be allowed to create containers, update /etc/subuid and /etc/subgid for the user with fields that look like the following. Note that the values for each user must be unique. If there is overlap, there is a potential for a user to use another user’s namespace and they could corrupt it.

1
2
3
$ cat /etc/subuid
cloudolife:100000:65536
test:165536:65536

The format of this file is USERNAME:UID:RANGE

username as listed in /etc/passwd or in the output of getpwent - https://man7.org/linux/man-pages/man3/getpwent.3.html.

  • The initial UID allocated for the user.

  • The size of the range of UIDs allocated for the user.

This means the user johndoe is allocated UIDs 100000-165535 as well as their standard UID in the /etc/passwd file.


NOTE: this is not currently supported with network installs; these files must be available locally to the host machine. It is not possible to configure this with LDAP or Active Directory.


If you update either /etc/subuid or /etc/subgid, you need to stop all the running containers owned by the user and kill the pause process that is running on the system for that user. This can be done automatically by using the podman system migrate command which will stop all the containers for the user and will kill the pause process.

Rather than updating the files directly, the usermod program can be used to assign UIDs and GIDs to a user.

1
2
3
4
5
$ usermod --add-subuids 200000-201000 --add-subgids 200000-201000 cloudolife

$ grep johndoe /etc/subuid /etc/subgid
/etc/subuid:cloudolife:200000:1001
/etc/subgid:cloudolife:200000:1001

FAQs

usermod: unrecognized option ‘–add-subuids’ on CentOS

1
$ usermod --add-subuids 200000-201000 --add-subgids 200000-201000 cloudolife

Create or modify /etc/subuid and /etc/subugid manulally.

1
2
3
$ echo "cloudolife:200000:1001" > /etc/subuid

$ cp /etc/subuid /etc/subgid

user namespaces are not enabled in /proc/sys/user/max_user_namespaces on CentOS7, RHEL7

1
2
3
$ podman
cannot clone: Invalid argument
user namespaces are not enabled in /proc/sys/user/max_user_namespaces

Remember to specify user.max_user_namespaces to 15000.

1
2
3
$ echo "user.max_user_namespaces=15000" > /etc/sysctl.d/userns.conf

$ sysctl -p /etc/sysctl.d/userns.conf

No subuid ranges found for user “cloudolife” in /etc/subuid

1
2
$ podman
ERRO[0000] cannot find mappings for user cloudolife: No subuid ranges found for user "cloudolife" in /etc/subuid

Remember to create or modify /etc/subuid and /etc/subgid according to the above.

there might not be enough IDs available in the namespace

1
there might not be enough IDs available in the namespace

First, find the max id.

1
2
3
$ cat /etc/passwd|awk -F ':' '{print $3,$4}'|sort

$ cat /etc/group|awk -F ':' '{print $3}'|sort

Assume 410000000 is great than max ix.

1
2
3
4
5
6
7
8
9
$ echo javadm:410000000:500000000 >> /etc/subuid

$ echo javadm:410000000:500000000 >> /etc/subgid

$ podman system migrate

$ podman info | grep host_id

$ podman unshare cat /proc/self/uid_map

References

[1] podman/rootless_tutorial.md at main · containers/podman - https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md

[2] Rootless containers with Podman: The basics | Red Hat Developer - https://developers.redhat.com/blog/2020/09/25/rootless-containers-with-podman-the-basics#example__using_rootless_containers

[3] How does rootless Podman work? | Opensource.com - https://opensource.com/article/19/2/how-does-rootless-podman-work

[4] Podman - https://podman.io/