# Podman

From ArchWiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Related articles

- systemd-nspawn
- Linux Containers
- Docker
- Buildah
- Vagrant

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.

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 cockpit-podman.

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 `/usr/share/containers/`. You must copy necessary files to `/etc/containers` before edit. To configure the network bridge interface used by Podman see `/etc/cni/net.d/87-podman-bridge.conflist`.

### Rootless Podman

Warning: Podman rootless relies on the unprivileged user namespace usage (`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 podman(1) § Rootless mode.

#### Enable kernel.unprivileged_userns_clone

First, check the value of `kernel.unprivileged_userns_clone` by running:

    $ sysctl kernel.unprivileged_userns_clone

If it is currently set to `0`, enable it by setting `1` via sysctl or kernel parameter.

Note: linux-hardened has `kernel.unprivileged_userns_clone` set to `0` by default.

#### Set subuid and subgid

In order for users to run rootless Podman, a subuid(5) and subgid(5) must be set for each user that wants to use it. These information must, ultimately, be stored in `/etc/subuid` and `/etc/subgid` which lists the UIDs for their user namespace.

`/etc/subuid` and `/etc/subgid` do not exist by default. If they do not exist yet in your system, create them by running:

    # touch /etc/subuid /etc/subgid

Note: The above command is required, because the usermod used below do not create them.

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-165536 --add-subgids 100000-165536 username

Tip: Instead of using usermod command, this could be achieved either by editing `/etc/subuid` and `/etc/subgid` directly.

Now, you should have the following content (replacing `username` with the given username):

    /etc/subuid

    username:100000:65536

    /etc/subgid

    username:100000:65536

Note: Many images require 65536 uids / gids for mapping (notably the base busybox and alpine images). It is recommended that you allocate at least that many uids / gids for each user to maximize compatibility with docker.

#### Propagate changes to subuid and subgid

Rootless Podman uses a pause process to keep the unprivileged namespaces alive. This prevents any change to the `/etc/subuid` and `/etc/subgid` 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 podman is able to start and run Podman containers.

### Storage

The configuration for how and where container images and instances are stored takes place in `/etc/containers/storage.conf`.

Note: When using #Rootless Podman overrides to the storage settings can be added to `$XDG_CONFIG_HOME/containers/storage.conf` on a per-user basis.

Set the `driver` according to the filesystem in use for the storage location (see containers-storage.conf(5) § STORAGE_TABLE).

### Foreign architectures

Podman is able to run images built for different CPU architecture than host using Wikipedia:binfmt_misc system.

To enable it install qemu-user-staticAUR and binfmt-qemu-staticAUR packages.

systemd comes with `systemd-binfmt.service` service which should enable new rules.

Verify that binfmt rules have been added:

    ls /proc/sys/fs/binfmt_misc

    DOSWin        qemu-cris        qemu-ppc      qemu-sh4eb        status
    qemu-aarch64  qemu-m68k        qemu-ppc64    qemu-sparc
    qemu-alpha    qemu-microblaze  qemu-riscv64  qemu-sparc32plus
    qemu-arm      qemu-mips        qemu-s390x    qemu-sparc64
    qemu-armeb    qemu-mipsel      qemu-sh4      register

Podman should now be able to run foreign architecture images. Most commands use the foreign architecture when `--arch` option is passed.

Example:

    podman run --arch arm64 'docker.io/alpine:latest' arch

    aarch64

### Docker Compose

With 3.0.0, podman has support for docker-compose. This requires enabling a podman socket which pretends to be docker; start the `podman.service` unit. For rootless containers, this requires you to start the `podman.service` user unit instead and set the `DOCKER_HOST` variable:

    $ export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock"

## Images

Note: You may omit the registry prefix from the images, as Podman will automatically search for the image in all registries defined in `/etc/containers/registries.conf` at `registries.search` in the defined order. The following images will always contain the prefix, to allow for configurations without `docker.io` in the configuration.

### Arch Linux

The following command pulls the Arch Linux x86_64 image from Docker Hub. This is a stripped down version of Arch core without network, etc.

    # podman pull docker.io/archlinux

See also README.md.

For a full Arch base, clone the repo from above and build your own image.

    $ git clone https://gitlab.archlinux.org/archlinux/archlinux-docker.git

Make sure that the devtools package is installed.

Edit the `packages` file so it only contains 'base'. Then run:

    # make rootfs
    # podman build -t archlinux .

### 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 [1], [2] and [3] 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

### 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: http://docs.podman.io/en/latest/markdown/podman-auto-update.1.html#examples

### 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 `dnsname` plugin enabled:

    $ podman network create foo

    /home/user/.config/cni/net.d/foo.conflist

    $ podman run --rm -it --network=foo docker.io/library/alpine:latest ip addr

    Error: command rootless-cni-infra [alloc 89398a9315256cb1938075c377275d29c2b6ebdd75a96b5c26051a89541eb928 foo festive_hofstadter    ] in container 1f4344bbd1087c892a18bacc35f4fdafbb61106c146952426488bc940a751efe failed with status 1, stdout="", stderr="exit status 3\n"

This can be solved by adding the following lines to `/etc/apparmor.d/local/usr.sbin.dnsmasq`:

    @{run}/containers/cni/dnsname/*/dnsmasq.conf r,
    @{run}/containers/cni/dnsname/*/addnhosts r,
    @{run}/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

### 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.

## See also

- Official website

Categories:

- Virtualization
- Sandboxing