How to access a host ssh tunnel from within a docker container?

To access a host SSH tunnel from within a Docker container, you must explicitly bind the tunnel’s listening port to a network interface that the container can reach. By default, ssh -L binds to localhost (127.0.0.1), which is isolated per container. You must change this binding to 0.0.0.0 or the host’s specific LAN IP address on the host machine so that the Docker bridge network can route traffic to it.

Understanding Network Isolation

Docker containers operate in isolated network namespaces by default. When you create an SSH local port forwarding tunnel using the command ssh -L 8080:localhost:80 user@host, the SSH client listens on port 8080 only on the loopback interface of the host machine. This means only processes running directly on the host OS can connect to 127.0.0.1:8080. The Docker daemon creates a virtual bridge network (typically docker0) for containers. Traffic from inside a container destined for 127.0.0.1 refers to the container itself, not the host. Therefore, attempts to connect to the tunnel from within the container will fail with a connection refused error because the port is not exposed to the external network interfaces. To resolve this, the SSH tunnel must be configured to listen on an address accessible from the Docker bridge network.

Configuring the SSH Tunnel Binding

The primary solution involves modifying how the SSH tunnel binds its local port. Instead of allowing the default behavior, you should specify the IP address on which the tunnel should listen. On most Linux systems, you can achieve this by using the -L flag with a specific IP address instead of just the port number. Run the following command on your host machine:

ssh -L 0.0.0.0:8080:localhost:80 user@remote-server

By specifying 0.0.0.0, you instruct the SSH client to bind the local forwarding socket to all available network interfaces on the host. This includes the physical Ethernet/Wi-Fi interface and the Docker bridge interface. Once this is active, any process on the host, including those in Docker containers, can connect to 0.0.0.0:8080 (or simply the host's IP on port 8080). If you prefer tighter security, you can bind specifically to the IP address assigned to your Docker bridge gateway. You can find this IP by running ip addr show docker0 on the host. Suppose the gateway IP is 172.17.0.1; you would then use:

ssh -L 172.17.0.1:8080:localhost:80 user@remote-server

This restricts access to the tunnel only to clients connected to the Docker network, preventing accidental exposure to other networks if the host has multiple interfaces.

Connecting from the Container

Once the tunnel is established and bound correctly, connecting from within the Docker container is straightforward. However, you cannot use localhost as the destination address because that resolves to the container’s own loopback interface. Instead, you must use the host’s IP address that the tunnel is bound to. If you bound the tunnel to 0.0.0.0, you can use the host’s primary IP address or the Docker gateway IP. The Docker gateway IP is usually the first IP in the subnet of the container’s network. For the default bridge network, this is often 172.17.0.1. Inside the container, run your application or test connection using:

curl http://172.17.0.1:8080

Or, if you are using a database client:

mysql -h 172.17.0.1 -P 8080 -u user -p

It is crucial to verify that the host firewall allows incoming connections on the specified port if you are testing from outside the immediate host environment, although internal Docker-to-host communication typically bypasses standard iptables rules depending on your kernel version and configuration.

Alternative: Using Host Network Mode

For development environments where network complexity is a hindrance, Docker provides a host network mode. When you run a container with --network host, the container shares the host’s network namespace entirely. In this mode, localhost inside the container is identical to localhost on the host.

docker run --network host my-app

With this setup, you do not need to modify the SSH tunnel binding. The default ssh -L 8080:localhost:80 works perfectly because the container sees the same network interfaces as the host. However, this approach sacrifices network isolation. All ports opened by the container are immediately visible on the host, which may pose security risks in production environments. It is best suited for debugging or single-container deployments where simplicity outweighs isolation needs. If you encounter issues with connectivity, ensure that the SSH service on the remote server is actually reachable and that no intermediate firewalls are blocking the tunnel. For more details on troubleshooting SSH identification errors, you might refer to our guide on Troubleshooting kex_exchange_identification Error in Linux SSH Connection.

Frequently Asked Questions

Why does curl localhost:8080 fail inside the container?

This happens because localhost inside the container refers to the container’s own network stack, not the host’s. Since the SSH tunnel is bound to the host’s interface, the container cannot see it via the loopback address. You must use the host’s IP address or the Docker gateway IP instead.

Can I use the container name to connect to the tunnel?

No, the SSH tunnel is established on the host machine, not within a container. Container names are resolved via Docker’s internal DNS, which points to other containers. You must target the host’s IP address directly from within the container to reach the tunnel endpoint.

Is binding to 0.0.0.0 secure?

Binding to 0.0.0.0 exposes the tunnel port to all network interfaces on the host, including public ones if present. This increases the attack surface. It is safer to bind specifically to the Docker bridge IP (e.g., 172.17.0.1) or the host’s private LAN IP to restrict access to trusted networks only.

What if I don’t want to use host network mode?

If you avoid --network host for isolation reasons, configuring the SSH tunnel to bind to the Docker gateway IP is the recommended alternative. This maintains network separation while allowing controlled communication between the container and the host-side tunnel.

How do I check which IP the Docker bridge is using?

You can determine the Docker bridge IP by running ip addr show docker0 on the host machine. Look for the inet address associated with the docker0 interface, which is typically something like 172.17.0.1/16. Use this IP when configuring your SSH tunnel binding.