diff --git a/WSL/build-custom-distro.md b/WSL/build-custom-distro.md index d54348b3..25e6ab6a 100644 --- 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/19/2024 +ms.date: 02/05/2025 ms.topic: article --- @@ -49,9 +49,11 @@ defaultUid = 1000 defaultName = my-distro [shortcut] +enabled = true icon = /usr/lib/wsl/my-icon.ico [windowsterminal] +enabled = true ProfileTemplate = /usr/lib/wsl/terminal-profile.json ``` @@ -63,6 +65,9 @@ WSL distribution file configuration options: | `oobe.defaultUid` | integer | `` | The default UID that the distribution starts with. This is useful when the `oobe.command` script creates a new user. | | `oobe.defaultName`| string | `` | The default name that the distribution is registered under. This default name can be replaced with the command: `wsl.exe --install --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 | `` | 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`: diff --git a/WSL/compare-versions.md b/WSL/compare-versions.md index e8155e06..75a25cd1 100644 --- a/WSL/compare-versions.md +++ b/WSL/compare-versions.md @@ -54,7 +54,7 @@ WSL 2 provides the benefits of WSL 1, including seamless integration between Win ### Full Linux kernel -The Linux kernel in WSL 2 is built by Microsoft from the latest stable branch, based on the source available at kernel.org. This kernel has been specially tuned for WSL 2, optimizing for size and performance to provide an amazing Linux experience on Windows. The kernel will be serviced by Windows updates, which means you will get the latest security fixes and kernel improvements without needing to manage it yourself. +The Linux kernel in WSL 2 is built by Microsoft from the latest stable branch, based on the source available at [kernel.org](https://kernel.org). This kernel has been specially tuned for WSL 2, optimizing for size and performance to provide an amazing Linux experience on Windows. The kernel will be serviced by Windows updates, which means you will get the latest security fixes and kernel improvements without needing to manage it yourself. The [WSL 2 Linux kernel is open source](https://github.com/microsoft/WSL2-Linux-Kernel). If you'd like to learn more, check out the blog post [Shipping a Linux Kernel with Windows](https://devblogs.microsoft.com/commandline/shipping-a-linux-kernel-with-windows/) written by the team that built it. @@ -62,9 +62,9 @@ Learn more in the [Release Notes for Windows Subsystem for Linux kernel](./kerne ### Increased file IO performance -File intensive operations like git clone, npm install, apt update, apt upgrade, and more are all noticeably faster with WSL 2. +File intensive operations like `git clone`, `npm install`, `apt update`, `apt upgrade`, and more are all noticeably faster with WSL 2. -The actual speed increase will depend on which app you're running and how it is interacting with the file system. Initial versions of WSL 2 run up to 20x faster compared to WSL 1 when unpacking a zipped tarball, and around 2-5x faster when using git clone, npm install and cmake on various projects. +The actual speed increase will depend on which app you're running and how it is interacting with the file system. Initial versions of WSL 2 run up to 20x faster compared to WSL 1 when unpacking a zipped tarball, and around 2-5x faster when using `git clone`, `npm install` and `cmake` on various projects. ### Full system call compatibility @@ -72,7 +72,7 @@ Linux binaries use system calls to perform functions such as accessing files, re - A whole new set of apps that you can run inside of WSL, such as **[Docker](tutorials/wsl-containers.md)** and more. -- Any updates to the Linux kernel are immediately ready for use. (You don't have to wait for the WSL team to implement updates and add the changes). +- Any updates to the Linux kernel are immediately ready for use (you don't have to wait for the WSL team to implement updates and add the changes). ## Exceptions for using WSL 1 rather than WSL 2 @@ -82,21 +82,21 @@ We recommend that you use WSL 2 as it offers faster performance and 100% system - If you will be using your WSL Linux distribution to access project files on the Windows file system, and these files cannot be stored on the Linux file system, you will achieve faster performance across the OS files systems by using WSL 1. - A project which requires cross-compilation using both Windows and Linux tools on the same files. - File performance across the Windows and Linux operating systems is faster in WSL 1 than WSL 2, so if you are using Windows applications to access Linux files, you will currently achieve faster performance with WSL 1. -- Your project needs access to a serial port or USB device. *However,* USB device support is now available for WSL 2 via the USBIPD-WIN project. See [Connect USB devices](./connect-usb.md) for set up steps. +- Your project needs access to a serial port or USB device. *However,* USB device support is now available for WSL 2 via the `USBIPD-WIN` project. See [Connect USB devices](./connect-usb.md) for set up steps. - WSL 2 does not include support for accessing serial ports. Learn more in the [FAQs](./faq.yml#can-i-access-the-gpu-in-wsl-2--are-there-plans-to-increase-hardware-support-) or in [WSL GitHub repo issue on serial support](https://github.com/microsoft/WSL/issues/4322). - You have strict memory requirements - WSL 2's memory usage grows and shrinks as you use it. When a process frees memory this is automatically returned to Windows. However, as of right now WSL 2 does not yet release cached pages in memory back to Windows until the WSL instance is shut down. If you have long running WSL sessions, or access a very large amount of files, this cache can take up memory on Windows. We are tracking the work to improve this experience on [the WSL GitHub repository issue 4166](https://github.com/microsoft/WSL/issues/4166). - For those using VirtualBox, be sure to use the latest version of both VirtualBox and WSL 2. See the [related FAQ](./faq.yml#will-i-be-able-to-run-wsl-2-and-other-3rd-party-virtualization-tools-such-as-vmware--or-virtualbox-). -- If you rely on a Linux distribution to have an IP address in the same network as your host machine, you may need to set up a workaround in order to run WSL 2. WSL 2 is running as a hyper-v virtual machine. This is a change from the bridged network adapter used in WSL 1, meaning that WSL 2 uses a Network Address Translation (NAT) service for its virtual network, instead of making it bridged to the host Network Interface Card (NIC) resulting in a unique IP address that will change on restart. To learn more about the issue and workaround that forwards TCP ports of WSL 2 services to the host OS, see [WSL GitHub repository issue 4150, NIC Bridge mode (TCP Workaround)](https://github.com/microsoft/WSL/issues/4150). +- If you rely on a Linux distribution to have an IP address in the same network as your host machine, you may need to set up a workaround in order to run WSL 2. WSL 2 is running as a Hyper-V virtual machine. This is a change from the bridged network adapter used in WSL 1, meaning that WSL 2 uses a Network Address Translation (NAT) service for its virtual network, instead of making it bridged to the host Network Interface Card (NIC) resulting in a unique IP address that will change on restart. To learn more about the issue and workaround that forwards TCP ports of WSL 2 services to the host OS, see [WSL GitHub repository issue 4150, NIC Bridge mode (TCP Workaround)](https://github.com/microsoft/WSL/issues/4150). > [!NOTE] > Consider trying the VS Code [Remote WSL Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) to enable you to store your project files on the Linux file system, using Linux command line tools, but also using VS Code on Windows to author, edit, debug, or run your project in an internet browser without any of the performance slow-downs associated with working across the Linux and Windows file systems. [Learn more](tutorials/wsl-vscode.md). ## WSL in the Microsoft Store -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 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`. +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 index ac3202b0..06ea5c10 100644 --- 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/19/2024 +ms.date: 02/05/2025 ms.topic: article --- @@ -45,7 +45,32 @@ If you see that you are near to reaching the available amount of disk space allo ## How to expand the size of your WSL 2 Virtual Hard Disk -To expand the VHD size for a Linux distribution beyond the **default 1TB maximum** amount of allocated disk space, follow the steps below. *(For earlier WSL releases that have not yet been updated, this max default may be set to 512GB or 256GB).* +To expand the VHD size for a Linux distribution beyond the default 1TB maximum amount of allocated disk space, you can use the `wsl --manage` command or follow the manual steps below. (Earlier WSL releases max default may be set to 512GB or 256GB). + +### Expand VHD size using `wsl --manage` + +The `wsl --manage` command is only available to WSL releases 2.5 and higher. + +To resize the allocated space on your virtual disk: + +1. Terminate all WSL instances using the command `wsl.exe --shutdown` + +2. Run `wsl --manage --resize `. Supported memory strings are of the form `B/M/MB/G/GB/T/TB`. Decimal values are currently unsupported (e.g. `2.5TB`). + +Output should look similar to the following: + +```bash +e2fsck 1.46.5 (30-Dec-2021) +Pass 1: Checking inodes, blocks, and sizes +resize2fs 1.46.5 (30-Dec-2021) +The operation completed successfully. +``` + +The virtual drive (ext4.vhdx) for this Linux distribution has now successfully been expanded to the new size. + +### Manual expansion + +To expand the VHD size for a Linux distribution using manual steps: 1. Terminate all WSL instances using the command: `wsl.exe --shutdown` @@ -112,7 +137,7 @@ old_desc_blocks = 32, new_desc_blocks = 38 The filesystem on /dev/sdb is now 78643200 (4k) blocks long. ``` -The virtual drive (ext4.vhdx) for this Linux distribution has now successfully been expanded to the new size. +The virtual drive (ext4.vhdx) for this Linux distribution has now successfully been expanded to the new size. > [!IMPORTANT] > We recommend that you do not modify, move, or access the WSL related files located inside of your `AppData` folder using Windows tools or editors. Doing so could cause your Linux distribution to become corrupted. If you would like to access your Linux files from Windows, that is possible via the path `\\wsl$\\`. Open your WSL distribution and enter `explorer.exe .` to view that folder. To learn more, see the blog post: [Accessing Linux files from Windows](https://devblogs.microsoft.com/commandline/whats-new-for-wsl-in-windows-10-version-1903/#accessing-linux-files-from-windows). diff --git a/WSL/docfx.json b/WSL/docfx.json index 4938dfb2..fa78ed74 100644 --- a/WSL/docfx.json +++ b/WSL/docfx.json @@ -51,7 +51,10 @@ "ms.author": "mattwoj", "ms.reviewer": "crloewen", "searchScope": ["WSL"], - "adobe-target": true + "adobe-target": true, + "contributors_to_exclude": [ + "VSC-Service-Account" + ] }, "contributors_to_exclude": [ "VSC-Service-Account" diff --git a/WSL/networking.md b/WSL/networking.md index 9a5b09c0..f5f85a3c 100644 --- a/WSL/networking.md +++ b/WSL/networking.md @@ -64,7 +64,10 @@ If you are building a networking app (for example an app running on a NodeJS or If you want to access a networking app running on Windows (for example an app running on a NodeJS or SQL server) from your Linux distribution (ie Ubuntu), then you need to use the IP address of your host machine. While this is not a common scenario, you can follow these steps to make it work. -1. Obtain the IP address of your host machine by running this command from your Linux distribution: `ip route show | grep -i default | awk '{ print $3}'` +1. Obtain the IP address of your host machine by running this command from your Linux distribution: +```bash +ip route show | grep -i default | awk '{ print $3}'` +``` 2. Connect to any Windows server using the copied IP address. The picture below shows an example of this by connecting to a Node.js server running in Windows via curl. diff --git a/WSL/systemd.md b/WSL/systemd.md index 47590728..997ddf9c 100644 --- a/WSL/systemd.md +++ b/WSL/systemd.md @@ -1,7 +1,7 @@ --- title: Use systemd to manage Linux services with WSL description: Learn how to use systemd to manage Linux services with Windows Subsystem for Linux. -ms.date: 07/17/2024 +ms.date: 01/13/2025 ms.topic: article --- @@ -25,7 +25,10 @@ Systemd is [now the default for the current version of Ubuntu](https://canonical To enable systemd for any other Linux distributions running on WSL 2 (changing the default from using the systemv init): -1. Ensure that your WSL version is 0.67.6 or newer. (To check, run `wsl --version`. To update, run `wsl --update` or [download the latest version from the Microsoft Store](https://aka.ms/wslstorepage).) +1. Ensure that your WSL version is 0.67.6 or newer: + + - to check, run `wsl --version`; if the command throws `Invalid command line option: --version` error, you must update WSL; + - to update, run `wsl --update` or [download the latest version from the Microsoft Store](https://aka.ms/wslstorepage). 2. Open a command line for your Linux distribution and enter `cd /` to access the root directory, then `ls` to list the files. You will see a directory named "etc" that contains the WSL configuration file for the distribution. Open this file so that you can make an update with the Nano text editor by entering: `nano /etc/wsl.conf`. @@ -36,11 +39,19 @@ To enable systemd for any other Linux distributions running on WSL 2 (changing t systemd=true ``` -4. Exit the Nano text editor (Ctrl + X, select Y to save your change). You will then need to close the Linux distribution. You can use the command `wsl.exe --shutdown` in PowerShell to restart all WSL instances. + ![Enable systemd on WSL 2](media/systemd-enable.png) + +4. Exit the Nano text editor (Ctrl + X, type Y to save your change and confirm with the `enter` key). + +5. You will then need to close the Linux distribution. You can use the command `wsl.exe --shutdown` in PowerShell to restart all WSL instances. + +6. Once you restart the Linux distribution, systemd will be running. You can verify it by using the command `systemctl status` to show the _running_ state and the command `systemctl list-unit-files --type=service`, which will show the status of any services associated with your Linux distribution. -![Enable systemd on WSL 2](media/systemd-enable.png) +If your Linux distribution is Debian/Ubuntu/Kali Rolling, you should not only have installed the systemd package, but also make sure the systemd-sysv package is installed. -Once your Linux distribution restarts, systemd will be running. You can confirm using the command: `systemctl list-unit-files --type=service`, which will show the status of any services associated with your Linux distribution. +```bash +sudo apt-get update -y && sudo apt-get install systemd systemd-sysv -y +``` Learn more about [Advanced settings configuration in WSL](wsl-config.md), including the difference between the `wsl.conf` (distribution-specific) and `.wslconfig` (global) config files, how to update automount settings, etc. diff --git a/WSL/troubleshooting.md b/WSL/troubleshooting.md index 873bb80c..d8670722 100644 --- a/WSL/troubleshooting.md +++ b/WSL/troubleshooting.md @@ -63,7 +63,7 @@ You can also: 3. The WSL executable is only installed to the native system directory. When you’re running a 32-bit process on 64-bit Windows (or on ARM64, any non-native combination), the hosted non-native process actually sees a different System32 folder. (The one a 32-bit process sees on x64 Windows is stored on disk at \Windows\SysWOW64.) You can access the "native" system32 from a hosted process by looking in the virtual folder: `\Windows\sysnative`. It won’t actually be present on disk, mind you, but the filesystem path resolver will find it. - **Error: This update only applies to machines with the Windows Subsystem for Linux.** - - To install the Linux kernel update MSI package, WSL is required and should be enabled first. If it fails, it you will see the message: `This update only applies to machines with the Windows Subsystem for Linux`. + - To install the Linux kernel update MSI package, WSL is required and should be enabled first. If it fails, you will see the message: `This update only applies to machines with the Windows Subsystem for Linux`. - There are three possible reason you see this message: 1. You are still in old version of Windows which doesn't support WSL 2. See step #2 for version requirements and links to update. diff --git a/WSL/tutorials/wsl-database.md b/WSL/tutorials/wsl-database.md index 4d98ee99..df82fb60 100644 --- a/WSL/tutorials/wsl-database.md +++ b/WSL/tutorials/wsl-database.md @@ -119,7 +119,7 @@ Learn more in the MongoDB docs: ## Install Microsoft SQL Server -To install SQL Server on a Linux distribution run by WSL: [SQL Server on Linux](/sql/linux/sql-server-linux-overview). To work with Microsoft SQL Server databases in VS Code, try the [MSSQL extension](https://marketplace.visualstudio.com/items?itemName=ms-mssql.mssql). +[Quickstart: Install SQL Server and create a database on Windows Subsystem for Linux (WSL 2)](/sql/linux/quickstart-install-connect-wsl-2). ## Install SQLite diff --git a/WSL/wsl-config.md b/WSL/wsl-config.md index 848cbad3..5b50ada4 100644 --- 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: 09/25/2024 +ms.date: 12/16/2024 ms.topic: article ms.custom: seo-windows-dev adobe-target: true @@ -9,18 +9,15 @@ adobe-target: true # Advanced settings configuration in WSL -The [wsl.conf](#wslconf) and [.wslconfig](#wslconfig) files are used to configure advanced settings options, on a per-distribution basis (`wsl.conf`) and globally across all WSL 2 distributions (`.wslconfig`). This guide will cover each of the settings options, when to use each file type, where to store the file, sample settings files and tips. +The [`wsl.conf`](#wslconf) and [`.wslconfig`](#wslconfig) files are used to configure advanced settings in WSL that will be applied [on start up of the WSL VM](#the-8-second-rule-for-configuration-changes). `wsl.conf` is used to apply settings on a per WSL distro basis, and `.wslconfig` is used to apply global settings to WSL. You can read more about the differences below. -## What is the difference between wsl.conf and .wslconfig? +| Aspect | `.wslconfig` | `wsl.conf` | +|:---|:---|:---| +| Scope | General settings that apply to all of WSL | Settings for WSL distributions only | +| Configures | Feature enablement in WSL, settings for the virtual machine powering WSL 2 (RAM, kernel to boot, number of CPUs, etc.) | Distribution settings in WSL such as boot options, DrvFs automounts, networking, interoperability with the Windows system, systemd usage, and default user | +| Location | `%UserProfile%\.wslconfig`, outside of a WSL distribution | `/etc/wsl.conf`, while inside a WSL distribution | -You can configure the settings for your installed Linux distributions that will automatically be applied every time you launch WSL in two ways, by using: - -- **[.wslconfig](#wslconfig)** to configure **global settings** across all installed distributions running on WSL 2. -- **[wsl.conf](#wslconf)** to configure **local settings** per-distribution for each Linux distribution running on WSL 1 or WSL 2. - -Both file types are used for configuring WSL settings, but the location where the file is stored, the scope of the configuration, the type of options that can be configured, and the version of WSL running your distribution all impact which file type to choose. - -WSL 1 and WSL 2 run with different architecture and will impact the configuration settings. WSL 2 runs as a lightweight virtual machine (VM), so uses virtualization settings that allow you to control the amount of memory or processors used (which may be familiar if you use Hyper-V or VirtualBox). [Check which version of WSL you are running.](./install.md#check-which-version-of-wsl-you-are-running) +Currently, all `.wslconfig` settings apply only to WSL 2 distributions. Learn [how to check which version of WSL you are running](./install.md#check-which-version-of-wsl-you-are-running). ## The 8 second rule for configuration changes @@ -244,7 +241,7 @@ 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. | +|`autoMemoryReclaim`| string | `dropCache` | 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. | |`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. |