Gentoo in WSL

From Gentoo Wiki
Jump to:navigation Jump to:search
Translate this page
Other languages:

This page documents the process and some configuration tips to get Gentoo running on WSL (Windows Subsystem for Linux) - to effectively run Gentoo under Windows.

Since WSL uses a real Linux kernel running on top of a hypervisor, Linux is essentially run within Windows. Gentoo can run on top of WSL, too. Use of WSL version 2 is assumed in this article, though the instructions here might apply to version 1 as well.

Installing WSL

WSL needs to be enabled in Windows before Gentoo can be installed. Here, the --no-distribution flag prevents the default distribution (Ubuntu) from being installed by default (this can be left out, if desired).

PS >wsl --install --no-distribution

Please consult Microsoft's documentation for installing WSL on Windows 10 (build 19041 or above) or Windows 11 and older builds of Windows 10.

WSL global options

The .wslconfig file configures settings globally for all Linux distributions running with WSL 2. Sections include settings for RAM, swap, number of processors, and host port-forwarding. The file .wslconfig can be created in the Windows user's home directory if it does not exist (e.g. C:\Users\larry\.wslconfig). Here is an example of configuring WSL for these options:

FILE %UserProfile%\.wslconfigGlobal options
[wsl2]
# Uses the amount specified or the lesser of {8GB OR 50% of the available RAM}
memory=8GB

# see Windows System Information > System Summary > Processor to determine the number available
# Note: should not exceed half of RAM to avoid compilation OOM errors
processors=4

# allow port forwarding (on by default)
localhostforwarding=true

These settings will become important for post-install configuration below (compiler options, etc.). A more complete example of a global configuration file can be found here.

The per-distribution config (/etc/wsl.conf) will be discussed throughout the following sections.

Note
Distributions running as WSL 1 will not be affected by this configuration as they are not running as a virtual machine.

Importing Gentoo via stage 3 file

Although the most common way to load a WSL distribution is by installing it using the Microsoft Store, or by issuing a command such as wsl --install -d <Distribution Name>, a more manual approach is used for Gentoo (Gentoo is not included in the official distributions, as of writing - run wsl --list --online to see the available distributions). A stage 3 file is used to import a basic Gentoo filesystem. This is similar to a bare-metal installation, where the archive is unpacked in the soon-to-be mounted filesystem. Assuming WSL is installed and enabled as per the instructions above, the simplified steps are as follows:

Download, unpack, and import a stage 3 file.
  1. WSL supports x64 and Arm CPUs. Download the appropriate stage file from the Gentoo downloads page.
  2. Unpack the stage file using an appropriate tool (e.g. 7-zip - see note below).
  3. To import Gentoo, open an administrator shell and run wsl --import <Distro> <InstallLocation> <FileName>, replacing each parameter with the appropriate value. For example (replacing the file name with the downloaded and unpacked stage file):
PS >wsl --import Gentoo C:\Users\Larry\AppData\Local\WSL\Gentoo\ .\stage3-amd64-openrc-20211121T170545Z.tar --version 2
  • Gentoo: The label of the Linux distribution that will show up in various wsl commands' output (assumed to be "Gentoo" hereafter)
  • C:\Users\Larry\AppData\Local\WSL\Gentoo\: The path where the WSL files pertaining to Gentoo are to be stored (directory may need to be created first)
  • .\stage3-amd64-openrc-20211121T170545Z.tar: The path to the stage 3 file
  • --version 2: The WSL version being used for the imported distribution (which is 2 in this example - may not be required)
Note
The stage 3 file passed into the wsl command should have .tar file name extension. Stage archives on Gentoo mirrors are .xz archives, but they can be unpacked to produce the .tar file. On Windows, programs that can unpack .xz archives include 7-Zip.

Basic system and configuration

Initial run

After the stage 3 import, the resulting Gentoo system can be used immediately. Assuming the label given in the import step was "Gentoo", the following command can be used to load the system:

PS >wsl -d Gentoo

However, some additional steps are highly recommended (next section).

Installation Handbook: Recommended setup steps

The following sections of the Installation Handbook should be used to finalize the installation process of a minimal system (assuming an AMD64 architecture).

Note
Because configuration on WSL does not involve chrooting, whenever the handbook mentions a path that starts with /mnt/gentoo, that prefix should be dropped from the path. For example, when the handbook says /mnt/gentoo/etc/portage/make.conf, use /etc/portage/make.conf instead.


In general, the handbook can be used in its entirety, with minor (additional) caution. In particular, some configuration is not necessary for certain features to work immediately (e.g. networking) and some are not configurable as they are provided automatically or do not apply (e.g. filesystem, bootloader). Furthermore, the kernel can be customized, but this is not discussed in this article.

Setting up a non-root default user

When starting Gentoo in WSL, the root user will be used by default. This is neither secure nor preferable. To this, it is recommended that a non-root user is enabled and set as the default. The simplest way to set a default user is to create one (if one hasn't been created already):

root #useradd -m -G wheel larry
root #passwd larry

and adding the following lines to /etc/wsl.conf:

FILE /etc/wsl.confLog in as user larry when Gentoo is launched on WSL
[user]
default=larry

After configuring a default user, a root session can still be explicitly started by specifying a user in the wsl command. For example:

PS >wsl -u root -d Gentoo

There are alternative ways to specify the default user. Configuration specified in /etc/wsl.conf will be preserved when exporting/importing a distribution which makes it less suitable for creating templates. Specifying a default user in the Windows Registry will be lost on export/import and will need to be repeated if the instance is re-imported.

Note
Prior to Windows build 18980, an undocumented method to add a default user was accomplished by editing the Windows registry (see https://superuser.com/a/1506322/928571). This method is no longer required.

Per-Distribution WSL Config

The per-distribution file /etc/wsl.conf can be used to configure important settings for the newly unpacked Gentoo system. The file does not exist by default but can be easily created (e.g. touch /etc/wsl.conf). WSL1 and WSL2 can both be configured in /etc/wsl.conf. The file is modeled after ini syntax. The sections below illustrate a variety of options that can be modified in these files. Example file with defaults:

FILE /etc/wsl.confExample per-distribution configuration
[automount]
# https://learn.microsoft.com/en-us/windows/wsl/wsl-config#automount-settings
# Automatically mount Windows drive when the distribution is launched
# Set to true will automount fixed drives (C:/ or D:/) with DrvFs under the root directory set above. Set to false means drives won't be mounted automatically, but need to be mounted manually or with fstab.
enabled = true

# Sets the `/etc/fstab` file to be processed when a WSL distribution is launched.
mountFsTab = true

# Sets the directory where fixed drives will be automatically mounted. 
root = /mnt/

# DrvFs-specific options can be specified.  
options = "metadata,uid=1003,gid=1003,umask=077,fmask=11,case=off"


[network]
# https://learn.microsoft.com/en-us/windows/wsl/wsl-config#network-settings
# Network host settings that enable the DNS server used by WSL 2. This example changes the hostname, sets generateHosts to false, preventing WSL from the default behavior of auto-generating /etc/hosts, and sets generateResolvConf to false, preventing WSL from auto-generating /etc/resolv.conf, so that a custom nameserver can be used (ie. nameserver 1.1.1.1).
# hostname = (DEFAULT WINDOWS HOSTNAME)
generateHosts = true
generateResolvConf = true


[interop]
# https://learn.microsoft.com/en-us/windows/wsl/wsl-config#interop-settings
# Set whether WSL supports interop process like launching Windows apps and adding path variables. Setting these to false will block the launch of Windows processes and block adding $PATH environment variables.
enabled = true
appendWindowsPath = true


[user]
# https://learn.microsoft.com/en-us/windows/wsl/wsl-config#user-settings
# Set the user when launching a distribution with WSL. Default is `root`.
# default = larry


[boot]
# https://learn.microsoft.com/en-us/windows/wsl/wsl-config#boot-settings
# Set a command to run when a new WSL instance launches.

# To enable systemd, if the system Gentoo profile supports it, uncomment the following line:
# systemd = true

# Additional commands. e.g. Run OpenRC:
# command = /sbin/openrc default

See Advanced settings configuration in WSL for a full description of the options available for wsl.conf.

Init systems

OpenRC can be run on WSL start. Add the following to /etc/wsl.conf:

FILE /etc/wsl.confRun OpenRC on WSL start
[boot]
command = "/sbin/openrc default"

After stopping the WSL distro (assuming "Gentoo" as the label):

PS >wsl --terminate Gentoo

services can be enabled and run as per the usual openrc commands.

Note
To shutdown and terminate all processes, a more global command can be used: wsl --shutdown
Important
Users need to wait for WSL distributions to shutdown completely before configuration settings appear. Typically, this is about 8 seconds (see here for more detail).

For Systemd, add:

FILE /etc/wsl.confRun systemd on WSL start
[boot]
systemd=true
Note
If booting with systemd runs into errors, it may be because of systemd's first boot detection. This can be disabled with the following change:
FILE %UserProfile%\.wslconfigWorkaround for systemd
[wsl2]
kernelCommandLine = systemd.firstboot=0

In a similar way, shutdown WSL or terminate the running distribution, and launch the WSL distribution in the usual way (waiting a small amount of time before the restart - see note above).

WSL filesystems

By default, existing drives are automatically mounted using the drvfs driver. These drives can be accessed under the /mnt directory.

Note
Performance suffers when working in directories outside of WSL (e.g. /mnt/c/). Therefore, it's recommended that users use the WSL filesystem (e.g. their home directory ~/) instead (see File storage and performance across file systems).

To mount drives not recognized by Windows, read Mount a Linux disk in WSL 2. To mount a USB drive (already mounted on the Windows host), the current method uses usbip which uses the IP protocol to give WSL access to Windows-mounted USB drives. Further instructions can be accessed here.

Graphical programs using X11 or Wayland

Graphical programs can be run under WSL thanks to WSLg (Windows Subsystem for Linux GUI). The purpose of the project is to enable support for running Linux GUI applications (X11 and Wayland) on Windows. The WSLg "system distro" is a containerized Linux environment where the WSLg XServer, Wayland server and Pulse Audio sockets originate. WSLg exposes the DirectX 12 API through the device /etc/dxg and it directly communicates with the GPU on the Windows host. To enable this, enable d3d12 as the video card in /etc/portage/make.conf:

FILE /etc/portage/make.confd3d12 Video Card
VIDEO_CARDS="d3d12"

Then, update the system to enable the changes:

root #emerge --ask --verbose --update --deep --changed-use @world
Important
WSL 2 provides a Wayland compositor, mesa 3D acceleration, and PulseAudio. At this point these should work out of the box. It is not necessary to install an X server, Wayland compositor, any window/desktop managers, login managers, graphics drivers, or any audio drivers, even if asked to do so by the Handbook or software installation instructions. Simply use the appropriate USE flags and launch the software, and the audio and graphics will 'just work' with the Windows system. Installing unneeded drivers can cause breakage.

Once a Windows NVIDIA GPU driver is installed on the HOST system, CUDA becomes available within WSL 2. The CUDA driver installed on Windows host will be stubbed inside the WSL 2 as libcuda.so, therefore users must not install any NVIDIA GPU Linux driver within WSL 2. The user has to be very careful here as the default CUDA Toolkit comes packaged with a driver, and it is easy to overwrite the WSL 2 NVIDIA driver with the default installation.

Important
CUDA Support: To compile new CUDA applications, a CUDA Toolkit for Linux x86 is needed. CUDA Toolkit support for WSL is still in preview stage as developer tools such as profilers are not available yet. However, CUDA application development is fully supported in the WSL2 environment. Be particularly careful if installing CUDA ([1]).

Optional: Xwayland can be merged to allow older X11 apps to connect to the newer modern Wayland compositor exposed by WSL2 for better performance. Without this, X11 applications will default to using the older WSL backwards compatibility feature of X11 server translation which is also less secure (X11 applications can read and write each other's data).

To verify that the system recognizes the driver, install x11-apps/mesa-progs:

root #emerge --ask --verbose x11-apps/mesa-progs

The output of glxinfo -B 2>/dev/null | grep Device can be used to verify the name of the graphics card.

In Windows, GPU usage can be observed in Task Manager by running glxgears in the Gentoo system.

On a system with multiple GPUs, the desired GPU can be selected by setting the environment variable MESA_D3D12_DEFAULT_ADAPTER_NAME to a unique substring of its name (case insensitive). For example:

root #echo 'MESA_D3D12_DEFAULT_ADAPTER_NAME="nvidia"' > /etc/env.d/99d3d12
root #env-update

On systemd, the X11 socket in /tmp will be shadowed by its tmpfs upon mounting, resulting in hanging applications when trying to talk to X. This can be solved via tmpfiles.d:

root #echo 'L+ /tmp/.X11-unix - - - - /mnt/wslg/.X11-unix' > /etc/tmpfiles.d/wsl.conf

Troubleshooting

An error occurred mounting one of the file systems

If a new Gentoo installation on Windows 11 fails to start with this error message:

PS >wsl -d Gentoo
An error occurred mounting one of the file systems. Please run 'dmesg' for more details.

Then reinstall Gentoo using a nomultilib stage3 variant.

Segmentation fault in docker

If using a docker image with some old glibc distributions inside Gentoo in WSL, segmentation faults may occur. In most cases this happens because vsyscall is off by default. Workaround is to enable its emulation at global WSL configurationː

FILE %UserProfile%\.wslconfigEnable vsyscall emulation
[wsl2]
kernelCommandLine = vsyscall=emulate

Problems with network with active Cisco AnyConnect VPN

If the VPN has no routes to the internet (only intranet), then change VPN interface metrics after each reconnect. Otherwise all traffic from WSL will go to VPN interface. This can be done with the next command on Windowsː

PS >Get-NetAdapter | Where-Object {$_.InterfaceDescription -Match "Cisco AnyConnect"} | Set-NetIPInterface -InterfaceMetric 6000

No audio / Can not connect to ALSA

The WSLg component of WSL provides a PULSE_SERVER environment variable. It is only possible to push audio from WSL guest into Windows host through that socket. Ensure the variable PULSE_SERVER is set and the desired software to run was built with pulseaudio support. For example, MPV requires the pulseaudio USE flag to have audio playback from videos.

/usr/lib/wsl/lib/libcuda.so.1 is not a symbolic link

This error message may appear in the kernel log (dmesg or journalctl -kb --grep libcuda). This can be fixed with an administrator cmd with the following commands:

>C:
>cd %WINDIR%\System32\lxss\lib
>del libcuda.so
>del libcuda.so.1
>mklink libcuda.so libcuda.so.1.1
>mklink libcuda.so.1 libcuda.so.1.1

After completing these steps, dir libcuda.so libcuda.so.1 output should look like the following:

C:\Windows\System32\lxss\lib>dir libcuda.so libcuda.so.1
Directory of C:\Windows\System32\lxss\lib
 
03/15/2022 03:59 PM libcuda.so [libcuda.so.1.1]|
03/15/2022 04:00 PM libcuda.so.1 [libcuda.so.1.1]|

/proc/sys/fs/binfmt_misc/WSLInterop-late: Permission denied

Inside the VM:

root #echo ':WSLInterop:M::MZ::/init:PF' > /etc/binfmt.d/wsl.conf

After a reboot of the VM launching Windows executables from within the VM should work.

Windows programs not on PATH

By default, despite setting appendWindowsPath = true, the Gentoo baselayout will overwrite the provided PATH completely. To solve this, edit /etc/profile to preserve the initial PATH:

FILE /etc/profileProfile Config
# [...]

WSLPATH="$PATH"

# Load environment settings from profile.env, which is created by
# env-update from the files in /etc/env.d
if [ -e /etc/profile.env ] ; then
        . /etc/profile.env
fi

export PATH="$PATH:$WSLPATH"
unset WSLPATH

# [...]

The first line and the last two lines of this block need to be added around the pre-existing middle block at the top of /etc/profile. Zsh users should perform the change in /etc/zsh/zprofile.

See also

  • Prefix — enables the power of Gentoo and Portage on other distributions and/or operating systems (Microsoft Windows via Cygwin, Android via Termux, etc.).

External resources

Retrieved from "https://wiki.gentoo.org/index.php?title=Gentoo_in_WSL/en&oldid=1305957"