Skip to content
🎉 Launch sale:50% off everything over $22 — automatically applied at checkout· ends Aug 2Shop the sale →
DevOps AI ToolKit
Newsletter
All prompts
AI for Podman Difficulty: Advanced ClaudeChatGPT

Rootless Podman Networking Debug Prompt

Systematically diagnose rootless Podman network failures across pasta/slirp4netns, netavark bridges, published ports, and aardvark-dns name resolution.

Target user
Platform engineers debugging connectivity, port publishing, or DNS failures in rootless Podman
Difficulty
Advanced
Tools
Claude, ChatGPT

The prompt

You are a senior Linux networking engineer who knows rootless Podman networking is a different stack from rootful, not a restricted version of it. You know rootless containers on the default network have no bridge and use a userspace path — pasta by default on Podman 5.x, slirp4netns on older versions — that published ports go through rootlessport, that container-to-container DNS via aardvark-dns only works on a user-created network and not the default one, and that the container's network namespace is invisible to plain `ip addr` on the host without `podman unshare --rootless-netns`.

I will describe a rootless networking failure. Diagnose it methodically.

Steps:

1. **Classify the failure precisely**: separate outbound (container cannot reach the internet), inbound (host or LAN cannot reach a published port), lateral (container cannot reach another container), and resolution (names do not resolve but IPs work) — the four have almost no diagnostic overlap.
2. **Establish the network mode**: from `podman info` and `podman inspect`, determine whether the container is on the default rootless network via pasta/slirp4netns, a user-created netavark bridge, `--network=host`, or joined to a pod, and state what each mode makes possible and impossible.
3. **Test inside the namespace**: give the exact commands to look from the container's side — `podman exec` for basic reachability, and `podman unshare --rootless-netns ip addr`/`ss -lntp` to inspect the rootless network namespace from the host, since host-level `ip`/`ss` will not show it.
4. **Debug port publishing**: confirm the container process actually binds 0.0.0.0 and not 127.0.0.1 inside the container (the single most common false alarm), then check the `PublishPort`/`-p` mapping, then check for a port below 1024 without `net.ipv4.ip_unprivileged_port_start` lowered, then check the host firewall.
5. **Debug DNS**: if names fail but IPs work, check whether the containers share a user-created network (required for aardvark-dns name resolution), verify aardvark-dns is running, inspect `/etc/resolv.conf` inside the container, and consider `host.containers.internal` for reaching the host.
6. **Check lateral connectivity assumptions**: confirm whether the containers are actually on the same network or in the same pod, and note that pod members share a network namespace and therefore reach each other on `localhost` rather than by container name.
7. **Account for known rootless limits**: point out behaviors that are not bugs — the container's source IP as seen by the host differs from rootful, ICMP may need `net.ipv4.ping_group_range`, and some inbound scenarios simply require pasta options or a host-network container.
8. **Give a minimal reproduction and fix**: reduce to the smallest `podman run` that shows the problem, then give the fix as a config change with the equivalent Quadlet directive if the workload is systemd-managed.

Fill in:
- Symptom and exact error: [PASTE]
- Podman version and OS: [DESCRIBE]
- `podman inspect <ctr>` network section: [PASTE]
- Output of `podman network ls` and the run/Quadlet config: [PASTE]
- Is the failure outbound, inbound, lateral, or DNS: [PICK ONE]

Output as: (a) the ranked hypotheses with the one command that confirms or eliminates each, (b) the diagnosis with the evidence that supports it, and (c) the fix as both a `podman run` flag and the equivalent Quadlet directive.

Do not disable the firewall or switch to `--network=host` as a diagnostic shortcut on a shared host — both change the security posture and frequently mask the real cause rather than revealing it.

Run this prompt with AI

Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.

Why this prompt works

Rootless networking problems get misdiagnosed because engineers reach for rootful mental models and host-level tools that cannot see what they need to see. Running ss -lntp on the host and finding nothing feels like proof the container is not listening, when in fact the rootless network namespace is simply not visible from there. Putting podman unshare --rootless-netns into the diagnostic path early replaces a wrong conclusion with a real observation, which is usually where the investigation actually starts making progress.

The four-way classification in step one is doing more work than it looks like. Outbound, inbound, lateral, and resolution failures share almost no root causes: outbound points at pasta or slirp4netns, inbound at rootlessport and privileged ports, lateral at network membership or pod namespace sharing, and resolution at aardvark-dns and network type. Forcing the classification before any hypothesis prevents the scattershot debugging where someone changes the network driver, the firewall, and the published port together and then cannot say which one mattered.

The step-four ordering encodes hard-won triage sequence. The single most common “port publishing is broken” report is an application bound to 127.0.0.1 inside the container, where the mapping is perfect and nothing will ever arrive. Checking that before touching firewall rules or sysctls saves the majority of these investigations outright. And the explicit warning against --network=host as a fix matters because it works — it makes the symptom vanish — which is exactly what makes it such an effective way to ship a container with no network isolation and a problem still waiting underneath.

Related prompts

More Podman prompts & error guides

Browse every Podman prompt and troubleshooting guide in one place.

Free download · 368-page PDF

Reading prompts? Get all 500 in one free PDF

500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.

  • 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
  • Instant PDF download — yours free, forever
  • Plus one practical AI-workflow email a week (no spam)

Single opt-in · unsubscribe anytime · no spam.