Podman Setup

Debian / Ubuntu

OpenSUSE MicroOS

Overview

Install Podman and setup rootless mode on a Linux system.

Assumptions

• Initial System Setup completed.

• Logged in as administrative user.

Update

Before getting started, update package repositories and apply upgrades for the latest patches.

# Debian
sudo apt update
sudo apt upgrade

# Microos
sudo transactional-update update && sudo reboot

Installation

Podman

Install Podman, crun, and rootless dependencies on the system.

Crun is an optional OCI runtime replacement for runc.

Dependencies required for rootless operation: uidmap, fuse-overlayfs, passt. On MicroOS the uidmap package will not be available; the newuidmap and newguidmap utilities will already be installed by default. This can be verified with which newuidmap && which newgidmap.

Also install MachineCTL via the systemd-container package for shell access and management of the rootless user. The su utility will not work without enabling SSH access for the rootless user and opening a new session. MachineCTL overcomes this problem without having to expose the user to SSH.

# Debian
sudo apt install podman crun uidmap fuse-overlayfs passt systemd-container

# Microos
sudo transactional-update pkg install podman crun fuse-overlayfs passt systemd-container && sudo reboot

By default, rootless users are not able to bind to ports below 1024. If the containers that will run on this system do not require any low ports, this is good behavior and should be kept. If the system requires access to low ports from rootless users, this can be achieved by enabling the cap_net_bind_service for the Podman service.

To assign capabilties, install the libcap2-bin package.

# Debian
sudo apt install libcap2-bin

# Microos
sudo transactional-update pkg install libcap2 && sudo reboot

Configure Podman

Events Logger

Create a container configuration override file for the events logger.

sudo vim /etc/containers/containers.conf.d/99-logger.conf

Set the event logger to journald for Podman. Uncomment, add, or modify the events_logger setting.

events_logger = "journald"

Crun Runtime

Create a container configuration override for OCI runtime.

sudo vim /etc/containers/containers.conf.d/99-engine.conf

Define the engine as crun.

[engine]
runtime = "crun"

Create System User

Create a system user that will run Podman, podmanu in this example.

sudo useradd --system --user-group --create-home --home /opt/podmanu --shell /bin/bash podmanu

Add this user to the systemd-journal group so it is able to access system logs.

sudo usermod -aG systemd-journal podmanu

Enable lingering for the rootless user so Podman can run in the background.

sudo loginctl enable-linger podmanu

UID/GID Configuration

The podmanu system user requires at least 65,536 UIDs and GIDs.

In theory, you can grant these IDs using usermod. You may encounter an error like: usermod: invalid subordinate uid range. While this is a valid error, it may not actually apply in this case. Verify the range manually for overlaps/validity. If the error persists, manually configure the subuid and subgid using an editor.

usermod

Attempt to create the UID/GID reservations with usermod. If this fails configure them manually.

sudo usermod --add-subuids 300000:65536 --add-subgids 300000:65536 podmanu

Manually

If the usermod command doesn’t work, manually configure the UIDs and GIDs. While doing this make sure no other user/group entries overlap in range.

Add matching UID and GID ranges to the /etc/subuid and /etc/subgid files for the podmanu rootless user.

sudo vim /etc/subuid

podmanu:300000:65536

sudo vim /etc/subgid

podmanu:300000:65536

Podman User Setup

Configure the Podman rootless user and service.

Start a new shell as podmanu using MachineCTL. The su command will not allow control over user systemd units.

sudo machinectl shell --uid=podmanu

Define the DOCKER_HOST environment variable, add it to .bashrc to make it permanent.

echo 'export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock' >> $HOME/.bashrc

Source the .bashrc file to apply changes.

source $HOME/.bashrc

Enable the Podman socket and Podman container restart service, be sure to include the user flag.

systemctl enable --user --now podman.socket
systemctl enable --user --now podman-restart.service

Verify the Podman socket is running.

systemctl status --user podman.socket

Exit the MachineCTL shell.

exit

The system is now ready to deploy rootless containers.

Disable Rootful Podman

If the Podman socket was enabled as root, disable the rootful process.

sudo systemctl stop podman.socket && sudo systemctl disable podman.socket

Errors

Container Logs

Container logs may not work for rootless users. Configure the event logger as journald and verify the rootless Podman user is in the systemd-journal group to resolve this.

Unable to get container logs: failed to obtain logs for Container 'container-id': initial journal cursor: failed to get cursor: cannot assign requested address rootless user

Cannot Connect

An error may occur when deploying stacks using compose referencing an inaccessible Docker daemon. When using Podman this means you need to define the DOCKER_HOST environment variable .

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

RunRoot Path

Unwritable RunRoot path. Probably trying to run a rootful container as rootless, or there’s a misconfiguration. Consider Stack Overflow post 73814619 .

podman[]: time="" level=warning msg="RunRoot is pointing to a path (/run/user/$UID/containers) which is not writable. Most likely podman will fail."

Permission Denied podman.sock

Permission denied for /run/podman/podman.sock may occur when trying to start a Podman container in rootless mode. Replace the -v /run/podman/podman.sock:/run/podman/podman.sock with -v /run/user/0000/podman/podman.sock:/run/podman/podman.sock, where 0000 is the rootless user UID. Get the current user UID with id -u, or check in /etc/passwd.

Error: statfs /run/podman/podman.sock: permission denied

References

^{1 2 3 4 5 6}