This guide was written by taking a laptop that had been reset to factory conditions. You may not need to do all of them depending on the starting state of your laptop
Enable Hyper-V
In BIOS make sure Hyper-V support is enabled
Make sure Hyper-V feature is turned on in Windows:
- Use search bar find 'Turn Windows features on or off'
- In the dialog that is displayed, turn on Hyper-V
Update Windows
Do Windows update to make sure you got the latest version
Install WSL2
If you haven't installed WSL2 before, in a Windows Command Prompt, run as Administrator, run 'wsl --install'. You will be required to reboot.
Update WSL2
Check WSL2 is up to date. Do this even if you just installed WSL2.
To do this, in a Windows Command Prompt, run as Administrator, run:
wsl --update
You may be required to reboot.
Install Ubuntu
If you haven't installed WSL2 before, visit the Windows app store and install Ubuntu version 20.04
Validate Connection Between WSL2 and Windows
Make sure you can connect from an Ubuntu shell in WSL2 to a process running in Windows by allowing stuff through the firewall.
First find a port running on Windows by running in a Windows command prompt
netstat -an | find "LISTENING"
Ensure you have telnet installed in Windows - if you don't use 'Turn Windows features on or off' to install 'Telnet Client'
Prove you can connect to the running port on Windows, by running the below in a Windows Command Prompt, replacing [port] with the listening port you found:
telnet localhost [port]
Run the following in a PowerShell Administrator console to open the Windows WSL network to calls from the Linux OS:
New-NetFirewallRule -DisplayName "_WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow
Find the ip address of your 'WSL' network in windows by in a Windows command prompt running 'ipconfig /all', and looking for the IP address assigned to the 'WSL' network
In an Ubuntu shell run the below, replacing [ipAddress] with the address you found above:
nc -v [ipAddress]
You should see a response saying the connection succeeded. If you do not then you either not opened the firewall, got the ip address wrong, or the specified port is listening anymore
Install Rancher Desktop
Download Rancher Desktop from https://rancherdesktop.io You need at least version 1.6.2.
Install Rancher Desktop, when prompted:
- Pick dockerd and moby as the containr runtime
- Pick the version of Kubernetes (K8s) that matches one that you regularly use
Run Rancher Desktop and use the File / Preferences menu item to hook Rancher Desktop up to WSL2.
Restart your machine
Start Rancher Desktop and wait for it to start
Validate Docker Availability in WSL2
Check that you can use docker commands in WSL. In a Ubuntu shell, run:
docker --version
to see that docker CLI is available. Run
docker ps
to show you can view docker processes running in Rancher Desktop
If you get a permission problem accessing the docker socket when you run the above then you may have to add some permissions. In which case do the following in an Ubuntu shell:
sudo addgrp docker
sudo adduser $USER docker
sudo chown root:docker /var/run/docker.sock
sudo chmod g+w /var/run/docker.sock
newgrp docker
Try the command again, and you should see the docker processes.
Validate host.docker.internal Works
You can check that host.docker.internal behaves the way you expect by following the steps below.
As per above, in a Windows command prompt, run the following to find a listening Windows port:
netstat -an | find "LISTENING"
In an Unbuntu shell run the following to get a container shell:
docker run -it busybox
In the container shell run the below, replacing [port] with the port you found
nc -v host.docker.internal [port]
If this doesn't work, it most likely because you rebooted and the Windows firewall is blocking access. To fix, run the following in a PowerShell, and retry afterwards.
New-NetFirewallRule -DisplayName "_WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow
Useful Links
If you have problems then consult FAQs at https://docs.rancherdesktop.io/faq/
WSL2 Related Network Problems
The WSL2 network is placed in the "Public" category by Microsoft (even though its an internal network), which block access. So by default WSL2 cannot access ports running in Windows.
In particular DNS doesn't work, so you may find that you can't for example run the following from an Ubuntu shell:
ping www.bbc.co.uk
To make things worse, the network is recreated after a reboot, so any firewall changes you add to allow traffic from WSL2 to Windows may not work following the reboot.
To get around this you need to run the following after every reboot in a Adminostrator Powershell:
New-NetFirewallRule -DisplayName "_WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow
Another issue that can occur is that subnet used by WSL2 comes from the 172.x.x.x range, and that conflicts with some routing that is handed out by the VPN client when you connect to some VPNs.
You most likely see this as an intermittent problem with Ubuntu being able to reach the Internet when you are not connected to the VPN, and that stops working as soon as you connect to the VPN.
Its intermittent because the problem only occurs if the IP address Microsoft assigns to the WSL network on reboot clashes with the subnet range used by the VPN. Sometimes it will, and sometimes it won't and there is no way to force WSL to use a particular 172.x.x.x subnet in Windows 10.
The easiest way to work around this is to add a dummy network interface into Windows that uses the 172.x.x.x subnet. If you do that, and reboot then WSL2 is forced of that network and picks an address in the 192.168.x.x range instead
Have a look at the comment from https://github.com/microsoft/WSL/issues/4467 from naruco on 31st March for details of what to do:
https://github.com/microsoft/WSL/issues/4467#issuecomment-810894433
Essentially though its the following in a Powershell run as Administrator, followed by a reboot:
New-VMSwitch -SwitchName “DummySwitch” -SwitchType Internal
New-NetIPAddress -IPAddress 172.16.0.1 -PrefixLength 12 -InterfaceAlias “vEthernet (DummySwitch)”
Its worth noting a lot of this is not a problem in Windows 11 as you can set up proper bridged networks for WSL2 there, so you can pick the ip address range and have a network that is not "Public"
