Merge pull request #2294 from MicrosoftDocs/main

Merge main to live

Author: craigloewen-msft

WSL/basic-commands.md

@@ -15,11 +15,11 @@ The WSL commands below are listed in a format supported by PowerShell or Windows
 wsl --install
 ```
 
-Install WSL and the default Ubuntu distribution of Linux. [Learn more](./install.md). You can also use this command to install additional Linux distributions by running `wsl --install <Distribution Name>`. For a valid list of distribution names, run `wsl --list --online`. 
+Install WSL and the default Ubuntu distribution of Linux. [Learn more](./install.md). You can also use this command to install additional Linux distributions by running `wsl --install <Distribution Name>`. For a valid list of distribution names, run `wsl --list --online`.
 
-Options include: 
+Options include:
 
-- `--distribution`: Specify the Linux distribution to install. You can find available distributions by running `wsl --list --online`. 
+- `--distribution`: Specify the Linux distribution to install. You can find available distributions by running `wsl --list --online`.
 - `--no-launch`: Install the Linux distribution but do not launch it automatically.
 - `--web-download`: Install from an online source rather than using the Microsoft Store.
 
@@ -54,7 +54,7 @@ See a list of the Linux distributions installed on your Windows machine, includi
 wsl --set-version <distribution name> <versionNumber>
 ```
 
-To designate the version of WSL (1 or 2) that a Linux distribution is running on, replace `<distribution name>` with the name of the distribution and replace `<versionNumber>` with 1 or 2. [Comparing WSL 1 and WSL 2](./compare-versions.md). WSL 2 is only available in Windows 11 or Windows 10, Version 1903, Build 18362 or later. 
+To designate the version of WSL (1 or 2) that a Linux distribution is running on, replace `<distribution name>` with the name of the distribution and replace `<versionNumber>` with 1 or 2. [Comparing WSL 1 and WSL 2](./compare-versions.md). WSL 2 is only available in Windows 11 or Windows 10, Version 1903, Build 18362 or later.
 
 > [!WARNING]
 > Switching between WSL 1 and WSL 2 can be time-consuming and result in failures due to the differences between the two architectures. For distributions with large projects, we recommend backing up files before attempting a conversion.
@@ -65,7 +65,7 @@ To designate the version of WSL (1 or 2) that a Linux distribution is running on
 wsl --set-default-version <Version>
 ```
 
-To set a default version of WSL 1 or WSL 2, replace `<Version>` with either the number 1 or 2. For example, `wsl --set-default-version 2`. The number represents the version of WSL to default to for new Linux distribution installations. [Comparing WSL 1 and WSL 2](./compare-versions.md). WSL 2 is only available in Windows 11 or Windows 10, Version 1903, Build 18362 or later. 
+To set a default version of WSL 1 or WSL 2, replace `<Version>` with either the number 1 or 2. For example, `wsl --set-default-version 2`. The number represents the version of WSL to default to for new Linux distribution installations. [Comparing WSL 1 and WSL 2](./compare-versions.md). WSL 2 is only available in Windows 11 or Windows 10, Version 1903, Build 18362 or later.
 
 ## Set default Linux distribution
 
@@ -97,7 +97,7 @@ To run a specific Linux distribution with a specific user, replace `<Distributio
 wsl --update
 ```
 
-Update your WSL version to the latest version. Options include: 
+Update your WSL version to the latest version. Options include:
 
 - `--web-download`: Download the latest update from the GitHub rather than the Microsoft Store.
 
@@ -109,13 +109,13 @@ wsl --status
 
 See general information about your WSL configuration, such as default distribution type, default distribution, and kernel version.
 
-## Check WSL version 
+## Check WSL version
 
 ```powershell
 wsl --version
 ```
 
-Check the version information about WSL and its components. 
+Check the version information about WSL and its components.
 
 ## Help command
 
@@ -156,7 +156,7 @@ For example:
 wsl --shutdown
 ```
 
-Immediately terminates all running distributions and the WSL 2 lightweight utility virtual machine. This command may be necessary in instances that require you to restart the WSL 2 virtual machine environment, such as [changing memory usage limits](/windows/wsl/disk-space) or making a change to your [.wslconfig file](./manage.md).
+Immediately terminates all running distributions and the WSL 2 lightweight utility virtual machine. This command may be necessary in instances that require you to restart the WSL 2 virtual machine environment, such as [changing memory usage limits](./disk-space.md) or making a change to your [.wslconfig file](./manage.md).
 
 ## Terminate
 
@@ -240,7 +240,7 @@ Attach and mount a physical disk in all WSL2 distributions by replacing `<DiskPa
 wsl --unmount <DiskPath>
 ```
 
-Unmount a disk given at the disk path, if no disk path is given then this command will unmount and detach ALL mounted disks.  
+Unmount a disk given at the disk path, if no disk path is given then this command will unmount and detach ALL mounted disks.
 
 ## Deprecated WSL commands
 

WSL/build-custom-distro.md

@@ -9,19 +9,19 @@ ms.topic: how-to
 
 This guide will walk through the steps to create and distribute a WSL distribution, which is a `.wsl` file.
 
-WSL distributions have two parts: 
+WSL distributions have two parts:
 
 1) A root filesystem (distributed as a tar file)
 2) A manifest entry (which contains the distribution metadata)
 
 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. 
+> See [this repository](https://github.com/microsoft/WSL-DistroLauncher) for the previous appx based distribution packaging instructions.
 
 ## What are WSL root filesystem tar files?
 
-WSL distributions are defined by a tar file with a `.wsl` file extension on Windows. 
+WSL distributions are defined by a tar file with a `.wsl` file extension on Windows.
 
 A TAR file (short for Tape Archive) is a type of archive file used to store multiple files together in a single file for easier distribution or backup. The TAR file contains the root file system of a Linux distribution (all the distribution files), as well as the WSL configuration files. WSL configuration files tell the WIndows operating system how to install and launch the distribution.
 
@@ -32,7 +32,7 @@ Once you have a Linux system that you'd like to make into a WSL distribution, fo
 There are two configuration files that the distribution should include:
 
 1. `/etc/wsl-distribution.conf`: A file created by the distribution maintainer responsible for controlling how the Linux distribution should be configured when first launched with WSL.
-2. `/etc/wsl.conf`: A file containing global system settings that are specific to the user and control how the distribution is launched. [Learn more about WSL configuration files.](/windows/wsl/wsl-config#what-is-the-difference-between-wslconf-and-wslconfig).
+2. `/etc/wsl.conf`: A file containing global system settings that are specific to the user and control how the distribution is launched. [Learn more about WSL configuration files.](./wsl-config.md).
 
 ### Add the WSL distribution configuration file
 
@@ -57,20 +57,20 @@ enabled = true
 ProfileTemplate = /usr/lib/wsl/terminal-profile.json
 ```
 
-WSL distribution file configuration options: 
+WSL distribution file configuration options:
 
-| key | value | default | notes |
-|:-----------|:---------|:--------|:------|
-| `oobe.command` | string | `<none>` | OOBE stands for out of box experience. This command runs the first time the user opens an interactive shell in the distribution. If that command returns non zero, it is considered unsuccessful, and the user won't be able to open a shell.   |
-| `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>` |
+| Key | Value | Default | Notes |
+|:---|:---|:---|:---|
+| `oobe.command` | string | None | OOBE stands for out of box experience. This command runs the first time the user opens an interactive shell in the distribution. If that command returns non zero, it is considered unsuccessful, and the user won't be able to open a shell.   |
+| `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` |
 | `shortcut.enabled` | boolean | true | Whether a start menu shortcut should be created when the distribution is installed. |
-| `windowsterminal.profileTemplate` | string | `<none>` | The JSON template to generate a Windows Terminal profile for this distribution. |
-| `windowsterminal.enabled` | boolean | true | Whether a terminal profile should be created when the distribution is installed. If `profileTemplate` is not set, a default profile will be generated. | 
-| `windowsterminal.profileTemplate` | string | Path to a terminal template file | The JSON template to generate a Windows Terminal profile for this distribution. | 
+| `windowsterminal.profileTemplate` | string | None | The JSON template to generate a Windows Terminal profile for this distribution. |
+| `windowsterminal.enabled` | boolean | true | Whether a terminal profile should be created when the distribution is installed. If `profileTemplate` is not set, a default profile will be generated. |
+| `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`: 
+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
@@ -107,12 +107,11 @@ done
 
 ## Generate a Windows Terminal profile
 
-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`. 
+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](/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:
 
+```json
 {
   "profiles": [
     {
@@ -143,39 +142,39 @@ The json file follows [the terminal profile json format](/windows/terminal/json-
     }
   ]
 }
-``` 
+```
 
 This file doesn’t need to specify the profile `name`, or `commandLine`. Those are automatically added by WSL when generating the terminal profile.
 
 ### Add a WSL configuration for local settings on a per-distribution basis
 
-In the context of a distribution root filesystem, we recommend that you configure systemd settings, including whether systemd starts by default, in the `/etc/wsl.conf` local settings on a per-distribution basis.  See the example below. 
+In the context of a distribution root filesystem, we recommend that you configure systemd settings, including whether systemd starts by default, in the `/etc/wsl.conf` local settings on a per-distribution basis.  See the example below.
 
-```
+```bash
 # /etc/wsl.conf
 
 [boot]
 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). 
+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 [Systemd recommendations](#systemd-recommendations) if you chose to enable systemd by default.
 
 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 the tar file. 
+Once the distribution and configuration files are in place, the root filesystem can be captured in the tar file.
 
 The recommended way of creating the tar file:
 
-```
-$ cd /path/to/rootfs
-$ tar --numeric-owner --absolute-names -c  * | gzip --best > ../install.tar.gz
+```bash
+cd /path/to/rootfs
+tar --numeric-owner --absolute-names -c  * | gzip --best > ../install.tar.gz
 ```
 
-The root of the tar should be the root of the filesystem (not a directory containing the root filesystem). 
+The root of the tar should be the root of the filesystem (not a directory containing the root filesystem).
 
 The recommended compression format is gzip. Other compression formats run the risk of breaking compatibility with older WSL versions.
 
@@ -199,78 +198,85 @@ The custom Linux distribution tar that you’ve created and renamed with a `.wsl
 
 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>`.
 
-Linux distributions that are tar-based are listed under `ModernDistribution`, with the below format: 
-
-```
-"ModernDistributions": {
+Linux distributions that are tar-based are listed under `ModernDistribution`, with the below format:
 
-"<flavor>": [
-    
-    {
-    "Name": "<version name>",
-    "FriendlyName": "<friendly name>",
-    "Default": true | false,
-    "Amd64Url": {
-        "Url": "<tar url>",
-        "Sha256": "<tar sha265 hash>"
-        },
-    "Arm64Url": {
-        "Url": "<tar url>",
-        "Sha256": "<tar sha265 hash>"
-        }
+```json
+{
+    "ModernDistributions": {
+        "<flavor>": [
+            {
+                "Name": "<version name>",
+                "FriendlyName": "<friendly name>",
+                "Default": true | false,
+                "Amd64Url": {
+                    "Url": "<tar url>",
+                    "Sha256": "<tar sha256 hash>"
+                },
+                "Arm64Url": {
+                    "Url": "<tar url>",
+                    "Sha256": "<tar sha256 hash>"
+                }
+            },
+            {
+                ...
+            }
+        ],
+        "<flavor>": [
+            ...
+        ]
     }
 }
-
 ```
 
 Each `flavor` entry contains a list of installable distributions. Distributions can be installed either via the flavor name (in which case the default entry is installed), or the version name.
 
-See how `wsl --install` commands work with the below manifest: 
+See how `wsl --install` commands work with the below manifest:
 
-```
+```json
 {
     "ModernDistributions": {
         "my-distro": [
             {
-                "Name": "my-distro-v3", 
+                "Name": "my-distro-v3",
                 "Default": true,
                 "FriendlyName": "My distribution version 3 (latest)"
-                 [...]
+                [...]
             },
             {
-                "Name": "my-distro-v2", 
+                "Name": "my-distro-v2",
                 "Default": false,
                 "FriendlyName": "My distribution version 2"
-                 [...]
+                [...]
             }
-    }        
+        ]
+    }
 }
 ```
 
-Sample install commands: 
+Sample install commands:
 
-```
-$ wsl --install my-distro # Installs 'my-distro-v3' since it's the default for 'my-distro' flavor
-$ wsl --install my-distro-v3 # Installs 'my-distro-v3' explicitly
-$ wsl --install my-distro-v2 # Installs 'my-distro-v2' explicitly
+```powershell
+wsl --install my-distro # Installs 'my-distro-v3' since it's the default for 'my-distro' flavor
+wsl --install my-distro-v3 # Installs 'my-distro-v3' explicitly
+wsl --install my-distro-v2 # Installs 'my-distro-v2' explicitly
 ```
 
 ## Adding your distribution to `wsl --install` for all WSL users
 
-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. 
+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 distribution to `wsl --install` for your enterprise or business group
 
 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`. 
+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. 
+Both registry values are strings (REG_SZ) and are expected to be in URL format.
 
 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`.
 
@@ -313,7 +319,7 @@ $manifestFile = "$PSScriptRoot/manifest.json"
 $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 
+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:
@@ -351,7 +357,7 @@ When you're done, you can delete `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\
 
 ### Systemd recommendations
 
-If systemd is enabled, units that can cause issues with WSL should be disabled or masked. 
+If systemd is enabled, units that can cause issues with WSL should be disabled or masked.
 The below units are known to cause issues in WSL distributions (applies to both system and user units):
 
 - systemd-resolved.service