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 on the system.

# Debian
sudo apt install podman

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

Configure and enable Podman in rootless or rootful mode. Rootless mode is strongly encouraged, but certain deployments may require rootful Podman.

Rootless Dependencies

Install 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 uidmap fuse-overlayfs passt systemd-container

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

Create System User

Create a system user that will run Podman, podmanu in this example. Add this user to the systemd-journal group so it is able to access system logs.

Debian

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

sudo usermod -aG systemd-journal podmanu

MicroOS

Open a transactional-update shell.

sudo transactional-update shell

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

usermod -aG systemd-journal podmanu

Exit the transactional-update shell.

exit

Reboot to apply changes.

sudo reboot

MachineCTL

Use MachineCTL to interact with the user for a full session. The su command will not allow control over user systemd units.

sudo machinectl shell --uid=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.

Debian

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

MicroOS

Open a transactional-update shell.

sudo transactional-update shell

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

Exit the transactional-update shell.

exit

Reboot to apply changes.

sudo reboot

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.

Debian

sudo vim /etc/subuid

podmanu:300000:65536

sudo vim /etc/subgid

podmanu:300000:65536

MicroOS

Open a transactional-update shell.

sudo transactional-update shell

vim /etc/subuid

podmanu:300000:65536

vim /etc/subgid

podmanu:300000:65536

Exit the transactional-update shell.

exit

Reboot to apply changes.

sudo reboot

Service Configuration

Configure the Podman service.

Enable Lingering

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

sudo loginctl enable-linger podmanu

Enable Podman

Enable the Podman socket for the rootless user. Start a new shell as podmanu using MachineCTL.

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, be sure to include the user flag.

systemctl enable --user --now podman.socket

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.

Stop and disable the Podman socket.

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

Containers Configuration

Network Capabilities

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

libpod

Open the containers.conf configuration file. If this file is missing look for a libpod.conf (deprecated). If both files are missing, create a new containers.conf file for configuration overrides (default configuration is at /usr/share/containers/containers.conf).

sudo vim /etc/containers/containers.conf

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

events_logger = "journald"

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}