From b3adfea838a99453d133e530450159ccf614317d Mon Sep 17 00:00:00 2001 From: Patrick Lang Date: Feb 28 2025 22:37:55 +0000 Subject: [PATCH 1/5] Add TOC entry for WSL --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 3c92acc..0cefa03 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1 +1,2 @@ * xref:faq.adoc[FAQ] +* xref:wsl.adoc[Windows Subsystem for Linux] \ No newline at end of file From c1ac32384c5645f466097d6e552b365855848956 Mon Sep 17 00:00:00 2001 From: Patrick Lang Date: Feb 28 2025 22:38:22 +0000 Subject: [PATCH 2/5] Start WSL doc from wiki content --- diff --git a/modules/ROOT/pages/wsl.adoc b/modules/ROOT/pages/wsl.adoc new file mode 100644 index 0000000..7557155 --- /dev/null +++ b/modules/ROOT/pages/wsl.adoc @@ -0,0 +1,104 @@ += Fedora in Windows Subsystem for Linux + + +Fedora 42 introduced a new image for use with https://learn.microsoft.com/en-us/windows/wsl/[Windows Subsystem for Linux] (commonly referred to as WSL). This will allow users to have a simple, easy to set up Fedora environment for development and testing use. + +Multiple distributions may be run side by side in different namespaces, sharing the same kernel. Conceptually, the workflow is similar to a container, but it has been optimized to support an interactive Linux development & testing. WSL manages a lightweight VM with Wayland, PulseAudio, and some extra filesystem mounts provided. The user's choice of distro, such as Fedora, is run in an isolated namespace with its own root image. Filesystem state, including the root filesystem and home directories are also preserved between uses. + +The Fedora changes are fully described at [[Changes/FedoraWSL]]. It is similar to the cloud and container images, but some developer-focused packages such as manual pages, wget, and vim have been preinstalled. Some changes specific to WSL for X11 and Wayland compatibility have also been preconfigured. + + +== Prerequisites + +* Windows 11 (recommended), amd64 or arm64. Windows 10 may work, but is not a focus as it will be [https://www.microsoft.com/en-us/windows/end-of-support end-of-life soon] +* Virtualization extensions must be available. If you are testing in a VM - be sure this is enabled in your VM settings. Some cloud services restrict this to specific instance types. + + +=== Install WSL on Windows 11 + +Microsoft has full instructions on setting up WSL at https://learn.microsoft.com/en-us/windows/wsl/install[WSL Install]. A summary follows. + +Setting up WSL is pretty simple. `wsl --install` will enable the hypervisor prerequisites, and prompt for reboot if needed. + +[source] +---- +wsl --install +Downloading: Windows Subsystem for Linux 2.4.10 +Installing: Windows Subsystem for Linux 2.4.10 +Windows Subsystem for Linux 2.4.10 has been installed. +Installing Windows optional component: VirtualMachinePlatform + +Deployment Image Servicing and Management tool +Version: 10.0.26100.1150 + +Image Version: 10.0.26100.2894 + +Enabling feature(s) +[==========================100.0%==========================] +The operation completed successfully. +The requested operation is successful. Changes will not be effective until the system is rebooted. +The requested operation is successful. Changes will not be effective until the system is rebooted. +---- + +After rebooting, you can proceed to the next section to install Fedora as a distribution in WSL. + + +=== Installing Fedora in WSL + +==== Downloading the Fedora WSL tarball + +The recommended build can be fetched from https://kojipkgs.fedoraproject.org/packages/Fedora-WSL-Base/[Koji under packages/Fedora-WSL-Base/] for `amd64` and `aarch64`. + + +==== Installing Fedora with wsl.exe + +First, check the version of WSL you are using by running `wsl.exe --version`. Follow the steps below based on the version. + +*For WSL versions 2.4.4+:* + +. From the command line, install the tarball with `wsl --install --from-file .\path\to\Fedora.tar.xz` + +[source] +---- +wsl --install --from-file .\Fedora-WSL-Base-42.20250204.2206.x86_64.tar.xz +Installing: .\Fedora-WSL-Base-42.20250204.2206.x86_64.tar.xz +Distribution successfully installed. It can be launched via 'wsl.exe -d Fedora' +---- + +. Enter the environment by running `wsl -d Fedora` + +. When prompted, provide a username. This will be the default user, and it will be added to the groups for `sudo` usage + +*For WSL versions prior to 2.4.4:* + +(These steps assume you are using PowerShell) + +. Make a directory for the Fedora distribution with `mkdir $ENV:LOCALAPPDATA\WSL\Fedora` +. Import the WSL tarball with `wsl --import Fedora $ENV:LOCALAPPDATA\WSL\Fedora .\Path\To\Fedora.x86_64-Rawhide.tar.xz` +. Enter the environment with `wsl -d Fedora -u root` +. Manually run `/usr/libexec/wsl/oobe.sh` to create the default user +. `exit` the environment logged in as root +. Enter the environment as the newly created user with `wsl -d Fedora -u ` + + +== Reporting bugs + +Perhaps you've found an already-reported bug. Please look at: + +* https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&classification=Fedora&component=wsl-setup&product=Fedora&product=Fedora%20EPEL[Bugzilla - component: wsl-setup] - for initial user creation & WSL configurations. +* https://pagure.io/fedora-kiwi-descriptions/issues[fedora-kiwi-descriptions issues] - for feedback & issues related to the preinstalled packages in the WSL package. + + +* When filing the bug, it's very helpful to include: +** WSL & Windows versions, which you can retrieve with wsl.exe --version +** exact steps you've performed (and whether you can reproduce it again) +** screenshots or videos, if applicable +** system journal (log), which you can retrieve by `journalctl -b > journal.txt` +** all output in a terminal, if started from a terminal +** your system description + + +== Source code + +Package sources are at: https://src.fedoraproject.org/rpms/wsl-setup[rpms/wsl-setup] + From 8ec3cf004453e0806defbb69d5d29a2df551847f Mon Sep 17 00:00:00 2001 From: Patrick Lang Date: Mar 21 2025 05:04:32 +0000 Subject: [PATCH 3/5] doc: update URL and steps based on feedback --- diff --git a/modules/ROOT/pages/wsl.adoc b/modules/ROOT/pages/wsl.adoc index 7557155..965c018 100644 --- a/modules/ROOT/pages/wsl.adoc +++ b/modules/ROOT/pages/wsl.adoc @@ -18,7 +18,7 @@ The Fedora changes are fully described at [[Changes/FedoraWSL]]. It is similar t Microsoft has full instructions on setting up WSL at https://learn.microsoft.com/en-us/windows/wsl/install[WSL Install]. A summary follows. -Setting up WSL is pretty simple. `wsl --install` will enable the hypervisor prerequisites, and prompt for reboot if needed. +`wsl --install` will enable the hypervisor prerequisites, and prompt for reboot if needed. [source] ---- @@ -47,7 +47,9 @@ After rebooting, you can proceed to the next section to install Fedora as a dist ==== Downloading the Fedora WSL tarball -The recommended build can be fetched from https://kojipkgs.fedoraproject.org/packages/Fedora-WSL-Base/[Koji under packages/Fedora-WSL-Base/] for `amd64` and `aarch64`. +The latest build for Fedora 42 beta may be fetched from https://download.fedoraproject.org/pub/fedora/linux/releases/test/42_Beta/Container/x86_64/images/Fedora-WSL-Base-42_Beta-1.4.x86_64.tar.xz[download.fedoraproject.org] for: +- https://download.fedoraproject.org/pub/fedora/linux/releases/test/42_Beta/Container/x86_64/images/Fedora-WSL-Base-42_Beta-1.4.x86_64.tar.xz[amd64] +- https://download.fedoraproject.org/pub/fedora/linux/releases/test/42_Beta/Container/aarch64/images/Fedora-WSL-Base-42_Beta-1.4.aarch64.tar.xz[aarch64] ==== Installing Fedora with wsl.exe From 1300b8ed20e9452a027960705f70b68022771128 Mon Sep 17 00:00:00 2001 From: Patrick Lang Date: Mar 21 2025 05:17:31 +0000 Subject: [PATCH 4/5] Add checksum links --- diff --git a/modules/ROOT/pages/wsl.adoc b/modules/ROOT/pages/wsl.adoc index 965c018..69cf199 100644 --- a/modules/ROOT/pages/wsl.adoc +++ b/modules/ROOT/pages/wsl.adoc @@ -47,10 +47,11 @@ After rebooting, you can proceed to the next section to install Fedora as a dist ==== Downloading the Fedora WSL tarball -The latest build for Fedora 42 beta may be fetched from https://download.fedoraproject.org/pub/fedora/linux/releases/test/42_Beta/Container/x86_64/images/Fedora-WSL-Base-42_Beta-1.4.x86_64.tar.xz[download.fedoraproject.org] for: -- https://download.fedoraproject.org/pub/fedora/linux/releases/test/42_Beta/Container/x86_64/images/Fedora-WSL-Base-42_Beta-1.4.x86_64.tar.xz[amd64] -- https://download.fedoraproject.org/pub/fedora/linux/releases/test/42_Beta/Container/aarch64/images/Fedora-WSL-Base-42_Beta-1.4.aarch64.tar.xz[aarch64] +The latest build for Fedora 42 beta may be fetched from https://download.fedoraproject.org/pub/fedora/linux/releases/test/42_Beta/Container/[download.fedoraproject.org] for: +- https://download.fedoraproject.org/pub/fedora/linux/releases/test/42_Beta/Container/x86_64/images/Fedora-WSL-Base-42_Beta-1.4.x86_64.tar.xz[amd64], https://download.fedoraproject.org/pub/fedora/linux/releases/test/42_Beta/Container/x86_64/images/Fedora-Container-images-42_Beta-1.4-x86_64-CHECKSUM[CHECKSUM] +- https://download.fedoraproject.org/pub/fedora/linux/releases/test/42_Beta/Container/aarch64/images/Fedora-WSL-Base-42_Beta-1.4.aarch64.tar.xz[aarch64], https://download.fedoraproject.org/pub/fedora/linux/releases/test/42_Beta/Container/aarch64/images/Fedora-Container-images-42_Beta-1.4-aarch64-CHECKSUM[CHECKSUM] +Checksums may be verified using the same steps used to validate other Fedora images as described at https://docs.fedoraproject.org/en-US/fedora/latest/preparing-boot-media/#sect-verifying-images[Verifying checksums on Windows systems]. ==== Installing Fedora with wsl.exe From 7b58b7151a03ad79add2e6fc5a8479d928629aff Mon Sep 17 00:00:00 2001 From: Patrick Lang Date: Mar 21 2025 05:24:57 +0000 Subject: [PATCH 5/5] Add Windows Server install notes --- diff --git a/modules/ROOT/pages/wsl.adoc b/modules/ROOT/pages/wsl.adoc index 69cf199..ec28c26 100644 --- a/modules/ROOT/pages/wsl.adoc +++ b/modules/ROOT/pages/wsl.adoc @@ -14,7 +14,9 @@ The Fedora changes are fully described at [[Changes/FedoraWSL]]. It is similar t * Virtualization extensions must be available. If you are testing in a VM - be sure this is enabled in your VM settings. Some cloud services restrict this to specific instance types. -=== Install WSL on Windows 11 +=== Install WSL on Windows 11, Windows Server 2022, or Windows Server 2025 + +> Windows Server 2022 needs to be updated to KB5014678 (OS Build 20348.768) or later first before installing WSL2. Please see the blog post https://devblogs.microsoft.com/commandline/wsl-2-distros-are-now-supported-on-windows-server/[WSL 2 distros are now supported on Windows Server] for more details. Microsoft has full instructions on setting up WSL at https://learn.microsoft.com/en-us/windows/wsl/install[WSL Install]. A summary follows.