Podman
podman is a daemonless container engine for developing, managing, and running OCI Containers on linux.
podman aims to be a drop-in replacement for docker for most user applications running docker images, setting alias docker=podman
should be enough for most pipelines to switch to podman[1]. buildah and skopeo are other tools which provide the other parts of the docker stack not provided by podman, such as building and distributing images[2].
Installation
Kernel
Kernel version 3.10 or greater is recommended[3].
As of podman 1.3.2 and runc 1.0.0_rc8, there is no built-in kernel config check included. However, the runc upstream provides a method of listing its required kernel configuration via check-config.sh script
Some of the config options from the
check-config.sh
script are deprecated. They are safe to ignore.Rootless mode
Configure the kernel
user namespaces have to be enabled in order to use the rootless mode. Many docker images make use of fuse and overlayfs, which also need to be enabled. The tun
kernel module also needs to be available and loaded for allowing rootless mode to access networking.
General setup --->
-*- Namespaces support --->
[*] User namespace
File systems --->
<*> FUSE (Filesystem in Userspace) support
<*> Overlay filesystem support
Device Drivers --->
-*- Network device support --->
-*- Network core driver support --->
<*/M> Universal TUN/TAP device driver support
Load required modules
If the tun
module is not built into the kernel, it needs to be loaded manually:
tun
Configure subuid/gid
podman requires the user to have a range of UIDs listed in /etc/subuid and /etc/subgid files. These UIDs are used for mapping the container UIDs to the host UIDs via user namespaces.
An overview for the recommended configuration of subuid/subgids is given in the wiki - Subuid subgid.
USE flags
USE flags for app-containers/podman A tool for managing OCI containers and pods with Docker-compatible CLI
apparmor
|
Enable support for the AppArmor application security system |
btrfs
|
Enables btrfs support (graph driver) in Podman |
cgroup-hybrid
|
Use legacy (hybrid) cgroups instead of modern (unified) cgroups |
fuse
|
Enables fuse dependencies (fuse-overlayfs is especially useful for rootless mode). |
init
|
Enables catatonit dependency required for podman run --init. |
rootless
|
Enables dependencies for running in rootless mode. |
seccomp
|
Enable seccomp (secure computing mode) to perform system call filtering at runtime to increase security of programs |
selinux
|
!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur |
systemd
|
Enable use of systemd-specific libraries and features like socket activation or session tracking |
wrapper
|
Install wrapper which lets use podman for command `docker` |
Emerge
It is recommended to use app-containers/crun as the OCI runtime provider, bug #723080.
root #
emerge --ask --oneshot app-containers/crun app-containers/podman
root #
emerge --ask app-containers/podman
Configuration
Files
- /etc/containers/registries.conf - Specifies which container registries should be searched for images.
- /etc/containers/policy.json - Defines policies for image validation.
Defaults are provided as /etc/containers/registries.conf.example and /etc/containers/policy.json.example.
- /etc/conf.d/podman - Configuration file for the podman OpenRC service.
Example: specify the TCP socket for the API service daemon
#SOCKET="unix:///run/podman/podman.sock"
SOCKET="tcp://localhost:12979" # this port is an example, choose whatever you want
Usage
The podman tool aims to be a drop-in replacement for docker client provided by Docker. For example, docker run becomes podman run and docker build becomes podman build.
All Container Pod-related actions are accessible via podman pod command.
Managing and using images
To search for available images, use podman search:
user $
podman search gentoo
NAME DESCRIPTION docker.io/osuosl/gentoo docker.io/osuosl/gentoo-ppc64le docker.io/osuosl/gentoo-i686 docker.io/centerforopenneuroscience/opfvta Gentoo based container for a reproducible an... docker.io/gentoo/stage3 Official Gentoo stage3 images. docker.io/gentoo/portage Official Gentoo Portage snapshot. Designed t... ...
To download an image, use podman pull:
user $
podman pull docker.io/gentoo/stage3
Trying to pull docker.io/gentoo/stage3:latest... Getting image source signatures Copying blob 93476f02ccbb done | Copying config eb88956325 done | Writing manifest to image destination eb8895632523167a51c60f247fbce008ca99bd54924c26f3ec3371c20524d88c
To list images available locally, run podman images:
user $
podman images
$ podman images REPOSITORY TAG IMAGE ID CREATED SIZE docker.io/gentoo/stage3 latest eb8895632523 3 days ago 1.34 GB
To use an image to interactively run a command in a new container, removing that container once it's exited:
user $
podman run --interactive --tty --rm docker.io/gentoo/stage3:latest /usr/bin/bash
The --interactive
and --tty
options can be abbreviated as -i
and -t
, respectively.
Detailed information can be found in the podman-search(1), podman-pull(1), podman-images(1). and podman-run(1) man pages.
Managing and using containers
All existing containers, running or not, can be listed via podman container:
user $
podman container list -a
Without the -a
option, only running containers will be listed.
Containers can be created, but not started, by using the create; subcommand if a name is not supplied, a name will be generated automatically.
user $
podman create --interactive --tty --name gentoo-bash docker.io/gentoo/stage3:latest /usr/bin/bash
Containers can be started, restarted and stopped via the start, restart and stop subcommands, e.g.:
user $
podman start gentoo-bash
Running containers can be listed via the ps subcommand:
user $
podman ps
Adding the -a
option will list all containers, running or not.
A container can be deleted via the rm subcommand:
user $
podman rm gentoo-bash
Detailed information can be found in the podman-container(1), podman-create(1), podman-start(1), podman-ps(1), and podman-rm(1) man pages.
Example: A systemd container for the root user on an OpenRC system
Create a container named "gentoo-systemd", fetching the base image if necessary, that will run that image's init command:
root #
podman create --interactive --tty --name gentoo-systemd docker.io/gentoo/stage3:systemd /usr/sbin/init
Set the password for the root user by mounting the container's root filesystem and using passwd(1) to change it:
root #
podman mount gentoo-systemd
root #
passwd -R [mount directory]
root #
podman unmount gentoo-systemd
Start the container and immediately attach to it:
root #
podman container start --attach gentoo-systemd
This should result in a boot sequence and a login prompt. Once logged in, confirm that systemd is PID 1 by running systemctl status.
Exposing containers to local network
By default, podman works in bridge mode with a separate cni-podman0 bridge, and then requests are translated to local network via NAT. It is possible, only for root, to give pods/containers real ips on the local network using macvlan mode.
First enable and start the cni-dhcp daemon:
root #
rc-update add cni-dhcp default
root #
rc-service cni-dhcp start
Add a new network config for podman to support macvlan networks.
{
"cniVersion": "0.4.0",
"name": "macvlan",
"plugins": [
{
"type": "macvlan",
"master": "br0",
"isGateway": true,
"ipam": {
"type": "dhcp"
}
},
{
"type": "portmap",
"capabilities": {
"portMappings": true
}
},
{
"type": "firewall"
},
{
"type": "tuning"
}
]
}
Here it is assumed that there is an externally configured bridge br0 already in existence. An example of such a configuration is available in the wiki - Network_bridge#Single_NIC_bridge. It is also possible to use an existing ethernet device, such as enp5s0f0 and attach to it.
Now it is possible to create a pod with this network:
root #
podman pod create --name homeserver --network macvlan
To validate that the pod has the proper configuration, an alpine test container can be run inside this pod:
root #
podman run -dt --pod homeserver --name alpine_test docker.io/library/alpine:latest top
root #
podman exec alpine_test ip addr
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 inet 127.0.0.1/8 brd 127.255.255.255 scope host lo valid_lft forever preferred_lft forever inet6 ::1/128 scope host proto kernel_lo valid_lft forever preferred_lft forever 2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 link/ether 3A:09:C6:B8:7F:DB brd ff:ff:ff:ff:ff:ff inet 192.168.2.121/24 brd 192.168.2.255 scope global dynamic noprefixroute enp5s0 valid_lft 85793sec preferred_lft 74993sec inet6 fe80::ab3d:b093:a223:776a/64 scope link noprefixroute valid_lft forever preferred_lft forever inet6 fe80::8c32:bb30:5827:8c34/64 scope link valid_lft forever preferred_lft forever
Troubleshooting
Not enough namespaces
When running a container an error appears: error creating libpod runtime: there might not be enough IDs available in the namespace.
In this case, increase the number of user namespaces permanently via a kernel setting:
user.max_user_namespaces=15076
Slow storage in the rootless mode
Check the used storage driver:
user $
podman info
If the reported storage driver is vfs
, you might want to switch to a faster overlayfs
.
See also
External resources
- podman(1)
- podman-create(1)
- podman-container(1)
- podman-images(1)
- podman-mount(1)
- podman-ps(1)
- podman-pull(1)
- podman-restart(1)
- podman-rm(1)
- podman-run(1)
- podman-search(1)
- podman-start(1)
- podman-stop(1)
- podman-unmount(1)
References
- ↑ What is podman?. Retrieved on January 17, 2021
- ↑ A Comprehensive Container Runtime Comparison, Retrieved on January 18, 2021
- ↑ Container Specification - v1, github. Retrieved on August 11, 2019