Skip to content

Commit

Permalink
docs: add guide to setup windows machine for WSL
Browse files Browse the repository at this point in the history
Add guide to setup windows machine for running our
integration tests on WSL instances
  • Loading branch information
lucasmoura committed Feb 7, 2024
1 parent 2a485dc commit 043550b
Show file tree
Hide file tree
Showing 9 changed files with 194 additions and 0 deletions.
194 changes: 194 additions & 0 deletions dev-docs/howtoguides/how_to_setup_windows_machine_for_wsl_testing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
# How to set up a Windows machine for WSL testing

To run our integration tests on Windows Subsystem for Linux (WSL) instances, we need to first set up
a Windows machine that will allow us to launch the WSL instances. After that, we also need to set up
an OpenSSH server so we can run SSH commands on the Windows machine.

This guide presents all the necessary steps for the set up, from launching the Windows 11 Pro
image in Azure to testing if WSL is correctly working on the machine.

## Launching the image on Azure

When launching the Windows instance on Azure, there are a few configurations that need to be performed,
otherwise we will not be able to launch WSL instances.

First of all, name the machine as `wsl-test`. Currently, this is the name we expect on the
integration tests.

After that, select the `Windows 11` image and mark the `Security Type` as *Standard*.
![](windows-security-type.png)

The alternative "Trusted Launch" [doesn't support Nested Virtualization](https://learn.microsoft.com/en-us/azure/virtual-machines/trusted-launch#unsupported-features),
required to run WSL.

Set a username and password for the VM. Please set the username as *ubuntu*.
We will use this account setting to manually log into the machine to run some commands there directly.
![](windows-ssh-setup.png)

Also, remember to also select the SSH inbound port for the machine
![](windows-setup-port.png)

Finally, you will need to check this checkbox here:
![](windows-license-check.png)

We have already confirmed with the WSL team that our Azure accounts have the proper license to
launch the Windows machine.


## Configure Bastion to log into the machine

To log into the machine and access its GUI, you need to set up Bastion.
After launching the machine, go for the *Connect via Bastion* option:

![](windows-bastion.png)

![](windows-deploy-bastion.png)

After deploying the Bastion, you just need to present your username and password to log into the
machine.

## Configuring Hyper-V

After logging into the machine through Bastion, you need to configure Hyper-V by following
this [tutorial](https://learn.microsoft.com/en-us/azure/lab-services/how-to-enable-nested-virtualization-template-vm-using-script?tabs=powershell)

## Installing winget

Each WSL Ubuntu distro has a dedicated installer in the Microsoft store. Therefore, before launching
any WSL instance, we need to install the installers first. To achieve that, we need to configure
**winget**.

To install it on the machine, follow this [tutorial](https://winget.pro/winget-install-powershell/)

```
Note that you can paste the commands in Bastion by using the clipboard feature that can be found
under this arrow:
```

![](windows-bastion-clipboard.png) ![](windows-bastion-clipboard-paste.png)

```
Finally, if you see the following error during installation, restart the machine first:
Add-AppxPackage : Deployment failed with HRESULT: 0x80073D02, The package could not be installed
because resources it modifies are currently in use.
```

## Installing WSL

To install WSL, just run the following command, as an administrator, on powershell:

```console
$ wsl --install
```

After that, we need to update WSL to the pre-release version by running:

```console
$ wsl --update --pre-release
```


```{note}
We are installing the pre-release version because it allow us to directly run wsl commands
through SSH. Once that fix is officially release, we will no longer need to install the
pre-release version.
```

Now, install a Bionic instance to test the whole WSL set up is working as expected:

```console
$ winget install --name "Ubuntu 18.04 LTS" --accept-source-agreements --accept-package-agreements --silent
```

Now, create the instance with:

```console
$ & ubuntu1804.exe install --root
```

After that, just test to see if we can run commands on the WSL instance:

```console
$ wsl -d Ubuntu-18.04 --exec lsb_release -a
```

## Installing OpenSSH server

To install OpenSSH server, follow these steps:

1) Open *Settings*
2) Go to *System*
3) Go to *Optional Features*
4) Go to *Add an optional feature*
5) Search for *ssh*
6) Install OpenSSH Server

After installing the Service, open PowerShell and launch it by running:

```console
$ Start-Service sshd
```

And set it to automatically start after boot:

```console
$ Set-Service -Name sshd -StartupType 'Automatic'
```

### Configure the SSH keys

We need to add a SSH public key into the Windows machine.

To do that, follow these steps:

1) Create a public key to be used in the Windows machine (You can also reuse an existing key if you want to)

2) Set the **UACLIENT_BEHAVE_WSL_IP_ADDRESS** environment variable with the Windows machine IP address.
This variable will be used in the integration test, but we will already use it in one of the
following steps.

2) Send the public key to the Windows machine:

```console
$ scp PUB_KEY_PATH ubuntu@$UACLIENT_BEHAVE_WSL_IP_ADDRESS:C:\\ProgramData\\ssh
```

3) SSH into the Windows machine. Note that this SSH will ask you for the password you have set up during the Windows image creation.
4) Run the following commands:

```console
$ cd %programdata%/ssh
```

```console
$ type PUB_KEY_NAME >> administrators_authorized_keys
```

```console
$ icacls administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"
```

Now test SSH into the machine using your private key

## Configure the machine for automatic login

To properly run **winget** commands after a machine reboot, a user
needs to be already logged into the machine. To automate that process,
follow this [tutorial](https://learn.microsoft.com/en-us/troubleshoot/windows-server/user-profiles-and-logon/turn-on-automatic-logon#use-registry-editor-to-turn-on-automatic-logon)

Note that you also need to manually create the **DefaultUserName** and **DefaultPassword** files.

## Running the integration test

After this set up, you should be able to use that machine to run the WSL tests automatically.
Before running a WSL test, remember to set the following environment variables:

* **UACLIENT_BEHAVE_WSL_IP_ADDRESS**
* **UACLIENT_BEHAVE_WSL_PRIVKEY_PATH**
* **UACLIENT_BEHAVE_WSL_PUBKEY_PATH**

Note that this variables must be set on our local machine. The integration test setup will use them
to stablish the connection with the Windows host machine to create the WSL instances the tests will
run on.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added dev-docs/howtoguides/windows-bastion.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added dev-docs/howtoguides/windows-deploy-bastion.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added dev-docs/howtoguides/windows-license-check.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added dev-docs/howtoguides/windows-security-type.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added dev-docs/howtoguides/windows-setup-port.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added dev-docs/howtoguides/windows-ssh-setup.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 043550b

Please sign in to comment.