podman/docs/tutorials/rootless_tutorial.md at main · podman-container-tools/podman · GitHub
Skip to content You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert Expand file tree / rootless_tutorial.md Copy path More file actions More file actions Latest commit History History History 236 lines (157 loc) · 13.4 KB / rootless_tutorial.md Copy path File metadata and controls 236 lines (157 loc) · 13.4 KB Raw Copy raw file Download raw file Outline Edit and raw actions Basic Setup and Use of Podman in a Rootless environment.
Prior to allowing users without root privileges to run Podman, the administrator must install or build Podman and complete the following configurations. Administrator Actions Installing Podman For installing Podman, see the installation instructions . Building Podman For building Podman, see the build instructions . Networking configuration A user-mode networking tool for unprivileged network namespaces must be installed on the machine in order for Podman to run in a rootless environment.
Podman uses pasta (provided by passt ) for rootless networking. Pasta fully supports IPv6 and is architecturally secure (runs in a separate process, uses modern Linux mechanisms for isolation etc). Passt is available on most Linux distributions via their package distribution software such as yum , dnf , apt , zypper , etc. under the name passt . If the package is not available, you can build and install passt from its upstream .
More details about pasta can be found in this blog post and in podman-network(1) . Note pasta's default situation of not being able to communicate between the container and the host has been fixed in Podman 5.3: see Podman 5.3 changes for improved networking experience with pasta . /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? 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. # cat /etc/subuid johndoe: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 . 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. Rather than updating the files directly, the usermod program can be used to assign UIDs and GIDs to a user. # usermod --add-subuids 100000-165535 --add-subgids 100000-165535 johndoe grep johndoe /etc/subuid /etc/subgid /etc/subuid:johndoe:100000:65536 /etc/subgid:johndoe:100000:65536 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 running podman system migrate as that user. NOTE: Starting with shadow-utils 4.9, pluggable data sources for subid ranges can be configured via /etc/nsswitch.conf . SSSD provides a plugin ( libsubid_sss.so ) that can retrieve subordinate ID ranges from a central identity server. Instead of managing local /etc/subuid and /etc/subgid files. To enable this, configure /etc/nsswitch.conf with subid: sss .
SSSD 2.6.0 added support for the IPA provider, and SSSD 2.12.0 extended this to the generic LDAP provider. For more details on centrally managed subordinate IDs with FreeIPA, see the FreeIPA subordinate IDs documentation . Giving access to additional groups Users can fully map additional groups to a container namespace if those groups subordinated to the user: # usermod --add-subgids 2000-2000 johndoe grep johndoe /etc/subgid This means the user johndoe can "impersonate" the group 2000 inside the container.
Note that it is usually not a good idea to subordinate active user ids to other users, because it would allow user impersonation. johndoe can use --group-add keep-groups to preserve the additional groups, and --gidmap="+g102000:@2000" to map the group 2000 in the host to the group 102000 in the container: $ podman run \ --rm \ --group-add keep-groups \ --gidmap="+g102000:@2000" \ --volume "$PWD:/data:ro" \ --workdir /data \ alpine ls -lisa Enable unprivileged ping (It is very unlikely that you will need to do this on a modern distro).
Users running in a non-privileged container may not be able to use the ping utility from that container. If this is required, the administrator must verify that the UID of the user is part of the range in the /proc/sys/net/ipv4/ping_group_range file. To change its value the administrator can use a call similar to: sysctl -w "net.ipv4.ping_group_range=0 2000000" . To make the change persist, the administrator will need to add a file with the .conf file extension in /etc/sysctl.d that contains net.ipv4.ping_group_range=0 $MAX_GID , where $MAX_GID is the highest assignable GID of the user running the container.
User Actions The majority of the work necessary to run Podman in a rootless environment is on the shoulders of the machine’s administrator. Once the Administrator has completed the setup on the machine and then the configurations for the user in /etc/subuid and /etc/subgid , the user can just start using any Podman command that they wish. User Configuration Files The Podman configuration files for root reside in /usr/share/containers with overrides in /etc/containers .
In the rootless environment they reside in ${XDG_CONFIG_HOME}/containers and are owned by each individual user. Note: in environments without XDG environment variables, Podman internally sets the following defaults: $XDG_CONFIG_HOME = $HOME/.config $XDG_DATA_HOME = $HOME/.local/share $XDG_RUNTIME_DIR = /run/user/$UID on systemd environments $TMPDIR/podman-run-$UID otherwise The three main configuration files are containers.conf , storage.conf and registries.conf .
The user can modify these files as they wish. containers.conf Podman reads /usr/share/containers/containers.conf /etc/containers/containers.conf ${XDG_CONFIG_HOME}/containers/containers.conf if they exist, in that order. Each file can override the previous for particular fields. storage.conf For storage.conf the order is /etc/containers/storage.conf ${XDG_CONFIG_HOME}/containers/storage.conf In rootless Podman, certain fields in /etc/containers/storage.conf are ignored.
These fields are: graphroot="" container storage graph dir (default: "/var/lib/containers/storage") Default directory to store all writable content created by container storage programs. runroot="" container storage run dir (default: "/run/containers/storage") Default directory to store all temporary writable content created by container storage programs. In rootless Podman these fields default to graphroot="${XDG_DATA_HOME}/containers/storage" runroot="${XDG_RUNTIME_DIR}/containers" $XDG_RUNTIME_DIR defaults on most systems to /run/user/$UID . registries Registry configuration is read in this order /etc/containers/registries.conf /etc/containers/registries.d/* ${XDG_CONFIG_HOME}/containers/registries.conf The files in the home directory should be used to configure rootless Podman for personal needs.
These files are not created by default. Users can copy the files from /usr/share/containers or /etc/containers and modify them. Authorization files The default authorization file used by the podman login
The rest of this page is on the live site.