Using WSL2

This article documents the setup of WSL2 for local and remote development. Local development is supported by Docker. For remote development, WSL2 effectively acts as a bridge. Remote development is done via SSH with support for X11 forwarding. This allows X11 applications to be run on the remote host and display on the Windows desktop.

1. Install WSL2

Install WSL2
Install Ubuntu from the Microsoft Store
Convert to WSL2
```
wsl --set-version Ubuntu 2
```
Verify WSL version
```
wsl --list --verbose
```

2. Install Docker

The following will make Docker available from WSL2.

Download the latest stable release
Follow the Docker WSL2 instructions

3. Install Windows Terminal

Install Windows Terminal from the Microsoft Store⁠[1]
Open Windows Terminal

Edit Settings

profile.json

// To view the default settings, hold "alt" while clicking on the "Settings" button.
// For documentation on these settings, see: https://aka.ms/terminal-documentation
{
    "$schema": "https://aka.ms/terminal-profiles-schema",

    "defaultProfile": "{2c4de342-38b7-51cf-b940-2309a097f518}",

    // Simplify copying
    "copyOnSelect": true,

    // Disable multi-line paste warning
    "multiLinePasteWarning": false,

    // Removed the following characters from the default list to allow double clicking
    // of paths and URLs to select and copy them: '/', '\', '.', ':'
    "wordDelimiters": " ()\"',;<>~!@#$%^&*|+=[]{}~?\u2502",

    "profiles": {
        "defaults": {
            // Make the cursor easier to find
            "cursorShape": "emptyBox",

            // Hide everything by default
            "hidden": true,
        },
        "list": [
            {
                "guid": "{2c4de342-38b7-51cf-b940-2309a097f518}",
                "hidden": false,
                "name": "WSL2",

                // Start WSL like any other profile (i.e. don't use "source")
                // Start in Linux home directory instead of Windows home directory
                "commandline": "wsl.exe ~",

                // WORKAROUND: The right padding is more than it should be.
                // Making it 0 seems to be equivalent to 8 on the left.
                // Also hide the scrollbar so that it doesn't contribute to the padding.
                "padding": "8, 8, 0, 0",
                "scrollbarState": "hidden",
            },
        ]
    },

    // Add any keybinding overrides to this array.
    // To unbind a default keybinding, set the command to "unbound"
    "keybindings": [
        // Make paste work like Linux
        { "command": "paste", "keys": [ "shift+insert" ] }
    ]
}

4. Setup SSH X11 Forwarding

Install VcXsrc
Run XLaunch
1. Set display number to 0
2. Disable access control
3. Save configuration
4. Open saved configuration to run VcXsrc
Open a WSL terminal
Configure $DISPLAY by adding the following to your ~/.bashrc
```
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0.0
```
This sets the DISPLAY to the IP address of the Windows host.

Configure SSH

~/.ssh/config

Host *
    User <remote-username>
    ForwardX11 yes
    ForwardX11Trusted yes
    ForwardAgent yes

Test
1. SSH
```
ssh remote-host
```
2. Run an X11 application
```
xlogo
```
  It should display on your Windows desktop.

5. Setup Pageant

Download wsl2-ssh-pageant

cd ~/.ssh/
curl -LO https://github.com/BlackReloaded/wsl2-ssh-pageant/releases/download/v1.0.0/wsl2-ssh-pageant.exe
chmod +x wsl2-ssh-pageant.exe

Install socat
```
sudo apt-get install socat
```

Add wsl2-ssh-pageant to your ~/.bashrc

export SSH_AUTH_SOCK=$HOME/.ssh/agent.sock
ss -a | grep -q $SSH_AUTH_SOCK
if [ $? -ne 0 ]; then
        rm -f $SSH_AUTH_SOCK
        setsid nohup socat UNIX-LISTEN:$SSH_AUTH_SOCK,fork EXEC:$HOME/.ssh/wsl2-ssh-pageant.exe >/dev/null 2>&1 &
fi

6. SSH into WSL2

Scott Hanselman has a great article on accessing WSL2 via Windows OpenSSH server titled THE EASY WAY how to SSH into Bash and WSL2 on Windows 10 from an external machine. However, it only supports Bash. It doesn’t support alternative shells like Zsh.

The trick is to change the Windows OpenSSH server default shell to C:\Windows\System32\wsl.exe instead of C:\Windows\System32\bash.exe. This will use whatever shell WSL2 has been configured to use.

So instead of

New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell -Value "C:\WINDOWS\System32\bash.exe" -PropertyType String -Force

Use

New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell -Value "C:\WINDOWS\System32\wsl.exe" -PropertyType String -Force

Windows Terminal v1.4 as of this writing. ↩