Podman

Podman is a utility provided as part of the libpod library. It can be used to create and maintain containers. Podman (Pod Manager) is a fully featured container engine that is a simple daemonless tool.

Installation

Podman can be installed via podman package in the community repository:

# apk add podman

Configuration

To run podman you'll need to enable the cgroups service.

# rc-update add cgroups # rc-service cgroups start

In the past cgroups v2 needs to be enabled in OpenRC. Currently this is the default setting in cgroups v2.

If you are running on top of Btrfs, consider setting storage driver to btrfs:

$ cat /etc/containers/storage.conf

driver = "btrfs"

If you're running podman inside a container, change the storage driver to vfs

You might need to restart your machine at this stage for the above changes to work properly.

Running as root

No further steps are required to run as root. Run an example container to verify everything works:

# podman run --rm hello-world

Running in rootless mode

To avoid permission problems with rootless podman, consider using Crun.

To run podman in rootless mode, run the following commands. Replace <USER> with your username in the following commands:

# modprobe tun # echo tun >>/etc/modules # echo <USER>:100000:65536 >/etc/subuid # echo <USER>:100000:65536 >/etc/subgid

Run an example container to verify everything works:

$ podman run --rm hello-world

Getting socket

To use the podman API or use podman remotely, you need podman socket. Socket is not needed, if podman CLI is used locally.

To get socket, start the podman service:

# rc-service podman start

The default location of the socket is /run/podman/podman.sock

Shared mount

Containers on linux might require filesystems to be mounted with different propagation than the kernel default of 'private'.

$ findmnt -o PROPAGATION /

will produce the following output:

PROPAGATION
private

This section explains few ways to mount your root(/) as shared for Distrobox to function. This is not needed when running in rootless mode.

Method1:

Fill in the file /etc/local.d/mount-rshared.start as follows:

Contents of /etc/local.d/mount-rshared.start

#!/bin/sh mount --make-rshared /

Mark it as executable:

# chmod +x /etc/local.d/mount-rshared.start

Then enable the service to autostart through OpenRC.

# rc-update add local default # rc-service local start

Method2:

An alternate solution with OpenRC v0.54.2-r1 onwards, edit the file /etc/fstab and add shared option to the root partition such that:

Contents of /etc/fstab

... /dev/sda2 / ext4 rw,relatime,shared 0 1 ...

For both the above cases, after a reboot test the working of shared / mount using the command:

# findmnt -o PROPAGATION /

which will produce the following output:

PROPAGATION
shared

Docker compose

The podman-compose package from provides a drop-in replacement for docker compose. Each time a docker compose is used, a warning will remind that this is using podman under the hood. This warning can be squelched permanently by running:

# touch /etc/containers/nodocker

Troubleshooting

"/" is not a shared mount

If you see a warning:

WARN[0000] "/" is not a shared mount, this could cause issues or missing mounts with rootless containers

You might want to fix this temporarily, for currently running system by issuing the command:# mount --make-rshared / Alternately, refer to Shared mount section for permanent solution(s).

Permission problems with rootless podman

You may encounter an error when entering your rootless container:

Error: unable to start container "XYZ": runc: runc create failed: unable to start container process: unable to apply cgroup configuration: rootless needs no limits + no cgrouppath when no permission is granted for cgroups: mkdir /sys/fs/cgroup/XYZ: permission denied: OCI permission denied

This problem may be solved by replacing runc by Crun and recreating your container. Keep in mind that crun replaces runc, which will render containers made with the latter unusable until recreated.