Rootless Podman-in-Podman Setup Guide for Arch Linux

Disclaimer: This guide was generated by Claude Sonnet 4.

This guide covers setting up rootless Podman with support for running Podman containers inside Podman containers (Podman-in-Podman) on Arch Linux.

Prerequisites

Ensure you have a non-root user with sudo privileges and that your user has proper subuid/subgid mappings configured.

Step 1: Install Required Packages

Install Podman and its dependencies:

sudo pacman -S podman fuse-overlayfs slirp4netns

Step 2: Enable User Lingering

Enable user lingering to allow your user session to persist:

sudo loginctl enable-linger $USER

Step 3: Configure Podman Storage

Create the Podman configuration directory:

mkdir -p ~/.config/containers

Create the storage configuration file at ~/.config/containers/storage.conf:

[storage]
driver = "overlay"
runroot = "/run/user/1000/containers"
graphroot = "/home/$USER/.local/share/containers/storage"

[storage.options]
additionalimagestores = [
]

[storage.options.overlay]
mount_program = "/usr/bin/fuse-overlayfs"
mountopt = "nodev,fsync=0"

Note: Replace $USER with your actual username in the graphroot path.

Step 4: Configure FUSE Kernel Module

Load the FUSE kernel module:

sudo modprobe fuse

Make the FUSE module load automatically on boot:

echo 'fuse' | sudo tee /etc/modules-load.d/fuse.conf

Step 5: Enable Podman User Service

Enable and start the Podman socket service for your user:

systemctl --user enable --now podman.socket

Step 6: Reboot (Recommended)

Reboot your system to ensure all changes take effect:

sudo reboot

Step 7: Test Rootless Podman

After reboot, test that basic rootless Podman works:

podman run --rm -it alpine

Step 8: Test Podman-in-Podman

Run Podman inside a Podman container using the --userns=keep-id flag:

podman run --rm -it --userns=keep-id quay.io/containers/podman:latest

Inside the nested container, you should now be able to run:

podman run --rm -it alpine

Alternative Approaches

Socket Mounting (Recommended for CI/CD)

For cases where you want to use the host Podman service from within a container:

podman run --rm -it \
  -v /run/user/$(id -u)/podman/podman.sock:/run/podman/podman.sock \
  -e CONTAINER_HOST=unix:///run/podman/podman.sock \
  quay.io/containers/podman:latest

Then use podman --remote inside the container.

Privileged Mode

If --userns=keep-id doesn't work, you can fall back to privileged mode:

podman run --rm -it --privileged quay.io/containers/podman:latest

Troubleshooting

Check Podman Configuration

Verify your Podman setup:

podman info

Look for:

rootless: true in the security section
Proper UID/GID mappings in the idMappings section
graphDriverName: overlay in the store section

Verify User Namespaces

Check your subuid/subgid configuration:

cat /etc/subuid
cat /etc/subgid

Your username should appear with a range like username:100000:65536.

Socket Service Issues

If the Podman socket isn't working:

systemctl --user status podman.socket
systemctl --user restart podman.socket

FUSE Issues

If you get FUSE-related errors:

lsmod | grep fuse
sudo modprobe fuse

Common Error Messages

"fuse: device not found": FUSE module not loaded (sudo modprobe fuse)
"insufficient UIDs or GIDs": User namespace mapping issue (check subuid/subgid)
"statfs podman.sock: no such file": Podman socket service not running (systemctl --user start podman.socket)

Notes

The --userns=keep-id flag preserves your user namespace mappings when running nested containers
This setup allows for true container isolation while maintaining rootless operation
For production use, consider the socket mounting approach for better security
Some container images may still have issues with nested user namespaces; test thoroughly with your specific use cases

scottzach1/pnp-arch.md