How to install and configure UP4W¶
1. Check that you meet UP4W prerequisites¶
To install and configure UP4W you will need:
A Windows host
An Ubuntu Pro token
How do I get an Ubuntu Pro token?
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.
Visit your Ubuntu Pro Dashboard to retrieve your subscription token.
See more: Ubuntu | Ubuntu Pro > Dashboard
(Only if you want to use UP4W with Landscape:)
A UP4W-compatible Landscape serveri.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:
Set up an Ubuntu WSL to act as the server:
Install a new Ubuntu WSL distro:
wsl --install Ubuntu-22.04
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 is127.0.0.1
. Take note of this address.Otherwise, open file
/etc/resolv.conf
in the WSL instance named Ubuntu-22.04. Find the line starting withnameserver
followed by an IP address.If the IP address does not start with
127
, take note of this address.Otherwise, run the command
ip route | grep ^default
and take note of the IP address that is printed.
Set up a Landscape Beta server:
Start a shell in your Ubuntu-22.04 distro.
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.
See more: Landscape | Quickstart deployment
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
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.
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 instancesi.e., from an
Ubuntu
,Ubuntu-Preview
, orUbuntu-22.04
+ distro and withwsl-pro-service
installednote: with a freshly installed or updated
Ubuntu-Preview
orUbuntu-22.04
+,wsl-pro-service
comes automatically pre-installed
I already have an Ubuntu WSL instance. Can I make it UP4W-compatible?
It depends:
Open a shell into your instance and check its distro version:
cat /etc/os-release
If the distro is not
Ubuntu
,Ubuntu-Preview
, orUbuntu-22.04
+: Your instance cannot be made UP4W-compatible. Please create a new one that is compatible. Otherwise: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
, andwsl --import
.
See more: Microsoft | WSL Documentation.
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
Open the Windows menu, search for “Ubuntu Pro for WSL”, click.
Input your Ubuntu Pro token:
Click on Already have a token?.
Write your Ubuntu Pro token and click Confirm.
Input your Landscape configuration:
Click on Quick setup.
Write the FQDN of your server.
Leave the registration key field empty.
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
Press Win+R, type
regedit.exe
, and click OK.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
Input your Ubuntu Pro token:
Right-click
UbuntuProToken
> Modify > Write the Ubuntu Pro token.
Input your Landscape configuration:
Right-click
LandscapeConfig
> Modify > Write the Landscape config.See more: UP4W Landscape config reference.
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.
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.
Open any of the distros you want to manage and check that it is pro-attached with
pro status
.See also: Ubuntu Pro client
Open Landscape and check that the host and distro were registered.