Running Podman in Rootless Mode

On Linux, unprivileged users cannot open ports below port number 1024. This limitation also applies to Podman, so by default, rootless containers cannot expose ports below port number 1024. You can remove this limitation temporarily using the following command:

sysctl net.ipv4.ip_unprivileged_port_start=0

To remove the limitation permanently, run sysctl -w net.ipv4.ip_unprivileged_port_start=0.

Note that this allows all unprivileged applications to bind to ports below 1024.

When using rootless containers with Podman, it is recommended to use cgroups v2. cgroups v1 have limited functionality compared to v2. For example, cgroups v1 do not allow proper hierarchical delegation to the user's subtrees. Additionally, Podman is unable to read container logs properly with cgroups v1 and the systemd log driver.

To find out which cgroups version is default on your system, use the following command:

> mount|grep ^cgroup|awk '{print $1}'|uniq
cgroup2
cgroup

The first entry in the output indicates the default cgroups version.

If you are using a version of SUSE Linux Enterprise Server with cgroups v1, you can enable cgroups v2 by adding the following to the kernel cmdline: systemd.unified_cgroup_hierarchy=1. Then update GRUB using the grub2-mkconfig -o /boot/grub2/grub.cfg command.

Even on setups of SUSE Linux Enterprise Server with cgroup v2, the default configuration delegates no controllers to user sessions (for performance reasons) and chosen controllers should be enabled explicitly, https://documentation.suse.com/sles/single-html/SLES-tuning/#sec-cgroups-user-sessions.

Running a container with Podman in rootless mode on SUSE Linux Enterprise Server may fail, because the container needs read access to the SUSE Customer Center credentials. For example, running a container with the command podman run -it --rm registry.suse.com/suse/sle15 bash and then executing zypper ref results in the following error message:

Refreshing service 'container-suseconnect-zypp'.
  Problem retrieving the repository index file for service 'container-suseconnect-zypp':
  [container-suseconnect-zypp|file:/usr/lib/zypp/plugins/services/container-suseconnect-zypp]
  Warning: Skipping service 'container-suseconnect-zypp' because of the above error.
  Warning: There are no enabled repositories defined.
  Use 'zypper addrepo' or 'zypper modifyrepo' commands to add or enable repositories

To solve the problem, grant the current user the required access rights by running the following command on the host:

> sudo setfacl -m u:$(id -nu):r /etc/zypp/credentials.d/*

Log out and log in again to apply the changes.

To give multiple users the required access, create a dedicated group using the groupadd GROUPNAME command. Then use the following command to change the group ownership and rights of files in the /etc/zypp/credentials.d/ directory.

> sudo chgrp GROUPNAME /etc/zypp/credentials.d/*
> sudo chmod g+r /etc/zypp/credentials.d/*

You can then grant a specific user write access by adding them to the created group.

By definition, rootless containers are run by a regular user. At the same time, certain applications deployed using containers expect to be run as root. This leads to a problem: how do you run a container as root, when you are not root on the host system? To solve the issue, Podman relies on user namespaces to map user IDs in the container to different user IDs on the host. By default, Podman maps the root user inside the container with the user ID (UID) 0 to the UID of the current user on the host system.

To illustrate how this is done in practice, create a temporary SLE BCI-Base container (the sleep value determines for how long the container runs):

> podman run -d --rm registry.suse.com/bci/bci-base sleep 600

Then run the podman top command as follows:

> podman top -l user huser
USER  HUSER
root  1000

The output indicates that the root user in the container is mapped to the user with UID 1000 on the host, so a root process inside the container is treated by the kernel as UID 1000 outside the container. This means that even though the process is running as root inside the container, this process does not have root privileges outside of the container. Moreover, if a file owned by a UID, and this UID is not mapped into the user namespace, the file is treated as owned by “nobody” (UID 65534). This also means that the container process is not allowed to access the file, unless the file is world readable and writable.

There are also situations, when a process or an application inside a container must run as the current host user. The --userns=keep-id option solves this problem by instructing Podman to map the user as itself into the container. To see how this works, create a temporary SLE BCI-Base container, but this time with --userns=keep-id:

> podman run -d --rm --userns=keep-id registry.suse.com/bci/bci-base sleep 600

Run the podman top again:

> podman top -l user huser

USER  HUSER
tux   tux

The output now shows that the regular user on the host system is mapped into the container.

There is another way to see how this works in practice. First, run the following command:

> podman run --rm -it -v ~/Downloads/:/downloads:Z registry.suse.com/bci/bci-base:15.5 ls -al /downloads

The command creates a container from the SLE BCI-Base container image, mounts the Downloads directory on the host system as the downloads directory inside, and then runs the ls -al command in the downloads directory. The output of the command looks something like this:

-rw-r--r-- 1 root root  4417088 Aug 25 09:21 document.pdf

This shows that the file is owned by root. Now, run the same command, but this time with the --userns=keep-id option:

> podman run --userns=keep-id --rm -it -v ~/Downloads/:/downloads:Z registry.suse.com/bci/bci-base:15.5 ls -al /downloads

This time, the output looks slightly different, indicating that the file is owned by the host user:

-rw-r--r-- 1 tux users 4417088 Aug 25 09:21 document.pdf

If Podman fails to launch containers in rootless mode, check whether an entry for the current user is present in /etc/subuid on the host system:

> grep $(id -nu) /etc/subuid
  user:10000:65536

When no entry is found, add the required sub-UID and sub-GID entries via the following command:

> sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $(id -nu)

To enable the change, reboot the machine or stop the session of the current user. To do the latter, run loginctl list-sessions | grep USER and note the session ID. Then run loginctl kill-session SESSION_ID to stop the session.

The usermod command above defines a range of local UIDs to which the UIDs allocated to users inside the container are mapped on the host. Note that the ranges defined for different users must not overlap. It is also important that the ranges do not reuse the UID of an existing local user or group. By default, adding a user with the useradd command on SUSE Linux Enterprise Server automatically allocates sub-UID and sub-GID ranges.

Podman stores the containers' data in the storage graph root (default is ~/.local/share/containers/storage). Because of the way Podman remaps user IDs in rootless containers, the graph root may contain files that are not owned by your current user but by a user ID in the sub-UID region assigned to your user. As these files do not belong to your current user, they can be inaccessible to you.

To read or modify any file in the graph root, enter a shell as follows:

> podman unshare bash
> id
  uid=0(root) gid=0(root) groups=0(root),65534(nobody)

Note that podman unshare performs the same user remapping as podman run does when launching a rootless container. You cannot gain elevated privileges via podman unshare.

Warning

Do not modify files in the graph root as this can corrupt Podman's internal state and render your containers, images and volumes inoperable.