Main > Live (#2064)

* Final editorial review update (#2063) Fix oobe delete user path Rename best practices to recommendations Minor writing style updates * Fix backtick in build-custom-distro.md (#2062) * Remove the duplicate `feedback_product_url` value (#2040) * Update troubleshooting.md (#2034) Azure virtual machine does support Nested Virtualization, but cannot use with Trusted Launch. Hence proposing minor correction. * Update networking.md (#2033) Updated that the hostname takes a lowercase -i as the address flag. This can be seen by running hostname --help. also made the "under the hood" section more verbose with the full length ip-address command. * Add the information about the --pre-release option (#2031) * Add note for blocked Microsoft Store (#2030) * Add note for blocked Microsoft Store * Editorial update --------- Co-authored-by: Matt Wojciakowski <[email protected]> * Add rule to ignore service account's contribute (#2039) * Update WSL shutdown instructions for clarity by specifying PowerShell should be run as administrator before executing the shutdown command. (#2028) * Update WSL shutdown instructions for clarity by specifying PowerShell should be run as administrator before executing the shutdown command. * Add Docker Desktop error recommendation --------- Co-authored-by: Matt Wojciakowski <[email protected]> * Fix warnings (#2065) --------- Co-authored-by: Carlos Nihelton <[email protected]> Co-authored-by: Caozhi Li <[email protected]> Co-authored-by: thiruma0203 <[email protected]> Co-authored-by: Horsevad <[email protected]> Co-authored-by: Carlos Rafael Ramirez <[email protected]> Co-authored-by: Chunyao Chan <[email protected]>
MicrosoftDocs · Nov 19, 2024 · 66074a6 · 66074a6
1 parent 23bf4e7
commit 66074a6
Show file tree

Hide file tree

Showing 7 changed files with 54 additions and 47 deletions.
diff --git a/WSL/build-custom-distro.md b/WSL/build-custom-distro.md
@@ -1,7 +1,7 @@
 ---
 title: Build a Custom Linux Distro for WSL - Windows
 description: Learn how to create a custom Linux distribution for Windows Subsystem for Linux.
-ms.date: 11/18/2024
+ms.date: 11/19/2024
 ms.topic: article
 ---
 
@@ -14,8 +14,7 @@ WSL distributions have two parts:
 1) A root filesystem (distributed as a tar file)
 2) A manifest entry (which contains the distribution metadata)
 
-> [!NOTE]
-> This guide only applies to [WSL release 2.4.4]( https://github.com/microsoft/WSL/releases) and higher.
+This guide only applies to [WSL release 2.4.4]( https://github.com/microsoft/WSL/releases) and higher.
 
 > [!NOTE]
 > See [this repository](https://github.com/microsoft/WSL-DistroLauncher) for the previous appx based distribution packaging instructions. 
@@ -64,12 +63,12 @@ WSL distribution file configuration options:
 | `oobe.defaultUid` | integer | `<none>` | The default UID that the distribution starts with. This is useful when the `oobe.command` script creates a new user. |
 | `oobe.defaultName`| string | `<none>` | The default name that the distribution is registered under. This default name can be replaced with the command: `wsl.exe --install <distro> --name <name>` |
 | `shortcut.icon` | string | The default WSL icon | The icon in the start menu shortcut for the distribution. Must be in `.ico` format with a maximum size of `10MB` |
-| ‘windowsterminal.profileTemplate` | string | Path to a terminal template file | The JSON template to generate a Windows Terminal profile for this distribution. | 
+| `windowsterminal.profileTemplate` | string | Path to a terminal template file | The JSON template to generate a Windows Terminal profile for this distribution. | 
 
 You need to create an out of box experience (OOBE) first run experience for the distribution. Below is a sample bash script that you can use. This script assumes that `oobe.defaultUid` is set to `1000`: 
 
 ```bash
-#! /bin/bash
+#!/bin/bash
 
 set -ue
 
@@ -95,7 +94,7 @@ while true; do
     if /usr/sbin/usermod "$username" -aG "$DEFAULT_GROUPS"; then
       break
     else
-      /usr/bin/deluser "$username"
+      /usr/sbin/deluser "$username"
     fi
   fi
 done
@@ -105,7 +104,7 @@ done
 
 WSL automatically generates a Windows Terminal profile when a distribution is installed. Distribution maintainers can customize the generated profile generated by setting ` windowsterminal.profileTemplate` in the WSL configuration file, `/etc/wsl-distribution.conf`. 
 
-The json file follows [the terminal profile json format](https://learn.microsoft.com/en-us/windows/terminal/json-fragment-extensions#structure-of-the-json-files).  Here’s an example profile: 
+The json file follows [the terminal profile json format](/windows/terminal/json-fragment-extensions#structure-of-the-json-files).  Here’s an example profile: 
 
 ```
 
@@ -156,15 +155,15 @@ systemd=true|false
 
 The distribution author determines whether systemd is enabled by default by setting the `boot.systemd` value to `true` (enabled) or `false` (not enabled). 
 
-See the [best practices section](#systemd) if you chose to enable systemd by default.
+See the [Systemd recommendations](#systemd-recommendations) if you chose to enable systemd by default.
 
-See [Advanced settings configuration in WSL](./wsl-config#wslconf) for all supported settings in `/etc/wsl.conf`.
+See [Advanced settings configuration in WSL](./wsl-config.md) for all supported settings in `/etc/wsl.conf`.
 
 ### Create the tar file
 
-Once the distribution and configuration files are in place, the root filesystem can be captured in tar. 
+Once the distribution and configuration files are in place, the root filesystem can be captured in the tar file. 
 
-Below is the recommended way of creating the tar:
+The recommended way of creating the tar file:
 
 ```
 $ cd /path/to/rootfs
@@ -175,27 +174,27 @@ The root of the tar should be the root of the filesystem (not a directory contai
 
 The recommended compression format is gzip. Other compression formats run the risk of breaking compatibility with older WSL versions.
 
-See the [best practices section](#configuration-files) for files that should, or shouldn't be included
+See the [Configuration file recommendations](#configuration-file-recommendations) for a list of files that should and shouldn't be included in the configuration.
 
-To obtain a TAR file of an existing Linux distribution, find guidance on how to export a docker container in [Import any Linux distribution to use with WSL](./use-custom-distro.md).
+To obtain a tar file of an existing Linux distribution, find guidance on how to export a docker container in [Import any Linux distribution to use with WSL](./use-custom-distro.md).
 
-Once the tar file archive is ready, see [Overriding the distribution manifest](#adding-your-distro-to-wsl---install-for-your-enterprise-or-group) to try it out locally.
+Once the tar file archive is ready, see [Test the distribution locally](#test-the-distribution-locally) to try it out locally.
 
 ## Create a .wsl file extension
 
-The final step, once you have create a TAR file to represent your custom Linux distribution, is to change the `.tar` file file extension to a `.wsl` file extension by renaming it. Renaming this file extension will mark it as a WSL distribution. Once the TAR has be renamed from `.tar` to `.wsl`, the file will install correctly on Windows when opened (double-clicked) in File Explorer. A `oobe.defaultName` entry is required in the `/etc/wsl-distribution.conf` file for this double-click experience to function properly
+The final step, once you have create a tar file to represent your custom Linux distribution, is to change the `.tar` file extension to a `.wsl` file extension by renaming it. Renaming this file extension will mark it as a WSL distribution. Once the tar has be renamed from `.tar` to `.wsl`, the file will install correctly on Windows when opened (double-clicked) in File Explorer. A `oobe.defaultName` entry is required in the `/etc/wsl-distribution.conf` file for this double-click experience to function properly.
 
 ## Distribute your WSL distribution
 
-WSL users can view available distributions by running `wsl --list --online` and can install them directly with `wsl --install <distroName>` (replacing <distroName> with the actual name of the Linux distribution. This process is controlled by a distribution manifest file. You can add this manifest file to your customer Linux distribution for it to be included in the `wsl --install` command options.
+WSL users can view available distributions by running `wsl --list --online` and can install them directly with `wsl --install <distroName>` (replacing `<distroName>` with the actual name of the Linux distribution. This process is controlled by a distribution manifest file. You can add this manifest file to your customer Linux distribution for it to be included in the `wsl --install` command options.
 
-The custom Linux distribution TAR that you’ve created and renamed with a `.wsl` file extension can be distributed however you please. Once downloaded a user can install it directly from the command line with `wsl --install --from-file <fileLocation>` (replacing <fileLocation> with the actual location of the file). Alternatively, the `.wsl` file for your custom WSL distribution can be opened by double-clicking it.
+The custom Linux distribution tar that you’ve created and renamed with a `.wsl` file extension can be distributed however you please. Once downloaded a user can install it directly from the command line with `wsl --install --from-file <fileLocation>` (replacing `<fileLocation>` with the actual location of the file). Alternatively, the `.wsl` file for your custom WSL distribution can be opened by double-clicking it.
 
 ## Distribution manifest details
 
 The [distribution manifest](https://github.com/microsoft/WSL/blob/master/distributions/DistributionInfo.json) contains metadata about the distributions that are available for installation via `wsl --install <distribution>`.
 
-TAR based distributions are listed under `ModernDistribution`, with the below format: 
+Linux distributions that are tar-based are listed under `ModernDistribution`, with the below format: 
 
 ```
 "ModernDistributions": {
@@ -251,25 +250,26 @@ $ wsl --install my-distro-v3 # Installs 'my-distro-v3' explicitly
 $ wsl --install my-distro-v2 # Installs 'my-distro-v2' explicitly
 ```
 
-## Adding your distro to `wsl --install` for all WSL users
+## Adding your distribution to `wsl --install` for all WSL users
 
-To make your WSL distro available to all users, please open a pull request on the [WSL GitHub repository](github.com/microsoft/wsl) that modifies the [DistributionInfo.json](https://github.com/microsoft/WSL/blob/master/distributions/DistributionInfo.json) file to include your distro information. 
+To make your WSL distribution available to all users, open a pull request on the [WSL GitHub repository](https://github.com/microsoft/wsl) that modifies the [DistributionInfo.json](https://github.com/microsoft/WSL/blob/master/distributions/DistributionInfo.json) file to include your distribution information. 
 
 This pull request will be reviewed by the WSL team.
 
-## Adding your distro to `wsl --install` for your enterprise or group
+## Adding your distribution to `wsl --install` for your enterprise or business group
 
-You can also make your distro available in `wsl --install` only to a select group by editing registry keys on chosen machines. 
+You can also make your distribution available in `wsl --install` only to a select group by editing registry keys on the chosen Windows devices.
 
 The WSL distribution manifest can be overridden by creating registry values in `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss`. 
 
 - `DistributionListUrl`: Overrides the distribution manifest URL
 - `DistributionListUrlAppend`: Add distributions from that manifest URL to the list of installable distributions
 
 Both registry values are strings (REG_SZ) and are expected to be in URL format. 
-Starting with WSL 2.4.4, the `file://` protocol is supported to make local testing easier. The expected format is: `file:///C:/path/to/file`
 
-### Testing a local distribution
+Starting with WSL release 2.4.4, the `file://` protocol is supported to make local testing easier. The expected format is: `file:///C:/path/to/file`.
+
+### Test the distribution locally
 
 To test a distribution tar, you can use the following sample powershell script to override the distribution manifest with the new distribution. First save the script below as `override-manifest.ps1`:
 
@@ -311,13 +311,13 @@ $manifest | ConvertTo-Json -Depth 5 | Out-File -encoding ascii $manifestFile
 Set-ItemProperty -Path "HKLM:SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss" -Name DistributionListUrl -Value "file://$manifestFile" -Type String -Force 
 ```
 
-Then configure the local manifest by running the following command in an elevated powershell:
+Then configure the local manifest by running the following command in an elevated Powershell:
 
 ```powershell
 .\override-manifest.ps1 -TarPath /path/to/tar
 ```
 
-Once completed, you should see the following output from `wsl.exe --list --online`
+Once completed, you should see the following output from `wsl.exe --list --online`:
 
 ```powershell
 $ wsl --list --online
@@ -332,22 +332,22 @@ You can then run `wsl.exe --install test-distro-v1` to try the installation of t
 
 When you're done, you can delete `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl` to revert to the official manifest.
 
-## Best practices
+## WSL custom Linux distribution recommendations
 
-### Configuration files
+### Configuration file recommendations
 
-- `/etc/wsl.conf` and `/etc/wsl-distribution.conf` should be included. They should be owned by `root:root` and their permissions should be `0644`
-- If `oobe.command` is used to create a new user, its uid should be `1000`, and should `oobe.defaultUid` should be set to that value.
-- `oobe.defaultName` and `shortcut.icon` should be specified in `/etc/wsl-distribution.conf`
-- `/etc/resolv.conf` should NOT be included in the root filesystem
-- There should be a root user in `/etc/passwd` and its uid should be `0`
-- There should be no password hashes in `/etc/shadow`
-- The archive should not contain a kernel or an initramfs
+- Ensure that your custom distribution includes both the `/etc/wsl.conf` and `/etc/wsl-distribution.conf` configuration files. Both files should be owned by `root:root` and their permissions should be `0644`.
+- If the `oobe.command` setting is used to create a new user, both `uid` and `oobe.defaultUid` should be set to `1000`.
+- Ensure that you set both `oobe.defaultName` and `shortcut.icon` in the distribution configuration file: `/etc/wsl-distribution.conf`
+- Do not include the file `/etc/resolv.conf` in the root filesystem.
+- Do include a root user in `/etc/passwd`. The `uid` for this root user should be `0`.
+- There should be no password hashes in `/etc/shadow`.
+- The archive should not contain a kernel or an initramfs.
 
-### Systemd 
+### Systemd recommendations
 
 If systemd is enabled, units that can cause issues with WSL should be disabled or masked. 
-The below units that are known to cause issues in WSL distributions (applies to both system and user units):
+The below units are known to cause issues in WSL distributions (applies to both system and user units):
 
 - systemd-resolved.service
 - systemd-networkd.service

diff --git a/WSL/compare-versions.md b/WSL/compare-versions.md
@@ -1,7 +1,7 @@
 ---
 title: Comparing WSL Versions
 description: WSL 2 provides the benefits of WSL 1, but uses an actual Linux kernel, rather than a translation layer like WSL 1, resulting in faster performance.
-ms.date: 11/20/2023
+ms.date: 11/19/2024
 ms.topic: conceptual
 ms.custom: seo-windows-dev
 ---
@@ -97,3 +97,6 @@ We recommend that you use WSL 2 as it offers faster performance and 100% system
 WSL has lifted the update functionality out of the Windows OS Image into a package that is available via the Microsoft Store. This means faster updates and servicing as soon as they're available, rather than needing to wait for an update of your Windows operating system.
 
 WSL was originally included in the Windows operating system as an optional component that need to be enabled in order to install a Linux distribution. WSL in the Store has the same user experience, and is the same product, but receives updates and servicing as a store package, rather than as an entire OS update. Beginning in Windows version 19044 or higher, running the `wsl.exe --install` command will install the WSL servicing update from the Microsoft Store. ([See the blog post announcing this update](https://devblogs.microsoft.com/commandline/the-windows-subsystem-for-linux-in-the-microsoft-store-is-now-generally-available-on-windows-10-and-11/)). If you are already using WSL, you can update to ensure that you're receiving the latest WSL features and servicing from the store by running `wsl.exe --update`.
+
+> [!NOTE]
+> If the Microsoft Store is inaccessible within your organization, you can still utilize this WSL version by appending `--web-download` to the `--update` command, such as `wsl --update --web-download`. You need to manually update WSL every time a new release becomes available using this method.
diff --git a/WSL/disk-space.md b/WSL/disk-space.md
@@ -1,7 +1,7 @@
 ---
 title: How to manage WSL disk space
 description: Learn how to check the amount of disk space available, expand the size of the Virtual Hard Disk (VHD), repair a VHD mounting or read-only error, and locate the .vhdx file and disk path for Linux distributions installed with WSL 2.
-ms.date: 11/10/2023
+ms.date: 11/19/2024
 ms.topic: article
 ---
 
@@ -162,13 +162,13 @@ touch: cannot touch 'file': Read-only file system
 
 To repair a disk mount error in WSL, and restore it back to a usable / writeable state again, you can use the `wsl.exe --mount` command to re-mount the disk with the following steps:
 
-1. Shutdown all WSL distributions by opening PowerShell and entering the command:
+1. Shutdown all WSL distributions by opening PowerShell as administrator (in an elevated command prompt) and entering the command:
 
     ```powershell
     wsl.exe --shutdown
     ```
 
-2. Open PowerShell as administrator (in an elevated command prompt) and enter the mount command, replacing `<path-to-ext4.vhdx>` with the path to the distribution's .vhdx file. For help locating this file, see [How to locate the VHD file and disk path for your Linux distribution](#how-to-locate-the-vhdx-file-and-disk-path-for-your-linux-distribution).
+2.  Enter the mount command and replace `<path-to-ext4.vhdx>` with the path to the distribution's .vhdx file. For help locating this file, see [How to locate the VHD file and disk path for your Linux distribution](#how-to-locate-the-vhdx-file-and-disk-path-for-your-linux-distribution).
 
     ```powershell
     wsl.exe --mount <path-to-ext4.vhdx> --vhd --bare
@@ -181,7 +181,7 @@ To repair a disk mount error in WSL, and restore it back to a usable / writeable
     ```
 
 > [!NOTE]
-> If you only have a single Linux distribution installed, you may encounter an "ext file in use" error and will need to [install](./basic-commands.md#install) an additional distribution in order to run `wsl.exe lsblk`. You can [uninstall](./basic-commands.md#unregister-or-uninstall-a-linux-distribution) the distribution once the repair is complete.
+> If you only have a single Linux distribution installed, you may encounter an "ext file in use" error and will need to [install](./basic-commands.md#install) an additional distribution in order to run `wsl.exe lsblk`. You can [uninstall](./basic-commands.md#unregister-or-uninstall-a-linux-distribution) the distribution once the repair is complete. Additionally, you may need to close Docker Desktop on Windows to avoid the error `Wsl/Service/CreateInstance/MountVhd/HCS/ERROR_SHARING_VIOLATION` while running the command `wsl.exe sudo e2fsck -f /dev/sdc`.
 
 4. Once the repair is complete, unmount the disk in PowerShell by entering:
 

diff --git a/WSL/docfx.json b/WSL/docfx.json
@@ -51,9 +51,11 @@
       "ms.author": "mattwoj",
       "ms.reviewer": "crloewen",
       "searchScope": ["WSL"],
-      "feedback_product_url": "https://github.com/Microsoft/WSL/issues",
       "adobe-target": true
     },
+    "contributors_to_exclude": [
+      "VSC-Service-Account"
+    ],
     "fileMetadata": {},
     "template": [],
     "dest": "wsl",

diff --git a/WSL/install.md b/WSL/install.md
@@ -105,6 +105,8 @@ Try the most recent features or updates to WSL by joining the [Windows Insiders
 - Beta channel: Ideal for early adopters, more reliable builds than the Dev channel.
 - Release Preview channel: Preview fixes and key features on the next version of Windows just before its available to the general public.
 
+If you prefer not switching your Windows installation to a preview channel, you can still test the latest preview of WSL by issuing the command: `wsl --update --pre-release`. For more information check the [WSL Releases page on GitHub](https://github.com/Microsoft/WSL/releases).
+
 ## Additional resources
 
 - [Windows Command Line Blog: Install WSL with a single command now available in Windows 10 version 2004 and higher](https://devblogs.microsoft.com/commandline/install-wsl-with-a-single-command-now-available-in-windows-10-version-2004-and-higher/)