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 && reboot
Configure and enable Podman in rootful or rootless mode; refer to the corresponding section below.
Rootful Mode
Out the box, Podman can be run as root. Consider using rootless mode instead for improved security.
Enable the Podman socket using systemctl
.
sudo systemctl enable podman.socket
Verify the Podman socket is running.
sudo systemctl start podman.socket
sudo systemctl status podman.socket
The system can now be used to deploy containers.
Rootless Mode
Rootless mode requires some additional configuration, but allows system users without root privileges to run containers. This is recommended for improved system security, specifically in the event of a container breakout.
Install Dependencies
Install dependencies required for rootless operation: uidmap
, dbus-user-session
, fuse-overlayfs
, slirp4netns
. Also install MachineCTL via the systemd-container
package for shell access and management of the rootless user.
# Debian
sudo apt install uidmap dbus-user-session fuse-overlayfs slirp4netns systemd-container
# Microos
sudo transactional-update pkg install uidmap dbus-user-session fuse-overlayfs slirp4netns systemd-container && reboot
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
Grant IDs
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
.
sudo usermod --add-subuids 300000:65536 --add-subgids 300000:65536 podmanu
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.
Open the subuid
file.
sudo vim /etc/subuid
Add a definition for podmanu
.
podmanu:300000:65536
Open the subgid
file.
sudo vim /etc/subgid
Add a definition for podmanu
. matching the UID range.
podmanu:300000:65536
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
If the Podman socket was started as root, disable it so only the rootless socket persists.
The system is now ready to deploy rootless containers.
References
Podman. “Podman Documentation.” 2024. ↩︎
Podman. “Basic Setup and Use of Podman in a Rootless environment.” 2024. ↩︎