How to install and configure UP4W

1. Check that you meet the prerequisites

To install and configure UP4W you will need:

How do I get an Ubuntu Pro token?

  1. Visit the Ubuntu Pro page to get a subscription.

See more: Ubuntu | Ubuntu Pro > Subscribe. If you choose the personal subscription option (Myself), the subscription is free for up to 5 machines.

  1. Visit your Ubuntu Pro Dashboard to retrieve your subscription token.

  • (Only if you want to use UP4W with Landscape:)
    A UP4W-compatible Landscape server

    • i.e., Landscape beta

How do I set up a Landscape beta server?
Can you help me set up a Landscape beta server locally, just for testing?

Sure:

  1. Set up an Ubuntu WSL to act as the server:

    1. Install a new Ubuntu WSL distro:

    wsl --install Ubuntu-22.04

    1. Find out the Windows host IP: In the WSL distro named Ubuntu-22.04, run:

      wslinfo --networking-mode

      • If it says mirrored, the relevant IP is 127.0.0.1. Take note of this address.

    • Otherwise, run the command ip route | grep ^default and take note of the IP address that is printed.

    1. Set up a Landscape Beta server:

      1. Start a shell in your Ubuntu-22.04 distro.

      2. Install the Landscape (beta) following the steps in the Landscape Quickstart deployment with the following considerations:

        • Make sure you install the beta version.

        • Your FQDN is the address you took note of in the previous step.

    2. Take note of the following addresses:

      • Hostagent API endpoint: ${WINDOWS_HOST_IP}:6554

      • Message API endpoint: ${WINDOWS_HOST_IP}/message-system

      • Ping API endpoint: ${WINDOWS_HOST_IP}/ping

    3. Open a Ubuntu-22.04 terminal and keep it open during the rest of the guide.

      • This ensures this distro keeps running in the background. See also: Microsoft’s FAQ.

  2. Store the following file somewhere in your Windows system. Name it landscape-client.conf. Replace the variables in the file with the relevant values for your server.

    [host]
url = ${HOSTAGENT_API_ENDPOINT}

[client]
url = ${MESSAGE_API_ENDPOINT}
ping_url = ${PING_API_ENDPOINT}
account_name = standalone

  • (Only for the verify step:)
    One or more UP4W-compatible Ubuntu WSL instances

    • i.e., from an Ubuntu, Ubuntu-Preview, or Ubuntu-22.04+ distro and with wsl-pro-service installed

      • note: with a freshly installed or updated Ubuntu-Preview or Ubuntu-22.04+, wsl-pro-service comes automatically pre-installed

I already have an Ubuntu WSL instance. Can I make it UP4W-compatible?

It depends:

  1. Open a shell into your instance and check its distro version:

    cat /etc/os-release

    If the distro is not Ubuntu, Ubuntu-Preview, or Ubuntu-22.04+: Your instance cannot be made UP4W-compatible. Please create a new one that is compatible. Otherwise:

  2. Open a shell into your distro and check if package wsl-pro-service is installed:

    pkg -s wsl-pro-service | grep Status

    If the status is not Status: install ok installed: Install it by running: sudo apt update && sudo apt install -y wsl-pro-service.

How do I create a new Ubuntu WSL instance that is UP4W-compatible?

Note

Here we assume you already have WSL installed. Run wsl --version to verify; if there you get an error because it is not there, install it: wsl --install.

Warning

Here we assume you do not have any existing Ubuntu-Preview or Ubuntu-22.04+ instances or you have them but do not mind overwriting them.

  • To view your current registered instances, run wsl --list --quiet.

  • To export, delete, and re-import an instance, see wsl --export, wsl --unregister, and wsl --import.

On your Windows host, in the Microsoft Store, search for the Ubuntu-Preview or Ubuntu-22.04+ distro app, click Install / Update, then Open. Follow the instructions to set up the instance. Note: The instance will come with wsl-pro-service pre-installed.

2. Install UP4W

On your Windows host, go to the Microsoft Store, search for Ubuntu Pro for WSL and click on the result. Find the Install button. Click. Done.

3. Configure UP4W for Ubuntu Pro and Landscape

See also: Ubuntu Pro, Landscape

There are two ways in which you can configure UP4W for Ubuntu Pro and Landscape – using the UP4W GUI or using the Windows Registry.

Using the GUI

Note

With this method you can only configure UP4W on a single Windows host at a time.

See also: UP4W GUI

  1. Open the Windows menu, search for “Ubuntu Pro for WSL”, click.

  2. Input your Ubuntu Pro token:

    1. Click on Already have a token?.

    2. Write your Ubuntu Pro token and click Confirm.

  3. Input your Landscape configuration:

    1. Click on Quick setup.

    2. Write the FQDN of your server.

    3. Leave the registration key field empty.

    4. Click the Continue button.

Using the registry

Note

This method can be adapted to configure UP4W on multiple Windows hosts at a time.

See also: Windows registry

  1. Press Win+R, type regedit.exe, and click OK.

  2. Navigate the tree to HKEY_CURRENT_USER\Software\Canonical\UbuntuPro.

    Note

    This key will not exist until you’ve run UP4W at least once. Otherwise, you’ll have to create the key and values yourself. See more: Microsoft Learn | Windows registry information for advanced users

  3. Input your Ubuntu Pro token:

    • Right-click UbuntuProToken > Modify > Write the Ubuntu Pro token.

  4. Input your Landscape configuration:

4. Verify that UP4W is working

If either verification step fails, wait for a few seconds and try again. This should not take longer than a minute.

  1. Start the UP4W GUI and check that your subscription is active.

    • To open the GUI, search Ubuntu Pro for WSL in the Windows menu and click on it.

    • The GUI will explicitly say that you are subscribed.

  2. Open any of the distros you want to manage and check that it is pro-attached with pro status.

  3. Open Landscape and check that the host and distro were registered.