Knowledgebase

Introduction

Podman (the POD MANager) is a daemonless tool for managing Open Container Initiative (OCI), Docker containers schema 1, Docker containers schema 2, pods (groups of containers), images and volumes. While the podman CLI client aims to be compatible with the docker commands and sub-commands, Podman differs from Docker in two respects that are worth calling attention to:

1. Podman containers run unprivileged (rootless) by default.
2. There is no daemon (service) running.

In this tutorial, we will install Podman on Ubuntu 18.04 and use it to start containers and manage containers as a root and non-root user. Converting containers and their workflows to be rootless with the minimum capabilities required to run is journey of learning to crawl, walk then run. This tutorial will give you a good start to that journey.

Prerequisites

• A fully-updated Ubuntu server.
• A non-root sudo user.

This guide applies to:

• Ubuntu 20.04 LTS
• Ubuntu 18.04 LTS

Podman Overview

The Podman project scope statement provides good summary of the functionality of Podman:

• Support for multiple container image formats, including OCI and Docker images.
• Full management of those images, including pulling from various sources (including trust and verification), creating (built via Containerfile or Dockerfile or committed from a container), and pushing to registries and other storage backends.
• Full management of container lifecycle, including creation (both from an image and from an exploded root filesystem), running, checkpointing and restoring (via CRIU), and removal.
• Support for pods, groups of containers that share resources and are managed together.
• Resource isolation of containers and pods.
• Support for a Docker-compatible CLI interface.
• Support for a REST API providing both a Docker-compatible interface and an improved interface exposing advanced Podman functionality.
• In the future, integration with CRI-O to share containers and backend code.

1. Install Podman

Ensure some system identifying data is available (we will use VERSION_ID).

$ source /etc/os-release

Add the Podman debian package repository to Apt.

$ sudo sh -c "echo 'deb http://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/stable/xUbuntu_${VERSION_ID}/ /' > /etc/apt/sources.list.d/devel:kubic:libcontainers:stable.list"
$ wget -nv https://download.opensuse.org/repositories/devel:kubic:libcontainers:stable/xUbuntu_${VERSION_ID}/Release.key -O- | sudo apt-key add -
$ sudo apt-get update -qq
$ sudo apt-get -qq --yes install podman

2. Executing Podman

Confirm Podman has been installed correctly.

$ podman info

You should see the Podman configuration and version information of the various components.

Using Podman from a terminal/shell consists of passing a chain of options, commands then arguments. The syntax takes this form:

podman [option] [command] [arguments]

The v1 and v2 commands are in most cases the same as the docker CLI. Podman strives for Docker compatibility, so you can generally substitute podman for docker in documents and blog posts code examples.

To review Podman options and commands:

$ podman --help

To view any sub-commands and options for a command:

$ podman <command> --help

3. Working with OCI Registries

Podman supports multiple container registries. When you specify a container name that does not contain a registry, e.g. store/elastic/metricbeat:7.9.0 rather than docker.io/store/elastic/metricbeat:7.9.0, Podman will consult the registry configuration file (/etc/containers/registries.conf) to obtain a list of registries to pull the container image from.

Add docker.io and registry.access.redhat.com (you can add some other registries too).

Edit /etc/containers/registries.conf:

$ sudo nano /etc/containers/registries.conf

Paste the follow contents:

# This is a system-wide configuration file used to
# keep track of registries for various container backends.
# It adheres to TOML format and does not support recursive
# lists of registries.

# The default location for this configuration file is
# /etc/containers/registries.conf.

# The only valid categories are: 'registries.search', 'registries.insecure', 
# and 'registries.block'.

[registries.search]
registries = ['docker.io', 'quay.io', 'registry.access.redhat.com']

# If you need to access insecure registries, add the registry's fully-qualified name.
# An insecure registry is one that does not have a valid SSL certificate or only does HTTP.
[registries.insecure]
registries = []

# If you need to block pull access from a registry, uncomment the section below
# and add the registries fully-qualified name.
#
# Docker only
[registries.block]
registries = []

Save and exit the file.

4. Using Podman with Sudo

While podman runs rootless by default you will sometimes come across a container that requires root privileges to build, or run the container. Generally, this is because Docker is run with root privileges by default, and many Dockerfiles and containers have been developed, built and run in a root environment. Since Docker Engine v19.03 it is possible to configure Docker to run rootless. However, configuring Docker for rootless operation is not trivial, so you will find most existing Docker tutorials and blog posts develop, build and run Docker containers as root.

Using sudo podman ... is generally sufficient to make the Podman build-time and run-time emulate the Docker behavior.

To better understand the context and implications of running Podman as root compared to non-root run sudo podman info and compare the output to that obtained previously from running podman info. Specifically, note the different settings for host:remoteSocket:path:, store:configFile:, store:graphRoot:, store:runRoot: and store:volumePath:.

Next, download and run the hello-word image with the following command:

$ sudo podman run hello-world

You should see the following output:

Trying to pull docker.io/library/hello-world...Getting image source signatures
Copying blob 1b930d010525 done
Copying config fce289e99e done
Writing manifest to image destination
Storing signatures
Hello from Docker!

This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:

    The Docker client contacted the Docker daemon.
    The Docker daemon pulled the hello-world image from the Docker Hub.
    The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading.
    The Docker daemon streamed that output to the Docker client, which sent it to your terminal.

The container cannot tell that it was run by Podman rather than Docker - generally this does not matter. Consequently, you can substitute Podman client for Docker daemon in the above output and have a reasonable summary of the actions taken - in fact Podman uses the Skopeo (container transfer) and Buildah (container build) libraries to implement some functionality. However, the essential difference is that no daemon (service) is in use.

5. Using Podman without Sudo

Display the current (non-root) user ID number (uid) on the host system.

$ id -u $(whoami)
1000

Check Podman rootless configuration is set up properly users.

$ podman unshare cat /proc/self/uid_map
     0       1000          1
     1     100000      65536

Then for groups.

$ podman unshare cat /proc/self/gid_map
     0       1000          1
     1     100000      65536

This shows how uids and gids are mapped from the user namespace inside the container to the host uids. Specifically, the uid of 0 inside the container is mapped to the current host system user ID, which is 1000. While uid value 1 inside the container is mapped to uid value 100000 on the host system. So a container uid value 47 would map to a uid value 100046 on the host system.