Podman
Podman is an alternative to Docker, providing a similar interface. It supports rootless containers and a shim service for docker-compose.
Installation
Install the podman package. Additionally if you want to build container images look at Buildah.
For container networking, install cni-plugins or netavark since v4.0.
If you want to replace Docker, one can install podman-docker to mimic the docker binary along with man pages.
Unlike Docker, Podman does not require a daemon, but there is one providing an API for services like cockpit via .
By default, it is only possible to run Podman containers as root. See #Rootless Podman to set up running containers as a non-root user.
Configuration
Configuration files for configuring how containers behave are located at . You must copy necessary files to before editing. To configure the network bridge interface used by Podman, see .
Rootless Podman
CONFIG_USER_NS_UNPRIVILEGED) which has some serious security implications, see Security#Sandboxing applications for details.By default, only root is allowed to run containers (or namespaces in kernelspeak). Running rootless Podman improves security as an attacker will not have root privileges over your system, and also allows multiple unprivileged users to run containers on the same machine. See also .
Additional dependencies
The following packages are required to run Podman in a rootless environment:
Enable kernel.unprivileged_userns_clone
First, check the value of by running:
$ sysctl kernel.unprivileged_userns_clone
If it is currently set to , enable it by setting via sysctl or kernel parameter.
Set subuid and subgid
In order for users to run rootless Podman, a and configuration entry must exist for each user that wants to use it. New users created using useradd(8) have these entries by default.
Users created prior to shadow 4.11.1-3 do not have entries in /etc/subuid and /etc/subgid by default. An entry can be created for them using the usermod(8) command or by manually modifying the files.
The following command enables the username user and group to run Podman containers (or other types of containers in that case). It allocates a given range of UIDs and GIDs to the given user and group.
# usermod --add-subuids 100000-165535 --add-subgids 100000-165535 username
Note, that the above range for the user username may already be taken by another user as it defines the default range for the first user on the system. If in doubt, first consult the /etc/subuid and /etc/subgid files to find the already reserved ranges.
Propagate changes to subuid and subgid
Rootless Podman uses a pause process to keep the unprivileged namespaces alive. This prevents any change to the and files from being propagated to the rootless containers while the pause process is running. For these changes to be propagated it is necessary to run:
$ podman system migrate
After this, the user/group specified in the above files is able to start and run Podman containers.
Storage
The configuration for how and where container images and instances are stored takes place in .
Set the according to the filesystem in use for the storage location (see ).
Foreign architectures
Podman is able to run images built for different CPU architecture than host using Wikipedia:binfmt_misc system.
To enable it, install and .
systemd comes with systemd-binfmt.service service which should enable new rules.
Verify that binfmt rules have been added:
Podman should now be able to run foreign architecture images. Most commands use the foreign architecture when option is passed.
Example:
# podman run --arch arm64 'docker.io/alpine:latest' arch
aarch64
Docker Compose
Podman 3.0.0 introduces docker-compose support. This requires enabling a Podman socket which pretends to be docker; start the unit. For rootless containers, this requires you to start the user unit instead and set the variable:
$ export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock"
To get hostname resolution between containers running install .
Images
Arch Linux
The following command pulls the Arch Linux x86_64 image from Docker Hub.
# podman pull docker.io/archlinux
See the Docker Hub page for a full list of available tags, including versions with and without build tools.
See also README.md.
Alpine Linux
Alpine Linux is a popular choice for small container images, especially for software compiled as static binaries. The following command pulls the latest Alpine Linux image from Docker Hub:
# podman pull docker.io/alpine
Alpine Linux uses the musl libc implementation instead of the glibc libc implementation used by most Linux distributions. Because Arch Linux uses glibc, there are a number of functional differences between an Arch Linux host and an Alpine Linux container that can impact the performance and correctness of software. A list of these differences is documented in https://wiki.musl-libc.org/functional-differences-from-glibc.html.
Note that dynamically linked software built on Arch Linux (or any other system using glibc) may have bugs and performance problems when run on Alpine Linux (or any other system using a different libc). See , and for examples.
CentOS
The following command pulls the latest CentOS image from Docker Hub:
# podman pull docker.io/centos
See the Docker Hub page for a full list of available tags for each CentOS release.
Debian
The following command pulls the latest Debian image from Docker Hub:
# podman pull docker.io/debian
See the Docker Hub page for a full list of available tags, including both standard and slim versions for each Debian release.
Troubleshooting
Add pause to process
WARN[0000] Failed to add pause process to systemd sandbox cgroup: Process org.freedesktop.systemd1 exited with status 1
Can be solved using: https://github.com/containers/crun/issues/704
# echo +cpu +cpuset +io +memory +pids > /sys/fs/cgroup/cgroup.subtree_control
Container dns will not be enabled
WARN[0000] binary not found, container dns will not be enabled
If you installed netavark as podman network backend you need to install
Containers terminate on shell logout
It may happen that after logging out from machine, Podman containers are stopped. To prevent that, user lingering should be enabled for user running containers:
$ loginctl enable-linger
You can also create user systemd unit as described: https://docs.podman.io/en/latest/markdown/podman-auto-update.1.html#examples
Failed to move rootless netns
$ docker-compose up
ERRO[0000] failed to move the rootless netns slirp4netns process to the systemd user.slice: Process org.freedesktop.systemd1 exited with status 1
Can be solved by starting/enabling .
Error building pause image after Podman upgrade 3.x to 4.0
Error: building local pause image: finding pause binary: exec: "catatonit": executable file not found in $PATH
Install the package to fix the error.
For details on upgrading from 3.x to 4.0, see the official blog article
Error on commit in rootless mode
Error committing the finished image: error adding layer with blob "sha256:02823fca9b5444c196f1f406aa235213254af9909fca270f462e32793e2260d8": Error processing tar file(exit status 1) permitted operation
Check that the storage driver is overlay in the #Storage configuration.
Error when creating a container with bridge network in rootless mode
If you are using AppArmor you might end up with problems when creating container using a bridge network with the plugin enabled:
This can be solved by adding the following lines to :
owner /run/user/[0-9]*/containers/cni/dnsname/*/dnsmasq.conf r, owner /run/user/[0-9]*/containers/cni/dnsname/*/addnhosts r, owner /run/user/[0-9]*/containers/cni/dnsname/*/pidfile rw,
And then reloading the AppArmor profile:
# apparmor_parser -R /etc/apparmor.d/usr.sbin.dnsmasq # apparmor_parser /etc/apparmor.d/usr.sbin.dnsmasq
No image found
By default, the registry list is not populated as the files in the package come from upstream. This means that by default, trying to pull any image without specifying the registry will result in an error similar to the following:
Error: short-name "archlinux" did not resolve to an alias and no unqualified-search registries are defined in "/etc/containers/registries.conf"
A starting configuration could be the following:
/etc/containers/registries.conf.d/00-unqualified-search-registries.conf
unqualified-search-registries = ["docker.io"]
This is equivalent to the default docker configuration.
A less convenient alternative, but having a higher compatibility with systems without configured shortnames, use the full registry path in the or .
Containerfile
FROM docker.io/archlinux/archlinux
Permission denied: OCI permission denied
Can be solved: https://bbs.archlinux.org/viewtopic.php?id=253966
$ env DBUS_SESSION_BUS_ADDRESS= podman ... $ env DBUS_SESSION_BUS_ADDRESS= podman-compose ...
Pushing images to Docker Hub: access denied/authentication required
When using to push container images to Docker Hub, the following errors could occur: or . The following hints can help to fix potential issues
- Tag the local image, e.g.,
# podman tag <localImage> docker.io/<dockerHubUsername>/<dockerHubRepository>:<Tag>
- Push the tagged image, e.g.,
# podman push docker.io/<dockerHubUsername>/<dockerHubRepository>:<Tag> docker://docker.io/<dockerHubUsername>/<dockerHubRepository>:<Tag>
- Login to docker.io, the Docker Hub repository and Docker Hub Registry server, e.g.,
# podman login -u <DockerHubUsername> -p <DockerHubPassword> registry-1.docker.io # podman login -u <DockerHubUsername> -p <DockerHubPassword> docker.io/<dockerHubUsername>/<dockerHubRepository> # podman login -u <DockerHubUsername> -p <DockerHubPassword> docker.io
- Logout from all registries before the login, e.g.,
# podman logout --all
- Add <dockerHubUsername> as collaborator in the Docker Hub Collaborators tab of the reporsitory
WARN[0000] "/" is not a shared mount, this could cause issues or missing mounts with rootless containers
Buildah/Podman running as rootless expects the bind mount to be shared, check if it is set to private:
In this case see and set temporarily the mount as shared with:
# mount --make-shared /
To set it permanently edit /etc/fstab and add the shared option to the desired mount and reboot. It will result in a entry like: