SSH connection failures between WSL2, VirtualBox, and Docker usually stem from network isolation or port forwarding misconfigurations. The primary cause is often that the WSL2 instance cannot reach the VirtualBox VM's internal IP, or the Docker container’s exposed ports are not correctly mapped to the host network interface. Verifying the virtual network adapter settings and ensuring correct NAT rules resolves most connectivity issues.
Understanding the Network Topology
To troubleshoot effectively, you must first understand how these three layers interact. WSL2 runs in a lightweight utility VM with its own virtual network switch. VirtualBox manages its own virtual machines, which typically sit on a separate virtual network interface (NAT or Bridged). Docker inside WSL2 uses the Linux bridge networking stack. When you attempt an SSH connection, traffic must traverse from the WSL2 kernel, through the VirtualBox network adapter, into the specific VM, and finally to the Docker container running within that VM. A common misconception is that WSL2 can directly access VirtualBox VMs via localhost. This is rarely true unless specific bridging configurations are applied. Instead, WSL2 sees the VirtualBox host machine as a remote server on the local network segment assigned by your physical router or VirtualBox’s internal DHCP server. Therefore, you need the actual IP address of the VirtualBox host, not the loopback address.Identifying the Correct IP Addresses
Start by determining the IP address of your VirtualBox host machine. Inside the VirtualBox VM, runip addr show or ifconfig to find the IP associated with the active network interface (usually eth0 or wlan0). Note this address carefully.
Next, check the IP address of your WSL2 instance. Open a WSL2 terminal and run hostname -I. This will give you the IP that WSL2 uses to communicate on the host network. If you are trying to connect *from* WSL2 *to* the VirtualBox VM, ensure that the VirtualBox host IP is reachable from the WSL2 IP. You can test this basic connectivity by running ping <VirtualBox_Host_IP> from within WSL2. If the ping fails, the issue is at the network layer, likely due to firewall rules or incorrect adapter binding.
Configuring VirtualBox Network Settings
The default NAT network in VirtualBox isolates the guest VM from the host machine in a way that makes external connections difficult. To allow WSL2 to connect to services inside the VM, you should configure port forwarding or switch to a Bridged Adapter. If you prefer keeping the NAT setup, you must add a port forwarding rule. In the VirtualBox manager, go to the VM settings, select Network, then Advanced, and look for Port Forwarding. Add a rule that maps a host port (e.g., 2222) to the guest port (22). However, this method often requires additional configuration on the Windows host side to route traffic correctly to WSL2. A more robust solution for development environments is using a Bridged Adapter. This assigns the VirtualBox VM an IP address on your local LAN, just like any other physical device. Ensure that your WSL2 instance and the VirtualBox VM are on the same subnet. Once bridged, you can SSH directly from WSL2 to the VM’s IP address using standard SSH commands.Checking Windows Firewall Rules
Even with correct network topology, Windows Defender Firewall may block incoming connections from WSL2. Since WSL2 appears as a separate network interface, Windows might classify it as a "Public" network, which has stricter inbound rules. Go to Windows Security > Firewall & network protection and ensure that the profile for the WSL2 interface allows file and printer sharing or custom inbound rules for SSH. You may also need to explicitly allow inbound traffic on port 22 for the specific network profile being used by the VirtualBox adapter.Docker Container Networking
Once you have established SSH connectivity to the VirtualBox host, you must ensure the Docker container is accessible. By default, Docker creates an isolated bridge network. If you are running a service inside Docker, you must expose the relevant ports. When starting your container, use the-p flag to map the container port to the host port. For example, docker run -p 8080:80 myimage exposes port 80 of the container as port 8080 on the VirtualBox host. After starting the container, verify that the port is listening by running netstat -tuln or ss -tuln inside the VirtualBox VM. Look for the port state listed as LISTEN.
If the port is not listening, check the Docker logs using docker logs <container_id>. Common errors include missing environment variables or configuration files that prevent the application from starting. Additionally, ensure that the application inside the container is binding to 0.0.0.0 rather than 127.0.0.1, as binding to localhost restricts access to only local connections within the container.
For deeper insights into managing space and images in this complex stack, you might find Reclaim Space of Pruned Images in Docker WSL useful for maintaining a healthy environment.
Diagnostic Steps for Persistent Failures
If the above steps do not resolve the issue, perform these diagnostic checks. First, try connecting from the Windows host itself to the VirtualBox VM using the host IP. If this works, the problem is isolated to WSL2. If it fails, the issue lies within VirtualBox or the VM’s internal configuration. Second, verify that the SSH daemon is running inside the VirtualBox VM. Runservice ssh status or systemctl status sshd. If it is inactive, start it with sudo service ssh start. Third, check if SELinux or AppArmor is blocking connections. Although less common in standard setups, security modules can sometimes interfere with Docker networking.
Finally, consider using Troubleshooting Docker on Ubuntu under WSL2 with Docker Desktop if you are switching to Docker Desktop, as it handles networking differently and may simplify the integration between WSL2 and external VMs.
Frequently Asked Questions
Why can't I ping the VirtualBox IP from WSL2?
This usually indicates that WSL2 and the VirtualBox VM are on different subnets or that the VirtualBox network adapter is set to NAT without proper bridging. Switching the VirtualBox network setting to Bridged Adapter often places both machines on the same local network, allowing successful pings.
Do I need to forward ports in VirtualBox if I use a Bridged Adapter?
No, if you use a Bridged Adapter, the VM acts as a direct participant on your LAN. You can connect to it directly using its assigned IP address and the standard SSH port (22) without needing manual port forwarding rules in VirtualBox settings.
How do I verify if Docker is exposing ports correctly?
Run docker ps to see the port mappings listed for your running containers. Then, inside the VirtualBox VM, use netstat -tuln | grep <port_number> to confirm that the port is actually listening and bound to the correct interface.
Can I use localhost to connect to Docker from WSL2?
Only if Docker Desktop is installed and configured to share the network namespace with WSL2. In a standard standalone Docker installation within WSL2, localhost refers to the WSL2 instance itself, not the VirtualBox host. You must use the VirtualBox host's IP address instead.
What if the SSH connection times out after authentication?
This is often caused by a firewall on the VirtualBox host blocking outbound traffic from the container or strict iptables rules. Check the firewall status inside the VM and ensure that the Docker bridge network is allowed to pass traffic. Restarting the Docker service can also reset stale network states.