From 6d44368f3086cbafd8aa74f2faa9473ebe2bafad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C4=83t=C4=83lin=20Emil=20Fetoiu?= Date: Mon, 12 Aug 2024 14:01:09 -0700 Subject: [PATCH 1/3] Doc updates about resolving .local names (#1999) * update docs about resolving .local names * add notfound instruction * update * Add more context and some formatting * add build number --------- Co-authored-by: Catalin-Emil Fetoiu Co-authored-by: Matt Wojciakowski --- WSL/troubleshooting.md | 54 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/WSL/troubleshooting.md b/WSL/troubleshooting.md index b2ec5a4a..b357b758 100644 --- a/WSL/troubleshooting.md +++ b/WSL/troubleshooting.md @@ -1,7 +1,7 @@ --- title: Troubleshooting Windows Subsystem for Linux description: Provides detailed information about common errors and issues people run into while running Linux on the Windows Subsystem for Linux. -ms.date: 02/22/2024 +ms.date: 08/08/2024 ms.topic: article --- @@ -296,7 +296,6 @@ When using Mirrored networking mode (the experimental `networkingMode` set to `m - UDP port 68 (DHCP) - TCP port 135 (DCE endpoint resolution) -- UDP port 5353 (mDNS) - TCP port 1900 (UPnP) - TCP port 2869 (SSDP) - TCP port 5004 (RTP) @@ -331,6 +330,57 @@ It is recommended to stop the Network Manager service for WSL networking to be c sudo systemctl disable network-manager.service ``` +### Resolve .local names in WSL + +To resolve hostnames to IP addresses within a local network without the need for a conventional DNS server, .local names are often used. This is achieved through the mDNS (Multicast DNS) protocol, which relies on multicast traffic to function. + +**networkingMode set to NAT:** + +Currently, this feature is not supported when DNS tunneling is enabled. To enable the resolution of .local names, we recommend the following solutions: + +- Disable DNS tunneling. +- Use mirrored networking mode. + +**networkingMode set to Mirrored:** + +Note: You need to be on WSL build 2.3.17 or higher in order to have the functionality below. + +Since Mirrored mode supports multicast traffic, the mDNS (Multicast DNS) protocol can be used to resolve .local names. Linux must be configured to support mDNS, as it does not do so by default. One way to configure it is using the following these two steps: + +1) Install the "libnss-mdns" package + +```Bash +sudo apt-get install libnss-mdns +``` + +*The "libnss-mdns" package is a plugin for the GNU Name Service Switch (NSS) functionality of the GNU C Library (glibc) that provides hostname resolution via Multicast DNS (mDNS). This package effectively allows common Unix/Linux programs to resolve names in the ad-hoc mDNS domain .local. + +2) Configure the `/etc/nsswitch.conf` file to enable the "mdns_minimal" setting in the "hosts" section. Example content of the file: + +```Bash +cat /etc/nsswitch.conf +# /etc/nsswitch.conf +# +# Example configuration of GNU Name Service Switch functionality. +# If you have the `glibc-doc-reference' and `info' packages installed, try: +# `info libc "Name Service Switch"' for information about this file. + +passwd: compat systemd +group: compat systemd +shadow: compat +gshadow: files + +hosts: files mdns_minimal [NOTFOUND=return] dns +networks: files + +protocols: db files +services: db files +ethers: db files +rpc: db files + +netgroup: nis +``` + ### DNS suffixes in WSL Depending on the configurations in the .wslconfig file, WSL will have the following behavior wrt DNS suffixes: From adc8b797e0a2456573b402406ce5a2baa5bbd66c Mon Sep 17 00:00:00 2001 From: Carlos Rafael Ramirez Date: Wed, 14 Aug 2024 20:32:00 +0200 Subject: [PATCH 2/3] Update basic-commands.md (typo teh to the) (#2006) --- WSL/basic-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/WSL/basic-commands.md b/WSL/basic-commands.md index d98a3401..6039af0f 100644 --- a/WSL/basic-commands.md +++ b/WSL/basic-commands.md @@ -169,7 +169,7 @@ To terminate the specified distribution, or stop it from running, replace ` Date: Thu, 15 Aug 2024 02:45:44 +0800 Subject: [PATCH 3/3] Prevent content from being translated in other language documents that should not be translated (#2000) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For example in Simplified Chinese documentation the value ”true“ is translated as ”是“ actually it should not be translated https://learn.microsoft.com/zh-cn/windows/wsl/wsl-config#main-wsl-settings --- WSL/wsl-config.md | 88 +++++++++++++++++++++++------------------------ 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/WSL/wsl-config.md b/WSL/wsl-config.md index ce69f228..c2a8805d 100644 --- a/WSL/wsl-config.md +++ b/WSL/wsl-config.md @@ -67,10 +67,10 @@ wsl.conf section label: `[automount]` | key | value | default | notes | |:-----------|:---------|:--------|:------| -| enabled | boolean | true | `true` causes fixed drives (i.e `C:/` or `D:/`) to be automatically mounted with DrvFs under `/mnt`. `false` means drives won't be mounted automatically, but you could still mount them manually or via `fstab`. | -| mountFsTab | boolean | true | `true` sets `/etc/fstab` to be processed on WSL start. /etc/fstab is a file where you can declare other filesystems, like an SMB share. Thus, you can mount these filesystems automatically in WSL on start up. | -| root| string | `/mnt/` | Sets the directory where fixed drives will be automatically mounted. By default this is set to `/mnt/`, so your Windows file system C-drive is mounted to `/mnt/c/`. If you change `/mnt/` to `/windir/`, you should expect to see your fixed C-drive mounted to `/windir/c`.| -| options | comma-separated list of values, such as uid, gid, etc, see automount options below | empty string | The automount option values are listed below and are appended to the default DrvFs mount options string. **Only DrvFs-specific options can be specified.**| +| `enabled` | boolean | `true` | `true` causes fixed drives (i.e `C:/` or `D:/`) to be automatically mounted with DrvFs under `/mnt`. `false` means drives won't be mounted automatically, but you could still mount them manually or via `fstab`. | +| `mountFsTab` | boolean | `true` | `true` sets `/etc/fstab` to be processed on WSL start. /etc/fstab is a file where you can declare other filesystems, like an SMB share. Thus, you can mount these filesystems automatically in WSL on start up. | +| `root`| string | `/mnt/` | Sets the directory where fixed drives will be automatically mounted. By default this is set to `/mnt/`, so your Windows file system C-drive is mounted to `/mnt/c/`. If you change `/mnt/` to `/windir/`, you should expect to see your fixed C-drive mounted to `/windir/c`.| +| `options` | comma-separated list of values, such as uid, gid, etc, see automount options below | empty string | The automount option values are listed below and are appended to the default DrvFs mount options string. **Only DrvFs-specific options can be specified.**| The automount options are applied as the mount options for all automatically mounted drives. To change the options for a specific drive only, use the `/etc/fstab` file instead. Options that the mount binary would normally parse into a flag are not supported. If you want to explicitly specify those options, you must include every drive for which you want to do so in `/etc/fstab`. @@ -80,13 +80,13 @@ Setting different mount options for Windows drives (DrvFs) can control how file | Key | Description | Default | |:----|:----|:----| -|uid| The User ID used for the owner of all files | The default User ID of your WSL distro (on first installation this defaults to 1000) -|gid| The Group ID used for the owner of all files | The default group ID of your WSL distro (on first installation this defaults to 1000) -|umask | An octal mask of permissions to exclude for all files and directories | 022 -|fmask | An octal mask of permissions to exclude for all files | 000 -|dmask | An octal mask of permissions to exclude for all directories | 000 -|metadata | Whether metadata is added to Windows files to support Linux system permissions | disabled -|case | Determines directories treated as case sensitive and whether new directories created with WSL will have the flag set. See [case sensitivity](./case-sensitivity.md) for a detailed explanation of the options. Options include `off`, `dir`, or `force`. | `off` +| `uid` | The User ID used for the owner of all files | The default User ID of your WSL distro (on first installation this defaults to 1000) +| `gid` | The Group ID used for the owner of all files | The default group ID of your WSL distro (on first installation this defaults to 1000) +| `umask` | An octal mask of permissions to exclude for all files and directories | `022` +| `fmask` | An octal mask of permissions to exclude for all files | `000` +| `dmask` | An octal mask of permissions to exclude for all directories | `000` +| `metadata` | Whether metadata is added to Windows files to support Linux system permissions | `disabled` +| `case` | Determines directories treated as case sensitive and whether new directories created with WSL will have the flag set. See [case sensitivity](./case-sensitivity.md) for a detailed explanation of the options. Options include `off`, `dir`, or `force`. | `off` By default, WSL sets the uid and gid to the value of the default user. For example, in Ubuntu, the default user is uid=1000, gid=1000. If this value is used to specify a different gid or uid option, the default user value will be overwritten. Otherwise, the default value will always be appended. @@ -105,9 +105,9 @@ wsl.conf section label: `[network]` | key | value | default | notes| |:----|:----|:----|:----| -| generateHosts | boolean | `true` | `true` sets WSL to generate `/etc/hosts`. The `hosts` file contains a static map of hostnames corresponding IP address. | -| generateResolvConf | boolean | `true` | `true` sets WSL to generate `/etc/resolv.conf`. The `resolv.conf` contains a DNS list that are capable of resolving a given hostname to its IP address. | -| hostname | string | Windows hostname | Sets hostname to be used for WSL distribution. | +| `generateHosts` | boolean | `true` | `true` sets WSL to generate `/etc/hosts`. The `hosts` file contains a static map of hostnames corresponding IP address. | +| `generateResolvConf` | boolean | `true` | `true` sets WSL to generate `/etc/resolv.conf`. The `resolv.conf` contains a DNS list that are capable of resolving a given hostname to its IP address. | +| `hostname` | string | Windows hostname | Sets hostname to be used for WSL distribution. | ### Interop settings @@ -117,8 +117,8 @@ These options are available in Insider Build 17713 and later. | key | value | default | notes| |:----|:----|:----|:----| -| enabled | boolean | `true` | Setting this key will determine whether WSL will support launching Windows processes. | -| appendWindowsPath | boolean | `true` | Setting this key will determine whether WSL will add Windows path elements to the $PATH environment variable. | +| `enabled` | boolean | `true` | Setting this key will determine whether WSL will support launching Windows processes. | +| `appendWindowsPath` | boolean | `true` | Setting this key will determine whether WSL will add Windows path elements to the $PATH environment variable. | ### User settings @@ -128,7 +128,7 @@ These options are available in Build 18980 and later. | key | value | default | notes| |:----|:----|:----|:----| -| default | string | The initial username created on first run | Setting this key specifies which user to run as when first starting a WSL session. | +| `default` | string | The initial username created on first run | Setting this key specifies which user to run as when first starting a WSL session. | ### Boot settings @@ -138,7 +138,7 @@ wsl.conf section label: `[boot]` | key | value | default | notes| |:----|:----|:----|:----| -| command | string | "" | A string of the command that you would like to run when the WSL instance starts. This command is run as the root user. e.g: `service docker start`.| +| `command` | string | "" | A string of the command that you would like to run when the WSL instance starts. This command is run as the root user. e.g: `service docker start`.| ### Example wsl.conf file @@ -208,25 +208,25 @@ This file can contain the following options that affect the VM that powers any W | key | value | default | notes| |:----|:----|:----|:----| -| kernel | path | The Microsoft built kernel provided inbox | An absolute Windows path to a custom Linux kernel. | -| memory | size | 50% of total memory on Windows | How much memory to assign to the WSL 2 VM. | -| processors | number | The same number of logical processors on Windows | How many logical processors to assign to the WSL 2 VM. | -| localhostForwarding | boolean | `true` | Boolean specifying if ports bound to wildcard or localhost in the WSL 2 VM should be connectable from the host via `localhost:port`. | -| kernelCommandLine | string | Blank | Additional kernel command line arguments. | -| safeMode | boolean | `false` | Run WSL in "Safe Mode" which disables many features and is intended to be used to recover distributions that are in bad states. Only available for Windows 11 and WSL version 0.66.2+. | -| 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.| -| 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 | boolean | 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** | boolean | 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** | boolean | true | Changes how DNS requests are proxied from WSL to Windows | -| autoProxy* | boolean | true | Enforces WSL to use Windows’ HTTP proxy information | -| defaultVhdSize | size | `1TB` | Set the Virtual Hard Disk (VHD) size that stores the Linux distribution (for example, Ubuntu) file system. Can be used to limit the maximum size that a distribution file system is allowed to take up. | +| `kernel` | path | The Microsoft built kernel provided inbox | An absolute Windows path to a custom Linux kernel. | +| `memory` | size | 50% of total memory on Windows | How much memory to assign to the WSL 2 VM. | +| `processors` | number | The same number of logical processors on Windows | How many logical processors to assign to the WSL 2 VM. | +| `localhostForwarding` | boolean | `true` | Boolean specifying if ports bound to wildcard or localhost in the WSL 2 VM should be connectable from the host via `localhost:port`. | +| `kernelCommandLine` | string | Blank | Additional kernel command line arguments. | +| `safeMode` | boolean | `false` | Run WSL in "Safe Mode" which disables many features and is intended to be used to recover distributions that are in bad states. Only available for Windows 11 and WSL version 0.66.2+. | +| `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.| +| `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` | boolean | `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`** | boolean | `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`** | boolean | `true` | Changes how DNS requests are proxied from WSL to Windows | +| `autoProxy`* | boolean | `true` | Enforces WSL to use Windows’ HTTP proxy information | +| `defaultVhdSize` | size | `1099511627776` (1TB) | Set the Virtual Hard Disk (VHD) size that stores the Linux distribution (for example, Ubuntu) file system. Can be used to limit the maximum size that a distribution file system is allowed to take up. | Entries with the `path` value must be Windows paths with escaped backslashes, e.g: `C:\\Temp\\myCustomKernel` @@ -244,14 +244,14 @@ These settings are opt-in previews of experimental features that we aim to make | Setting name | Value | Default | Notes | |:----|:----|:----|:----| -|`autoMemoryReclaim`| string | disabled | Automatically releases cached memory after detecting idle CPU usage. Set to `gradual` for slow release, and `dropcache` for instant release of cached memory. | -|`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. | +|`autoMemoryReclaim`| string | `disabled` | Automatically releases cached memory after detecting idle CPU usage. Set to `gradual` for slow release, and `dropcache` for instant release of cached memory. | +|`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. | +|`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. | Entries with an * after the value type are only available on Windows 11.