How to use docker container port command to list port mappings

Introduction

In this lab, you will learn how to use the docker port command to inspect the port mappings of a running Docker container. We will start by launching an Nginx container with published ports, then explore how to list all published port mappings for the container.

You will also learn how to list specific published TCP and UDP port mappings, and understand the behavior when querying a non-existent UDP mapping. Finally, we will demonstrate how to list a specific published port mapping without explicitly specifying the protocol.

Skills Graph

Start a container with published ports

In this step, we will learn how to start a Docker container and publish its ports to the host machine. Publishing ports allows external access to services running inside the container.

First, let's pull the nginx image from Docker Hub. This image contains a simple web server that we can use for demonstration.

docker pull nginx

You should see output indicating that the image is being downloaded. Once the download is complete, you can verify that the image is available locally by running:

docker images

Now, we will start an nginx container and publish port 80 inside the container to port 8080 on the host machine. The -d flag runs the container in detached mode (in the background), the -p flag maps the ports, and nginx is the image name.

docker run -d -p 8080:80 nginx

The output will be the container ID. This means the container has started successfully and its internal port 80 is accessible via port 8080 on your LabEx VM.

To verify that the web server is running and accessible, you can use curl to access the published port on the host machine.

curl http://localhost:8080

You should see the default Nginx welcome page HTML output in your terminal. This confirms that the port mapping is working correctly and you can access the service running inside the container from the host.

List all published port mappings for the container

In this step, we will learn how to list the published port mappings for a running Docker container. This is useful for confirming which ports are exposed and how they are mapped to the host.

We can use the docker port command followed by the container ID or name to list all published port mappings for a specific container. First, let's get the container ID of the nginx container we started in the previous step.

docker ps -q --filter ancestor=nginx

This command will output the container ID. Copy this ID as we will use it in the next command.

Now, use the docker port command with the container ID to list the port mappings. Replace <container_id> with the actual ID you obtained.

docker port <container_id>

You should see output similar to 80/tcp -> 0.0.0.0:8080. This indicates that the container's internal port 80 (using TCP protocol) is mapped to port 8080 on all host interfaces (0.0.0.0).

This command is a quick way to see all the port mappings configured for a running container.

List a specific published TCP port mapping

In this step, we will refine our use of the docker port command to list a specific published port mapping, including the protocol. This is useful when a container exposes multiple ports with different protocols.

To list a specific published TCP port mapping, we append the container port and the protocol (/tcp) to the docker port command. First, get the container ID again if you don't have it handy.

docker ps -q --filter ancestor=nginx

Now, use the docker port command with the container ID and specify the internal port 80 with the TCP protocol. Replace <container_id> with your container ID.

docker port < container_id > 80/tcp

The output should be 0.0.0.0:8080. This specifically shows the host address and port that the container's internal TCP port 80 is mapped to. This is more precise than listing all ports if you only care about a particular mapping and protocol.

List a specific published UDP port mapping (expect error)

In this step, we will attempt to list a specific published UDP port mapping for our nginx container. Since Nginx typically only uses TCP for its web server, we expect this command to not find a UDP mapping and potentially return an error or no output. This demonstrates how to specify the protocol when querying port mappings and what happens when a mapping for that protocol doesn't exist.

First, get the container ID of your nginx container.

docker ps -q --filter ancestor=nginx

Now, use the docker port command with the container ID and specify the internal port 80 with the UDP protocol (/udp). Replace <container_id> with your container ID.

docker port < container_id > 80/udp

You should observe that this command produces no output or an error message. This is because the nginx container, as configured, does not expose port 80 using the UDP protocol. This highlights the importance of specifying the correct protocol when querying port mappings.

List a specific published port mapping without specifying protocol

In this step, we will learn how to list a specific published port mapping without explicitly specifying the protocol (TCP or UDP). When the protocol is omitted, docker port will list mappings for both TCP and UDP for the specified container port.

First, get the container ID of your nginx container.

docker ps -q --filter ancestor=nginx

Now, use the docker port command with the container ID and specify the internal port 80 without the protocol. Replace <container_id> with your container ID.

docker port < container_id > 80

Since our nginx container only has a TCP mapping for port 80, the output will be 80/tcp -> 0.0.0.0:8080. If the container had both TCP and UDP mappings for port 80, both would be listed. This is a convenient way to see all mappings for a particular internal port, regardless of the protocol.

Summary

In this lab, we learned how to start a Docker container and publish its internal ports to the host machine using the docker run -p command. We demonstrated this by running an Nginx container and mapping its internal port 80 to host port 8080, verifying accessibility with curl.

Subsequently, we explored the docker port command to list the published port mappings of a running container. We learned how to list all published ports and how to query specific TCP or UDP port mappings, understanding that querying a non-existent UDP mapping would result in an error. We also practiced listing a specific port mapping without explicitly specifying the protocol.