Merge main > live (#1919)

* Fixing small formatting and writing errors. (#1863) * Fix broken code block and bookmark link (#1866) * Fix broken code block * Update broken wslconfig bookmark * Update install-on-server.md (#1871) Fix indent and numbering for better readability. * Fix punctuation errors (#1876) * small improvements in troubleshooting.md (#1877) Some small formatting improvements. Also added the command to restart the hns service. * Fix a few typos (#1879) Co-authored-by: Matt Wojciakowski <mattwoj@microsoft.com> * Updated guide to fix an issue because of a wrong command (#1884) * Update wsl-containers.md Running Dev Containers: **Open Folder in Container...** when using this guide is not / no longer correct, as most readers will already have opened the folder while connected to WSL based on the steps provided above. We need to use **Dev Containers: Reopen in Container** or it will fail to create the .devcontainer folder and devcontainer.json and give a (unfortunately not very clear) error message. See also: https://code.visualstudio.com/docs/devcontainers/containers#_open-a-wsl-2-folder-in-a-container-on-windows - Use the Dev Containers: Reopen in Container command from a folder already opened using the WSL extension. - Select Dev Containers: Open Folder in Container... from the Command Palette (F1) and choose a WSL folder using the local \\wsl$ share (from the Windows side). * Update wsl-containers.md --------- Co-authored-by: Matt Wojciakowski <mattwoj@microsoft.com> * Update faq.yml -- tiny grammar change (#1885) * Update faq.yml -- tiny grammar change 'changes to locale to' -> 'changes the locale to' * Update basic-commands.md 'If you running WSL' -> 'If you run WSL' * Update basic-commands.md * rephrase a long sentence * swap order of two sentences to make example of command closer to the description of the command example of command: `wsl --set-default-version 2` * Update basic-commands.md Replace wsl -u <Username>`, `wsl --user <Username> with wsl --user <Username> `wsl -u <Username>` and `wsl --user <Username>` are equivalent. Both commands are correct for the section of the documentation, but the display of the commands in the documentation was incorrect due to the stray ticks and comma. * Update gui-apps.md to simplify commits. (#1880) * Update gui-apps.md If we are already referencing apt, why not just use apt to install google chrome? * Update gui-apps.md forgot --fix-missing * Add a note to explain the command flags and path --------- Co-authored-by: Matt Wojciakowski <mattwoj@microsoft.com> * Fix anchor warning * Updated docs for usbipd-win updates (#1870) * Updated docs for usbipd-win updates * Update url to latest Co-authored-by: Frans van Dorsselaer <17404029+dorssel@users.noreply.github.com> * Fixes based on feedback Thank you @dorssel ! * Remove admin requirement Co-authored-by: Frans van Dorsselaer <17404029+dorssel@users.noreply.github.com> * Remove x86 support Co-authored-by: Frans van Dorsselaer <17404029+dorssel@users.noreply.github.com> --------- Co-authored-by: Matt Wojciakowski <mattwoj@microsoft.com> Co-authored-by: Frans van Dorsselaer <17404029+dorssel@users.noreply.github.com> * Moving experimental settings to the experimental section (#1901) * Moving experimental settings to the experimental section Some networking config settings are still experimental. Moving those to the experimental section of the document so customers know how to use these settings. * Added code ticks to new setting entries * Update wsl-config.md fixing settings which are no longer experimental, but the text still referred to them as experimental * Update wsl-config.md fixed the string referring to autoProxy. it's no longer experimental. --------- Co-authored-by: Matt Wojciakowski <mattwoj@microsoft.com> * Moving ms.prod and ms.technology to ms.service and ms.subservice * Update to new feedback mechanism (#1917) * Update to new feedback mechanism * fix desc syntax * Fix template link * add svg support --------- Co-authored-by: Stefan Nikolaj <51296436+snikolaj@users.noreply.github.com> Co-authored-by: Anton Kesy <antonkesy@gmail.com> Co-authored-by: Ishan Jain <github@ishan.jain.se> Co-authored-by: Krishna Vivek Vitta <84629581+krishnacx@users.noreply.github.com> Co-authored-by: icyerasor <andreas@feldschmid.com> Co-authored-by: Blake-Madden <66873089+Blake-Madden@users.noreply.github.com> Co-authored-by: vmsteiner <107506233+vmsteiner@users.noreply.github.com> Co-authored-by: Andrew Zipperer <47086307+zipperer@users.noreply.github.com> Co-authored-by: Wes Bryie <wes@wesbryie.tech> Co-authored-by: Craig Loewen <crloewen@microsoft.com> Co-authored-by: Frans van Dorsselaer <17404029+dorssel@users.noreply.github.com> Co-authored-by: Keith Horton <khorton@microsoft.com> Co-authored-by: Drew Batchelor (he/him) <drewbat@microsoft.com>
MicrosoftDocs · Feb 2, 2024 · a7f1dfa · a7f1dfa
1 parent d90da18
commit a7f1dfa
Show file tree

Hide file tree

Showing 5 changed files with 139 additions and 36 deletions.
diff --git a/.github/ISSUE_TEMPLATE/doc-issue.yml b/.github/ISSUE_TEMPLATE/doc-issue.yml
@@ -0,0 +1,63 @@
+name: Post a documentation issue
+title: Contribute Feedback
+description: >-
+ Post an issue specific to WSL documentation.
+labels:
+ - "needs-triage"
+body:
+ - type: markdown
+ attributes:
+ value: "## Enter your feedback"
+ - type: markdown
+ attributes:
+ value: Select the issue type, and describe the issue in the text box below. Add as much detail as needed to help us resolve the issue.
+ - type: dropdown
+ id: issue-type
+ attributes:
+ label: Type of issue
+ options:
+ - Typo
+ - Code doesn't work
+ - Missing information
+ - Outdated article
+ - Other (describe below)
+ validations:
+ required: true
+ - type: textarea
+ id: userfeedback
+ validations:
+ required: true
+ attributes:
+ label: Feedback
+ description: Provide details that will add context on what should be updated in the documentation. Additional details not needed for typos, grammar, formatting, etc. For technical or factual errors, please include code snippets and output to show how the documentation is incorrect.
+ - type: markdown
+ attributes:
+ value: "## Article information"
+ - type: markdown
+ attributes:
+ value: "*Don't modify the following fields*. They are automatically filled in for you. Doing so will disconnect your issue from the affected article. *Don't edit them*."
+ - type: input
+ id: pageUrl
+ validations:
+ required: true
+ attributes:
+ label: Page URL
+ - type: input
+ id: contentSourceUrl
+ validations:
+ required: true
+ attributes:
+ label: Content source URL
+ - type: input
+ id: author
+ validations:
+ required: true
+ attributes:
+ label: Author
+ description: GitHub Id of the author
+ - type: input
+ id: documentVersionIndependentId
+ validations:
+ required: true
+ attributes:
+ label: Document Id
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: 11/20/2023
+ms.date: 01/04/2024
 ms.topic: article
 ---
 
@@ -14,9 +14,9 @@ Setting up the USB/IP project on your Windows machine will enable common develop
 ## Prerequisites
 
 - Running Windows 11 (Build 22000 or later). *(Windows 10 support is possible, see note below).*
-- A machine with an x64/x86 processor is required. (Arm64 is currently not supported with usbipd-win).
+- A machine with an x64 processor is required. (x86 and Arm64 are currently not supported with usbipd-win).
+- WSL is [installed and set up with the latest version](./install.md).
 - Linux distribution installed and [set to WSL 2](./basic-commands.md#set-wsl-version-to-1-or-2).
-- Running [Linux kernel 5.10.60.1 or later](./kernel-release-notes.md).
 
 > [!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)**.
@@ -42,33 +42,29 @@ This will install:
 - A command line tool `usbipd`. The location of this tool will be added to the PATH environment variable.
 - A firewall rule called `usbipd` to allow all local subnets to connect to the service. You can modify this firewall rule to fine tune access control.
 
-## Install the USBIP tools and hardware database in Linux
-
-Once the USB/IP project has completed installing, you will need to install the user space tools and a database of USB hardware identifiers. These instructions are for Ubuntu — [other distributions may require a different usbip client package](https://github.com/dorssel/usbipd-win/wiki/WSL-support#usbip-client-tools).
+## Attach a USB device
 
-On Ubuntu, run this command:
+Before attaching your USB device, ensure that a WSL command line is open. This will keep the WSL 2 lightweight VM active.
 
-```bash
-sudo apt install linux-tools-generic hwdata
-sudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/*-generic/usbip 20
-```
+> [!NOTE]
+> This doc assumes that you have [`usbipd-win 4.0.0` or higher installed](https://github.com/dorssel/usbipd-win/releases/latest)
 
-At this point a service is running on Windows to share USB devices, and the necessary tools are installed in WSL to attach to shared devices.
+1. List all of the USB devices connected to Windows by opening PowerShell in *administrator* mode and entering the following command. Once the devices are listed, select and copy the bus ID of the device you’d like to attach to WSL.
 
-## Attach a USB device
-
-Before attaching your USB device, ensure that a WSL command line is open. This will keep the WSL 2 lightweight VM active.
+ ```powershell
+ usbipd list
+ ```
 
-1. List all of the USB devices connected to Windows by opening PowerShell in *administrator* mode and entering the command:
+2. Before attaching the USB device, the command `usbipd bind` must be used to share the device, allowing it to be attached to WSL. This requires administrator privileges. Select the bus ID of the device you would like to use in WSL and run the following command. After running the command, verify that the device is shared using the command `usbipd list` again.
 
  ```powershell
- usbipd wsl list
+ usbipd bind --busid 4-4
  ```
 
-2. Select the bus ID of the device you’d like to attach to WSL and run this command. You’ll be prompted by WSL for a password to run a sudo command. The Linux distribution to be attached must be your default distribution. (See the [Basic commands for WSL](./basic-commands.md#set-default-linux-distribution) doc to change your default distribution).
+3. To attach the USB device, run the following command. (You no longer need to use an elevated administrator prompt.) Ensure that a WSL command prompt is open in order to keep the WSL 2 lightweight VM active. Note that as long as the USB device is attached to WSL, it cannot be used by Windows. Once attached to WSL, the USB device can be used by any distribution running as WSL 2. Verify that the device is attached using `usbipd list`. From the WSL prompt, run `lsusb` to verify that the USB device is listed and can be interacted with using Linux tools.
 
  ```powershell
- usbipd wsl attach --busid <busid>
+ usbipd attach --wsl --busid <busid>
  ```
 
 3. Open Ubuntu (or your preferred WSL command line) and list the attached USB devices using the command:
@@ -79,10 +75,10 @@ Before attaching your USB device, ensure that a WSL command line is open. This
 
  You should see the device you just attached and be able to interact with it using normal Linux tools. Depending on your application, you may need to configure udev rules to allow non-root users to access the device.
 
-4. Once you are done using the device in WSL, you can either physically disconnect the USB device or run this command from PowerShell in *administrator* mode:
+4. Once you are done using the device in WSL, you can either physically disconnect the USB device or run this command from PowerShell:
 
  ```powershell
- usbipd wsl detach --busid <busid>
+ usbipd detach --busid <busid>
  ```
 
 To learn more about how this works, see the [Windows Command Line Blog](https://devblogs.microsoft.com/commandline/connecting-usb-devices-to-wsl/#how-it-works) and the [usbipd-win repo on GitHub](https://devblogs.microsoft.com/commandline/connecting-usb-devices-to-wsl/#how-it-works).

diff --git a/WSL/docfx.json b/WSL/docfx.json
@@ -21,7 +21,8 @@
  "files": [
  "**/*.png",
  "**/*.gif",
- "**/*.jpg"
+ "**/*.jpg",
+ "**/*.svg"
  ],
  "exclude": [
  "**/obj/**",
@@ -35,10 +36,17 @@
  "breadcrumb_path": "/windows/wsl/breadcrumb/toc.json",
  "uhfHeaderId": "MSDocsHeader-Windows",
  "recommendations" : true,
- "feedback_system": "GitHub",
- "feedback_github_repo": "MicrosoftDocs/WSL",
- "ms.prod": "dev-environment",
- "ms.technology": "windows-subsystem-for-linux",
+ "feedback_product_url": "https://github.com/Microsoft/wsl/issues",
+ "feedback_system": "OpenSource",
+ "open_source_feedback_contributorGuideUrl": "https://learn.microsoft.com/contribute/content/how-to-write-quick-edits",
+ "open_source_feedback_issueTitle": "",
+ "open_source_feedback_issueLabels": "needs-triage",
+ "open_source_feedback_issueUrl": "https://github.com/MicrosoftDocs/wsl/issues/new?template=doc-issue.yml",
+ "open_source_feedback_productLogoLightUrl": "https://learn.microsoft.com/windows/wsl/media/wsl-icon.svg",
+ "open_source_feedback_productLogoDarkUrl": "https://learn.microsoft.com/windows/wsl/media/wsl-icon.svg",
+ "open_source_feedback_productName": "Windows Subsystem for Linux", 
+ "ms.service": "dev-environment",
+ "ms.subservice": "windows-subsystem-for-linux",
  "author": "craigloewen-msft",
  "ms.author": "crloewen",
  "searchScope": ["WSL"],

diff --git a/WSL/media/wsl-icon.svg b/WSL/media/wsl-icon.svg
diff --git a/WSL/wsl-config.md b/WSL/wsl-config.md
@@ -1,7 +1,7 @@
 ---
 title: Advanced settings configuration in WSL
 description: A guide to the wsl.conf and .wslconfig files used for configuring settings when running multiple Linux distributions on Windows Subsystem for Linux.
-ms.date: 11/10/2023
+ms.date: 01/17/2024
 ms.topic: article
 ms.custom: seo-windows-dev
 adobe-target: true
@@ -221,15 +221,10 @@ This file can contain the following options that affect the VM that powers any W
 | 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.|
-|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 |
-|useWindowsDnsCache**| bool | false | Only applicable when `experimental.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 `experimental.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. |
-|initialAutoProxyTimeout*| string | 1000 | Only applicable when `experimental.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 `experimental.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 `experimental.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. Note that 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. |
+| 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 |
 
 Entries with the `path` value must be Windows paths with escaped backslashes, e.g: `C:\\Temp\\myCustomKernel`
 
@@ -249,6 +244,15 @@ These settings are opt-in previews of experimental features that we aim to make
 |:----|:----|:----|:----|
 |`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. |
+|`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. Note that 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. |
+
+Entries with an * after the value type are only available on Windows 11.
+
+Entries with an ** after the value type require [Windows version 22H2](https://blogs.windows.com/windows-insider/2023/09/14/releasing-windows-11-build-22621-2359-to-the-release-preview-channel/) or higher.
 
 ## Example .wslconfig file