Implementing Rootless Containers with Podman: User Namespaces and API Access

The Rootless Challenge: Running Containers Without Root

Running containers as the root user creates a significant security risk: if a process escapes the container, it possesses full administrative privileges on the host. Podman solves this by using rootless mode, allowing a standard user to launch, manage, and stop containers without requiring sudo or a root-level daemon.

The primary takeaway for engineers is that rootless Podman relies on User Namespaces (userns). This kernel feature maps a range of IDs from the host to the container, making the container process believe it is root (UID 0) inside the namespace, while the host sees it as an unprivileged user.

The Mapping Mechanism: SubUIDs and SubGIDs

For rootless mode to function, the host OS must allocate a range of subordinate user IDs (subuids) and group IDs (subgids) to the user. These are defined in /etc/subuid and /etc/subgid.

A typical entry in these files looks like this: username:100000:65536. This tells the kernel that the user username is allowed to map 65,536 IDs starting from 100,000. When a container starts, Podman maps the container's root user to the host user's actual UID, and the rest of the container's users to this subordinate range.

Worked Configuration: Enabling the Podman API Socket

Many CI/CD tools and IDEs expect a Docker-compatible API socket. In rootless mode, you must start a user-level systemd unit to provide this socket, as there is no central root daemon.

Run these commands as the non-privileged user who will run the containers:

# Enable the podman API service for the current user
systemctl --user enable --now podman.socket

# Verify the socket is active and identify the path
podman system connection list

Expected Result: The output of connection list should show a Unix socket path, typically located at /run/user/<UID>/podman/podman.sock. You can now point tools like Docker Compose to this socket by setting the DOCKER_HOST environment variable.

Networking and Port Limitations

Because rootless containers cannot modify the host's network stack, Podman uses slirp4netns or pasta to emulate a network interface in user space. This introduces two critical constraints:

• Privileged Ports: By default, rootless users cannot bind containers to ports below 1024 (e.g., port 80 or 443). Attempting to do so will result in a "permission denied" error.
• Performance: User-space networking is slower than the root-level bridge because packets must pass through a translation layer.

To allow a rootless container to bind to a privileged port, you must modify the host's kernel parameters. Run this as root on the host:

# Allow unprivileged users to bind to ports starting at 80
sysctl -w net.ipv4.ip_unprivileged_port_start=80

Verification and Diagnostics

To verify that the user namespace mapping is active and correct, use the podman unshare command. This command executes a process in the same user namespace that Podman uses for containers.

# Run as the non-privileged user
podman unshare cat /proc/self/uid_map

The output will show the mapping (e.g., 0 1000 1), confirming that UID 0 inside the namespace maps to UID 1000 on the host.

Common Mistakes and Limitations

Issue	Cause	Resolution
Permission denied on volumes	Host directory permissions don't match mapped UIDs	Use podman unshare chown to fix directory ownership
Storage driver errors	OverlayFS requires root on older kernels	Install fuse-overlayfs to handle mounts in user space
sysctl failures	Containers trying to modify kernel parameters	Rootless containers cannot modify /proc/sys; these must be set on the host

Rollback Procedure

If you need to disable the user-level API socket and revert the port restriction:

1. Run systemctl --user disable --now podman.socket as the user.
2. Run sudo sysctl -w net.ipv4.ip_unprivileged_port_start=1024 as root to restore default port restrictions.