Main > Live (#1976)

* Update wsl-config.md (#1949) * Add kernel requirement for connect-usb.md (#1950) * Update networking.md (#1962) Adding the OS requirements for networking features to make it clear when the features are available. * Doc updates for dnsTunneling and autoProxy (#1970) * dns and proxy doc updates * add dnsTunnelingIpAddress setting * mention generateHosts option * move bullet point * rephrase docker desktop point --------- Co-authored-by: Catalin-Emil Fetoiu <cfetoiu@microsoft.com> --------- Co-authored-by: Craig Loewen <crloewen@microsoft.com> Co-authored-by: Keith Horton <khorton@microsoft.com> Co-authored-by: Cătălin Emil Fetoiu <fetoiucatalinemil@gmail.com> Co-authored-by: Catalin-Emil Fetoiu <cfetoiu@microsoft.com>
MicrosoftDocs · Jul 2, 2024 · ec88118 · ec88118
1 parent a962daa
commit ec88118
Show file tree

Hide file tree

Showing 4 changed files with 20 additions and 11 deletions.
diff --git a/WSL/connect-usb.md b/WSL/connect-usb.md
@@ -1,7 +1,7 @@
 ---
 title: Connect USB devices
 description: Learn how to connect a USB device to your WSL 2 Linux distribution using usbipd-win.
-ms.date: 01/04/2024
+ms.date: 04/16/2024
 ms.topic: article
 ---
 
@@ -20,7 +20,7 @@ Setting up the USB/IP project on your Windows machine will enable common develop
 
 > [!NOTE]
 > To check your Windows version and build number, select **Windows logo key + R**, type **winver**, select **OK**. You can update to the latest Windows version by selecting **Start** > **Settings** > **Windows Update** > **[Check for updates](ms-settings:windowsupdate)**.
-> To check your Linux kernel version, open your Linux distribution and enter the command: `uname -a`. To manually update to the latest kernel, open PowerShell and enter the command: 'wsl --update`.
+> To check your Linux kernel version, open your Linux distribution and enter the command: `uname -a`. To manually update to the latest kernel, open PowerShell and enter the command: `wsl --update`.
 
 > [!IMPORTANT]
 > WSL now supports both Windows 10 and Windows 11 via the Microsoft Store, meaning that Windows 10 users now have access to the latest kernel versions without needing to compile from source. See [WSL in the Microsoft Store is now generally available on Windows 10 and 11](https://devblogs.microsoft.com/commandline/the-windows-subsystem-for-linux-in-the-microsoft-store-is-now-generally-available-on-windows-10-and-11/) for info on how to update to the Store-supported version of WSL. If you are unable to update to the Store-supported version of WSL and automatically receive kernel updates, see the [USBIPD-WIN project repo](https://github.com/dorssel/usbipd-win/wiki/WSL-support) for instructions on connecting USB devices to a Linux distribution running on WSL 2 by building your own USBIP enabled WSL 2 kernel.
@@ -29,6 +29,12 @@ Setting up the USB/IP project on your Windows machine will enable common develop
 
 Support for connecting USB devices is not natively available in WSL, so you will need to install the open-source usbipd-win project.
 
+**Kernel requirements**
+
+To use USBIPD with Windows Subsystem for Linux (WSL), you need to have a [Linux kernel version of 5.10.60.1 or higher](https://github.com/dorssel/usbipd-win/wiki/WSL-support/6befeedd4c8e2a49468e4b03532c9a20478f8677). If the installed kernel version is older than 5.10.60.1, then it can be updated by first shutting down any running instances of WSL with `wsl --shutdown`, then running the command: `wsl --update`.
+
+**Install USBIPD on WSL**
+
 1. Go to the [latest release page for the usbipd-win project](https://github.com/dorssel/usbipd-win/releases).
 2. Select the .msi file, which will download the installer. (You may get a warning asking you to confirm that you trust this download).
 3. Run the downloaded usbipd-win_x.msi installer file.

diff --git a/WSL/networking.md b/WSL/networking.md
@@ -74,7 +74,7 @@ Using `listenaddress=0.0.0.0` will listen on all [IPv4 ports](https://stackoverf
 
 ## Mirrored mode networking
 
-You can [set `networkingMode=mirrored` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-for-wslconfig) to enable mirrored mode networking. Enabling this changes WSL to an entirely new networking architecture which has the goal of 'mirroring' the network interfaces that you have on Windows into Linux, to add new networking features and improve compatibility.
+On machines running Windows 11 22H2 and higher you can [set `networkingMode=mirrored` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-for-wslconfig) to enable mirrored mode networking. Enabling this changes WSL to an entirely new networking architecture which has the goal of 'mirroring' the network interfaces that you have on Windows into Linux, to add new networking features and improve compatibility.
 
 Here are the current benefits to enabling this mode:
 
@@ -91,11 +91,11 @@ This new mode addresses networking issues seen with using a NAT (Network Address
 
 ## DNS Tunneling
 
-Setting [`dnsTunneling=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-for-wslconfig) has WSL use a virtualization feature to answer DNS requests from within WSL, instead of requesting them over a networking packet. This feature is aimed to improve compatibility with VPNs, and other complex networking set ups.
+On machines running Windows 11 22H2 and higher, setting [`dnsTunneling=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-for-wslconfig) has WSL use a virtualization feature to answer DNS requests from within WSL, instead of requesting them over a networking packet. This feature is aimed to improve compatibility with VPNs, and other complex networking set ups.
 
 ## Auto Proxy
 
-Setting [`autoProxy=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-for-wslconfig) enforces WSL to use Windows' HTTP proxy information. If you have a proxy already set up in Windows, enabling this feature will make that proxy be set automatically in WSL as well.
+On machines running Windows 11 22H2 and higher, setting [`autoProxy=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-for-wslconfig) enforces WSL to use Windows' HTTP proxy information. If you have a proxy already set up in Windows, enabling this feature will make that proxy be set automatically in WSL as well.
 
 ## WSL and firewall
 

diff --git a/WSL/troubleshooting.md b/WSL/troubleshooting.md
@@ -267,6 +267,8 @@ When enabled, the following apply to proxy settings on your Linux distributions:
 - The Linux environment variable, `NO_PROXY`, is set to bypass any HTTP/S proxies found in the Windows configuration targets.
 - Every environment variable, except `WSL_PAC_URL`, is set to both lower case and upper case. For example: `HTTP_PROXY` and `http_proxy`.
 
+There is a known issue caused by ZScaler configurations, where ZScaler repeatedly enables and disables Windows proxy configurations, leading to WSL repeatedly showing the "An Http proxy change has been detected on the host" notification.
+
 Learn more in the Command Line blog: [WSL September 2023 update](https://devblogs.microsoft.com/commandline/windows-subsystem-for-linux-september-2023-update/#autoproxy).
 
 ### Networking considerations with DNS tunneling
@@ -275,16 +277,16 @@ When WSL can’t connect to the internet, it might be because the DNS call to th
 
 DNS Tunneling can be configured using the `dnsTunneling` setting in the [experimental section of the WSL Configuration file](/windows/wsl/wsl-config#experimental-settings). When applying this setting, note these considerations:
 
-- Native Docker can have connectivity issues in WSL when DNS tunneling is enabled – if the network has a policy to block DNS traffic to: 8.8.8.8 
 - If you use a VPN with WSL, turn on DNS tunneling. Many VPNs use NRPT policies, which are only applied to WSL DNS queries when DNS tunneling is enabled.
 - The `/etc/resolv.conf` file in your Linux distribution has a 3 DNS servers maximum limitation, while Windows may use more than 3 DNS servers. Using DNS tunneling removes this limitation – all Windows DNS servers can now be used by Linux.
 - WSL will use Windows DNS suffixes in the following order (similar to the order used by the Windows DNS client): 
   1. Global DNS suffixes 
   2. Supplemental DNS suffixes 
   3. Per-interface DNS suffixes
   4. If DNS encryption (DoH, DoT) is enabled on Windows, encryption will be applied to DNS queries from WSL. If users want to enable DoH, DoT inside Linux, they need to disable DNS tunneling.
-- DNS queries from Docker containers (either Docker Desktop or native Docker running in WSL) will bypass DNS tunneling. DNS tunneling cannot be leveraged to apply host DNS settings and policies to Docker DNS traffic.
-- Docker Desktop has its own way (different from DNS tunneling) of applying host DNS settings and policies to DNS queries from Docker containers.
+- DNS queries from Docker containers managed by Docker Desktop will bypass DNS tunneling. Docker Desktop has its own way (different from DNS tunneling) of applying host DNS settings and policies to DNS queries from Docker containers.
+- In order for DNS tunneling to be succesfully enabled, the generateResolvConf option in the wsl.conf file should not be disabled.
+- When DNS tunneling is enabled, the generateHosts option in the wsl.conf file is ignored (the Windows DNS hosts file is not copied in the Linux /etc/hosts file). The policies in the Windows hosts file will be applied to DNS queries from Linux, without the need for the file to be copied in Linux.
 
 Learn more in the Command Line blog: [WSL September 2023 update](https://devblogs.microsoft.com/commandline/windows-subsystem-for-linux-september-2023-update/#dns-tunneling).
 

diff --git a/WSL/wsl-config.md b/WSL/wsl-config.md
@@ -217,15 +217,15 @@ This file can contain the following options that affect the VM that powers any W
 | swap | size | 25% of memory size on Windows rounded up to the nearest GB | How much swap space to add to the WSL 2 VM, 0 for no swap file. Swap storage is disk-based RAM used when memory demand exceeds limit on hardware device. |
 | swapFile | path | `%USERPROFILE%\AppData\Local\Temp\swap.vhdx` | An absolute Windows path to the swap virtual hard disk. |
 | pageReporting | boolean | `true` | Default `true` setting enables Windows to reclaim unused memory allocated to WSL 2 virtual machine. |
-| guiApplications | boolean* | `true` | Boolean to turn on or off support for GUI applications ([WSLg](https://github.com/microsoft/wslg)) in WSL. Only available for Windows 11.|
+| guiApplications | boolean | `true` | Boolean to turn on or off support for GUI applications ([WSLg](https://github.com/microsoft/wslg)) in WSL.|
 | debugConsole | boolean* | `false` | Boolean to turn on an output console Window that shows the contents of `dmesg` upon start of a WSL 2 distro instance. Only available for Windows 11.|
 | nestedVirtualization | boolean* | `true` | Boolean to turn on or off nested virtualization, enabling other nested VMs to run inside WSL 2. Only available for Windows 11.|
 | vmIdleTimeout | number* | `60000` | The number of milliseconds that a VM is idle, before it is shut down. Only available for Windows 11.|
 | dnsProxy | bool | true | Only applicable to networkingMode = NAT. Boolean to inform WSL to configure the DNS Server in Linux to the NAT on the host. Setting to false will mirror DNS servers from Windows to Linux. |
 | networkingMode** | string | NAT | If the value is `mirrored` then this turns on mirrored networking mode. Default or unrecognized strings result in NAT networking. |
 | firewall** | bool | true | Setting this to true allows the Windows Firewall rules, as well as rules specific to Hyper-V traffic, to filter WSL network traffic. |
-| dnsTunneling** | bool | false | Changes how DNS requests are proxied from WSL to Windows |
-| autoProxy* | bool | false | Enforces WSL to use Windows’ HTTP proxy information |
+| dnsTunneling** | bool | true | Changes how DNS requests are proxied from WSL to Windows |
+| autoProxy* | bool | true | Enforces WSL to use Windows’ HTTP proxy information |
 
 Entries with the `path` value must be Windows paths with escaped backslashes, e.g: `C:\\Temp\\myCustomKernel`
 
@@ -247,6 +247,7 @@ These settings are opt-in previews of experimental features that we aim to make
 |`sparseVhd`| bool | false | When set to true, any newly created VHD will be set to sparse automatically. |
 |`useWindowsDnsCache`**| bool | false | Only applicable when `wsl2.dnsTunneling` is set to true. When this option is set to false, DNS requests tunneled from Linux will bypass cached names within Windows to always put the requests on the wire. |
 |`bestEffortDnsParsing`**| bool | false | Only applicable when `wsl2.dnsTunneling` is set to true. When set to true, Windows will extract the question from the DNS request and attempt to resolve it, ignoring the unknown records. |
+|`dnsTunnelingIpAddress`**| string | 10.255.255.254 | Only applicable when `wsl2.dnsTunneling` is set to true. Specifies the nameserver that will be configured in the Linux resolv.conf file when DNS tunneling is enabled. |
 |`initialAutoProxyTimeout`*| string | 1000 | Only applicable when `wsl2.autoProxy` is set to true. Configures how long (in milliseconds) WSL will wait for retrieving HTTP proxy information when starting a WSL container. If proxy settings are resolved after this time, the WSL instance must be restarted to use the retrieved proxy settings. |
 |`ignoredPorts`**| string | null | Only applicable when `wsl2.networkingMode` is set to `mirrored`. Specifies which ports Linux applications can bind to, even if that port is used in Windows. This enables applications to listen on a port for traffic purely within Linux, so those applications are not blocked even when that port is used for other purposes on Windows. For example, WSL will allow binding to port 53 in Linux for Docker Desktop, as it is listening only to requests from within the Linux container. Should be formatted in a comma separated list, e.g: `3000,9000,9090` |
 |`hostAddressLoopback`**| bool | false | Only applicable when `wsl2.networkingMode` is set to `mirrored`. When set to `True`, will allow the Container to connect to the Host, or the Host to connect to the Container, by an IP address that's assigned to the Host. The `127.0.0.1` loopback address can always be used,this option allows for all additionally assigned local IP addresses to be used as well. Only IPv4 addresses assigned to the host are supported. |