2020-06-24·~6 mins read

Accessing an unpublished port of a running Docker container

docker

networking

A cargo ship full of containers leaving the port

You've just finally setup your Docker container and It’s up and running, but then when trying to access it from the host you realized that you didn't publish a port. Damn!

Well if it's not a problem you can just stop it and re-run it again by providing the -p flags you need and the problem is solved. But what if you ran some commands in the container since it started? You would need to repeat them again. Or what if you're in a situation where for some reason you cannot restart the container or you really don't want to?

In this post, I'm gonna show how different solutions could be applied depending on whether restarting the container is an option or not.

The version of Docker Engine I'm using in this post is the latest one at the time of writing that is 19.03.

How port mapping works

Let's first have a look at how port mapping works first, feel free to skip this section if you're already familiar with the topic.

By default Docker containers are completely isolated from the host, this means that also the network is isolated. Thus if you want to run for example a Redis container you won’t be able to use it from the host unless you’ll explicitly instruct the container to publish the port (port number 6379 in this case) and map it to one available port on the host.

One important thing to keep in mind is to understand the difference between an exposed port and a published one.

A port can be exposed either using the --expose flag when running docker run or by using the EXPOSE command in a Dockerfile. Exposing a port actually does nothing with regard to networking and it should be interpreted as a way of documenting the ports used by the container. Indeed it's a good practice in a Dockferfile to show what are the ports that are used by the container by exposing them. As an example, checkout the Dockerfile for Redis that exposes port 6379.

So if we run a container with Redis without mapping it to any port, we can see that we cannot reach it from the host even if in the Dockerfile it is marked as exposed. One thing to be noted is that a container’s port is not accessible by the host, but it is accessible by other containers running in the same network.

On the other hand, publishing a port maps that port on a container to another one on the host, and as you most probably know already this can be done using the -p. For example, we can either run Redis and map its port to the same one on the host or to another one:

Now that we know the difference between exposing and publishing a port, it worths knowing that Docker provides a -P flag. This flag simply publishes all the ports that are exposed and map them to a set of random ones:

In this case, for example, the container's port 6739 has been mapped to the host's port 32770.

When restarting the container is fine

If restarting the container is fine, then you have two possible scenarios:

1. losing the changes applied in the container is fine,
2. losing the changes applied in the container is not fine at all.

Well, the first case is a no brainer and you most probably didn't land into this post if that's the case. You'll just need to stop the container and run it again by providing the proper -p flag to map a local port to the target port of the container.

Committing the container

It could be the case that from the time you ran the container you already executed many commands and the idea of restarting the container and repeating them gives you the creeps. 😱

In this case, you can first commit the container so that the current state is saved into a new image:

Now you can just run a new container from the newly created image and provide the proper -p flag to map the port. You can now feel relieved again! 😌

Without restarting the container

As you may have guessed already, it's not possible to map a port on a running container and this is also mentioned in this ticket:

However, all is not lost! There's a tool named socat that makes it possible to access an unpublished port of a running container.

What is socat?

socat is a tool that establishes two bidirectional byte streams and transfers data between them and we'll see how we can leverage this mechanism to access an unpublished port of a running container.

socat has a very wide set of use cases, and I’d highly suggest you to have a look at its documentation page if you’re interested in knowing more.

The basic idea of socat is that it takes two addresses parameters and it links them so that what’s read in the first is written in the second and vice versa.

It is actually possible to change this default behavior such as read/write in one direction only, or even make the second address to write back to a third address, but this is out of the scope of this brief intro.

socat is very flexible and in this context, an address can be many different things such as a TCP connection, a UDP one, a file descriptor, a Unix socket, etc..

For example, we can use socat to listen from a TCP connection and write to stdout:

or vice versa write to stdin and send the bytes to a TCP connection:

Each address can optionally have different options attached and different addresses types have different options available. See the documentation to see the full list.

At this point, you probably guessed already that we’re going to use socat to forward the traffic from the host to the unmapped port of the target container. Let’s see how in the next section.

Using socat for forwarding the traffic

Let's say that your target container is running a web-server at port 80 and this is the unpublished port you wanna reach. We can run socat inside another container in the same network of the target one. By doing this we can instruct it to act as a proxy and to forward the traffic from a port of our choice that needs to be exposed, let's say 8080, to the port 80 of the target container that is accessible since it runs in the same network through another port of our choice in the socat container, let's say 1234.

Wait! What?! 🤯

It’s actually much easier than it sounds! And an image worths a thousand words!

Luckily for us, we don't even need to create a Dockerfile, but we can just use the alpine/socat image and run it with the correct command.

So let's create our target container that in this example will correspond to a very simple NGINX web-server that simply returns a plain text response when the root endpoint is curled:

As we can see, the container is listening at port 80, but we didn't map it to any port. In order to forward the traffic, the socat container needs to know the IP address of the target container:

As we can see the container is running at the address 172.17.0.3. Let's then finally run our socat container with the command below:

Now we can curl port 8080 and the request will be forwarded to the port 80 of the target container as we wanted:

Yeah! We made it! 🎉

However, as I anticipated, this works because both containers are running in the same network. In this example they're both running in the default bridge network:

If for example, the target container is running on a user-defined network, then we need to make the socat container run in the same one. Otherwise, the curl will just hang and eventually timeout.

Let's see this in practice by creating a network and making our target web-server container run in it:

In this case, we know that our target container is running in the network called sample-network since we created it. In case you don't you can always inspect the container and retrieve it with the same command mentioned above:

As you can see it returns a JSON with a key that corresponds to the network name.

Let's then create again our socat container, but this time by passing it the correct network to connect to:

We're now able again to curl the target container as shown before! 🎉

You can verify that curl won't work if you don't provide the --network sample-network flag to the port mapper.

Conclusions

After reviewing the difference between exposing and publishing a port we went through the different ways we could access an unpublished port depending on the needs. There are many different use cases where accessing an unpublished port is needed and I hope that you were able to solve yours and that you found socat an interesting tool to study further.

One scenario I didn’t cover in this post is how to achieve the same if the docker container is part of a docker-compose setup. But you could give it a try yourself as you should be able to easily address it by applying the same concepts outlined here.

If you found this post interesting then please share it with your friends or in your socials!