Gentoo in WSL

From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.

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 path /etc/wsl.conf contains settings for specific Linux distributions (used in various sections below). This file supports four sections: automount, network, interop, and user. However, some settings, such as adjusting memory, number of processors, swap, and host port-forwarding need to be configured within a .wslconfig file in the Windows user's home directory (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.

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 Tarball

The most common way to load a WSL distribution is by installing it using the Microsoft Store, and more specifically, by issuing a command such as wsl --install -d <Distribution Name>. Run wsl --list --online to see the available distributions. As Gentoo is not included in this list (as of writing), a more manual approach is used. A stage 3 tarball is used to import a basic Gentoo filesystem. This is similar to a bare-metal installation, where the tarball 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 Tarball.
  1. WSL supports x64 and Arm CPUs. Download the appropriate tarball from the Gentoo downloads page.
  2. Unpack the tarball 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 your downloaded and unpacked tarball):
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 tarball
  • --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 tarball 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).

Recommended setup steps

In general, following the Installation Handbook can be used as per usual (post tarball import). 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). Some features, such as the init system (see below) and timezone (chrony), can be customized. You can customize your kernel, but this is not discussed in this article. The following sections should be used to finalize the installation process:

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.

Per-Distribution WSL Config

The per-distribution file /etc/wsl.conf and global configuration file %UserProfile%\.wslconfig are used to configure advanced settings options. WSL1 and WSL2 can both be configured in /etc/wsl.conf. The file is modelled after ini syntax. The sections below illustrate a variety of options that can be modified in these files. As an example:

FILE /etc/wsl.confExample per-distribution configuration
# Automatically mount Windows drive when the distribution is launched
[automount]

# 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 directory where fixed drives will be automatically mounted. This example changes the mount location, so your C-drive would be /c, rather than the default /mnt/c. 
root = /

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

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

# 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 you can create your own (ie. nameserver 1.1.1.1).
[network]
hostname = DemoHost
generateHosts = false
generateResolvConf = false

# 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.
[interop]
enabled = false
appendWindowsPath = false

# Set the user when launching a distribution with WSL.
[user]
default = DemoUser

# Set a command to run when a new WSL instance launches. This example starts the Docker container service.
[boot]
command = service docker start

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

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.

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 a WSL shutdown under Windows:

PS >wsl --shutdown

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

For Systemd, add:

FILE /etc/wsl.confRun systemd on WSL start
[boot]
systemd=true

In a similar way, shutdown and restart WSL to use systemd in WSL.

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. Under a Gentoo client (WSL) distribution, the server is not automatically recognized. To allow for graphical programs, it is necessary to remove the default X11 domain socket, and link to the WSLg socket instead:

root #rm -r /tmp/.X11-unix && ln -s /mnt/wslg/.X11-unix /tmp/.X11-unix

To verify, users can run a graphical program such as x11-apps/xeyes to confirm.

Note
The X11 domain socket created in this way is not permanent (issue). In order to make this permanent, one solution is to add this command to /etc/wsl.conf:
FILE /etc/wsl.confPersist X11 domain socket to enable graphical programs
[boot]
command = "rm -r /tmp/.X11-unix && ln -s /mnt/wslg/.X11-unix /tmp/.X11-unix"

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 your 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

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.).
Retrieved from "https://wiki.gentoo.org/index.php?title=Gentoo_in_WSL&oldid=1256773"