Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท Networking

Publishing Ports and Name Resolution

Learn how podman run -p maps host ports to containers, how to bind to one address, use random ports, and how containers find each other by name, alias and host.containers.internal.

A container's network is private. Nothing outside can reach a server running inside it until you publish a port, which asks Podman to forward traffic from a port on the host to a port in the container. The reverse direction matters just as much: containers need to find each other, either by IP or, more conveniently, by name.

This lesson covers the -p syntax in full, the traps around binding addresses and privileged ports, and every way a container can resolve a name.

The -p syntax

Terminal
podman run -d -p 8080:80 docker.io/library/nginx:stable

The general shape is [host_ip:][host_port:]container_port[/protocol]:

Form Meaning
-p 8080:80 Host port 8080 forwards to container port 80 (TCP)
-p 127.0.0.1:8080:80 Only reachable from the host itself
-p 80 Random free host port forwards to container port 80
-p 5353:53/udp A UDP port
-p 8000-8010:8000-8010 A range of ports
-P Publish every port the image declares with EXPOSE, on random host ports

Look up what was assigned:

Terminal
podman port web
podman port web 80/tcp

podman ps shows the same mapping in its PORTS column.

Binding to one address

Without a host IP, the port listens on all host addresses (0.0.0.0), so a laptop on a coffee-shop network exposes the service to everyone there. For development, prefer 127.0.0.1:

Terminal
podman run -d --name db -p 127.0.0.1:5432:5432 docker.io/library/postgres:17

EXPOSE in a Containerfile is documentation only. It does not publish anything by itself; it only tells -P which ports to map.

Parsing a port mapping

The stand-in below parses -p values into their parts, the way you do when reading someone else's command line. It is a simplified model without IPv6 brackets.

Python Parse -p mappings (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.

Port conflicts

Two containers cannot publish the same host port on the same address. Podman reports the failure when you start the second one. The subtle part: 0.0.0.0:8080 conflicts with 127.0.0.1:8080 because the wildcard already covers it, while 127.0.0.1:8080 and 192.168.1.5:8080 can coexist.

Python Find clashing bindings (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.

Rootless and low ports

A rootless container runs without special privileges, and Linux normally reserves ports below 1024 for root. -p 80:80 therefore fails for a normal user with a "permission denied" style error. You have three choices:

  • Publish a high port (-p 8080:80) and put a reverse proxy in front if you need port 80.
  • Lower the limit once for the whole machine: sudo sysctl net.ipv4.ip_unprivileged_port_start=80, and persist it in a file under /etc/sysctl.d/.
  • Run the container as root (not recommended unless you need it).

The next lessons cover how rootless networking forwards traffic; see Rootless Networking with pasta.

How containers find each other

Once containers share a network you have four ways to reach one from another.

1. By container name (user-defined networks).

Terminal
podman network create appnet
podman run -d --name db --network appnet docker.io/library/postgres:17
podman run --rm --network appnet docker.io/library/alpine:3 ping -c1 db

2. By alias. Give one container several names with --network-alias:

Terminal
podman run -d --name db --network appnet --network-alias database --network-alias pg docker.io/library/postgres:17

3. By the host's name. From inside any container, host.containers.internal resolves to the host, so a container can call a service you run directly on your machine. Podman writes it into the container's /etc/hosts.

4. By pod localhost. Containers in the same pod share one network namespace, so they reach each other on localhost and different ports. A pod is Podman's way to group containers that must work as one unit.

Extra DNS control is available per container: --dns 1.1.1.1, --dns-search example.test, --add-host intranet:10.0.0.7 (adds an /etc/hosts line).

On the default podman network there is no name resolution between containers. If ping db says "bad address", create a network with podman network create and attach both containers to it.

Other network modes

--network accepts more than a network name:

  • host: share the host's network stack. No isolation and no -p needed; ports clash with host services. Rootless host mode works but has the host's privilege limits.
  • none: only a loopback interface.
  • container:NAME: join another container's network namespace, which is what pods do under the hood.
  • bridge, pasta, slirp4netns: pick the rootless/default mechanism explicitly.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does podman run -p 127.0.0.1:8080:80 do?

    The first field is the host address, then host port, then container port. 127.0.0.1 limits access to the local machine.
  2. 2. Does EXPOSE 80 in a Containerfile publish port 80 to the host?

    EXPOSE is metadata. -P publishes the exposed ports on random host ports; plain EXPOSE publishes nothing.
  3. 3. Which name always resolves to the host from inside a Podman container?

    Podman adds host.containers.internal to the container's /etc/hosts. localhost is the container itself.
  4. 4. Why does -p 80:80 fail for a normal rootless user by default?

    net.ipv4.ip_unprivileged_port_start defaults to 1024, so unprivileged users cannot bind lower ports.

Summary

  • -p [ip:][host_port:]container_port[/proto] publishes a port; bind to 127.0.0.1 when only you need it.
  • -P publishes the ports declared with EXPOSE on random host ports; podman port shows the result.
  • Two bindings clash when the port and protocol match and the addresses are equal or one is 0.0.0.0.
  • Rootless users cannot bind ports below 1024 unless the sysctl limit is lowered.
  • Containers find each other by name on user-defined networks, by alias, through host.containers.internal for the host, or on localhost inside a pod.

Next: Rootless Networking with pasta