Gentoo in WSL

From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.
This article is a stub. Please help out by expanding it - how to get started.
Resources

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 WSL2 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.

Installing WSL on Windows

WSL needs to be installed before Gentoo can be imported and set up in it. Use of WSL version 2 is assumed in this article, though the instructions here might apply to version 1 as well.

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

Importing a stage 3 tarball into WSL

A stage 3 tarball is required to install Gentoo in WSL. Download the appropriate tarball for system architecture at the Gentoo downloads page.

A command like the following one, which should be run in Windows PowerShell, imports a Gentoo stage 3 tarball into WSL.

PS >wsl --import Gentoo C:\Users\Larry\AppData\Local\WSL\Gentoo\ .\stage3-amd64-openrc-20211121T170545Z.tar --version 2

Some arguments in this command that can or should be changed are:

  • Gentoo: The name of the Linux distribution that will show up in various wsl commands' output
  • C:\Users\Larry\AppData\Local\WSL\Gentoo\: The path where the WSL files pertaining to Gentoo are to be stored
  • .\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)
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.

Configuring the Gentoo distribution imported into WSL

Initial setup

After the stage 3 import, the resulting Gentoo system in WSL still requires some additional initial setup steps. First, enter the Gentoo distribution on WSL by using the command:

PS >wsl -d Gentoo

The system can be configured as desired by following the Installation Handbook for steps following installing stage 3. Some configurations — like init system, timezone, kernel, filesystem, networking, and bootloader — are not necessary as they are managed by WSL. Only the sections listed below are relevant on WSL; instructions in all other sections may be ignored.

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, please use /etc/portage/make.conf instead.

Now a basic Gentoo system setup in WSL should be achieved. The resulting Gentoo system could be used like if it was on the bare-metal: more packages can be installed, and it might even be possible to run GUI apps thanks to WSLg, a new WSL 2 feature.

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. It would be better if WSL would use a non-privileged user as default.

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.

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

Creating a new non-root user

A new non-root user in the wheel group needs to be created first; this is also what WSL prompts the user to do when one of the prepackaged distributions downloaded from the Microsoft Store is launched for the first time. Replace larry with a desired user name.

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

Specifying the default WSL user in the Windows Registry

Start the Registry Editor and navigate to HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss. Within the keys within Lxss, search for the one with a DistributionName string equal to what was used to install Gentoo. Within that key, look for a DWORD named DefaultUid. Create it if it's missing, then set it to the uid to use by default (usually 1000 for the first user created). Note that regedit defaults to hexadecimal for DWORDs; switch to decimal before punching in 1000 (or punch in 3e8).

Specifying the default WSL user in /etc/wsl.conf

Create a file called /etc/wsl.conf in the Gentoo system on WSL with the following contents.

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

Replace larry with the appropriate user name.

Exit Gentoo back to the shell, and then issue wsl --terminate Gentoo. The change in /etc/wsl.conf should then take effect the next time Gentoo is launched.

Tuning performance-related options specific to WSL 2

WSL 2 can be configured in ways such as adjusting the memory allocation since it essentially runs a Linux distribution in a virtual machine. Here is an example of configuring the virtual machine:

FILE /etc/wsl.confAllocate 8 GB RAM and 4 virtual processors to Gentoo on WSL 2
[wsl2]
memory=8GB
processors=4

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=1180095"