Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 37 ยท Networking

Troubleshooting Podman Networking

A practical checklist for Podman networking problems: containers that cannot resolve names, ports that do not answer, firewall rules, DNS failures, and the commands to inspect each layer.

Network problems feel mysterious because several layers are involved: the application, the container's namespace, the Podman network, the host's firewall and the outside world. The trick is to test one layer at a time, from the inside out. This lesson gives you a repeatable order of checks and the commands for each.

None of the commands below can run in the browser; the runnable examples are stand-ins that model the diagnosis logic so you can practice choosing the right next step.

The layered checklist

Inside to outside

App Is it listening on 0.0.0.0?
Container Right network and IP?
Publish Is the port mapped?
Host Firewall and port clashes.

Fix the first layer that fails.

1 / 2

1. Is the program listening on the right address?

A server that binds to 127.0.0.1 inside the container is unreachable from outside the container, even with -p. Check from inside:

Terminal
podman exec web ss -tlnp
podman exec web netstat -tlnp

You want 0.0.0.0:PORT (or [::]:PORT), not 127.0.0.1:PORT. If the image has no ss, try cat /proc/net/tcp or add a debug container to the same network namespace:

Terminal
podman run --rm -it --network container:web docker.io/nicolaka/netshoot

Using --network container:NAME shares the target's network stack, so every tool in the debug image sees exactly what the target sees. (That image is only an example of a tool bundle; any image with curl, dig and ip works.)

2. Is the container on the network you think?

Terminal
podman inspect web --format '{{json .NetworkSettings.Networks}}'
podman network inspect appnet
podman ps --format '{{.Names}} {{.Networks}}'

Two containers that cannot talk are very often on different networks. Remember that the default podman network has no DNS: see Podman Networks and Netavark.

3. Is the port published?

Terminal
podman port web
podman ps

An empty podman port means nothing is published. Then test from the host:

Terminal
curl -v http://127.0.0.1:8080/

"Connection refused" means nothing is listening on that host port (not published, wrong port, container stopped). "Connection reset" or an empty reply usually means the mapping exists but the application inside is not answering on the container port.

4. Is the host in the way?

  • Port already in use: ss -tlnp | grep :8080 on the host. Podman refuses to start a container whose host port is taken.
  • Firewall: Netavark writes its own rules for iptables or nftables. A firewalld reload can wipe them; run podman network reload --all to restore forwarding for running containers.
  • Rootless low ports: see Publishing Ports and Name Resolution.
  • SELinux rarely blocks networking but often blocks volume access, which looks like an app problem. Check ausearch -m avc -ts recent on Fedora and RHEL.

DNS problems

If a container cannot resolve names:

Terminal
podman exec web cat /etc/resolv.conf
podman exec web getent hosts db
podman exec web nslookup example.com

Common causes:

Symptom Likely cause Fix
Container name does not resolve Default network, or the names are on different networks Create a user-defined network and attach both
Public names fail, IPs work Host resolver is a stub (127.0.0.53) the container cannot reach Pass --dns 1.1.1.1, or fix containers.conf dns_servers
Name works once, then stops Container was removed and recreated with another IP Use names, never hard-coded IPs
Wrong name resolves Stale --add-host or alias podman inspect and review /etc/hosts

On networks with DNS, Aardvark answers names for containers on the same network only and forwards other lookups to the host's resolvers.

Practicing the diagnosis

The program below is a small rule engine: give it observed facts and it returns the next layer to look at. It only models the checklist; it cannot see your system.

Python Which layer is broken? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Name resolution rules

Name lookup depends on where the containers sit. This stand-in encodes the rules from the previous lessons so you can test a topology before building it.

Python Can A resolve B? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice db -> cache fails even though both are reachable through web: DNS is scoped to a shared network, and containers do not route through each other.

Useful commands at a glance

Terminal
podman logs -f web                     # application output
podman exec -it web sh                 # a shell inside
podman network inspect NET             # subnet, DNS, containers
podman network reload --all            # rebuild firewall rules
podman unshare --rootless-netns ss -tlnp   # rootless: sockets in the network namespace
podman info --format '{{.Host.NetworkBackend}}'   # netavark

podman unshare --rootless-netns runs a command inside the rootless network namespace, where you can see the bridge, Aardvark DNS and port forwards that rootless networks use. It is the rootless equivalent of looking at the host's own network.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A server inside a container binds to 127.0.0.1:8000 and you run with -p 8000:8000. What happens from the host?

    Forwarded traffic arrives on the container's network interface, not on its loopback, so the app must listen on 0.0.0.0.
  2. 2. What does podman network reload --all fix?

    It reapplies Netavark's rules, which a firewalld reload may have removed.
  3. 3. How can a debug image see exactly the same network stack as container web?

    container:NAME joins the target's network namespace, so tools see its interfaces and sockets.
  4. 4. Container db is reachable by IP but not by name on the default network. Why?

    Only user-defined networks have Aardvark DNS enabled by default.

Summary

  • Diagnose from the inside out: app listening address, container network, port publishing, host firewall and port clashes.
  • Bind servers to 0.0.0.0 inside containers.
  • --network container:NAME is the best way to debug with a toolbox image.
  • DNS names work only between containers that share a network with DNS enabled.
  • podman network reload --all restores rules after a firewall reload; podman unshare --rootless-netns shows the rootless namespace.

Next: Running Compose Files with Podman