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 && reboot

Installation

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 should be used, and is strongly encouraged.

Rootless Mode

Rootless mode works out the box with Podman, but requires some additional configuration for optimal performance.

Install Dependencies

Install dependencies required for rootless operation: uidmap, dbus-user-session, fuse-overlayfs, passt.

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 dbus-user-session fuse-overlayfs passt systemd-container

# Microos
sudo transactional-update pkg install uidmap dbus-user-session fuse-overlayfs passt systemd-container && reboot

Create System User

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

Debian

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

MicroOS

Open a transactional-update shell.

sudo transactional-update shell

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

Exit the transactional-update shell.

exit

Reboot to apply changes.

sudo reboot

Grant IDs (usermod)

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

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

Grant IDs (Manual)

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

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

Enable the Podman socket, be sure to include the user flag.

systemctl enable --user podman.socket

Verify the Podman socket is running.

systemctl start --user podman.socket
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.

Debian

Stop and disable the Podman socket.

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

MicroOS

Stop the Podman socket.

sudo systemctl stop podman.socket

Open a transactional-update shell.

sudo transactional-update shell

Disable the Podman socket.

systemctl disable podman.socket

Exit the transactional-update shell.

exit

Reboot to apply changes.

sudo reboot

Errors

RunRoot Path

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

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}