How to set up Ubuntu Pro for WSL and register WSL hosts to Landscape

This document is for a future release of Landscape beta. Ubuntu Pro for WSL is not available yet for everyone in the Microsoft Store.

If this is the first time you’ve installed Landscape beta, you can continue with this guide. If you upgraded your version of Landscape beta, you first need to configure it to enable WSL-related services. For more information, visit how to configure WSL-related services after upgrading Landscape beta.

You must be running Windows 11 to use Ubuntu Pro for WSL.

This guide describes how to set up Ubuntu Pro for WSL and register new WSL hosts (Windows machines) to Landscape.

Contents:

Check prerequisites

To use the WSL-Landscape integration, you must have the following applications downloaded from the Microsoft store:

At this time, you must use Ubuntu (Preview). If you already have the Ubuntu (Preview) application installed, you may need to update it to the newest version.

Also, you must have WSL 2 installed instead of WSL 1. If you’ve just now installed WSL from the Microsoft store, then you’ve installed WSL 2 and can proceed to the next steps. If you’ve previously installed WSL and aren’t sure if it’s WSL 1 or WSL 2, run wsl -l -v in Powershell or Command Prompt to get the version. If you have WSL 1, you need to upgrade to WSL 2. For more information, see Microsoft’s guide on upgrading from WSL 1 to WSL 2.

Install and activate Ubuntu Pro for WSL

The documentation here is for a future release of Landscape beta. Ubuntu Pro for WSL is not available yet for everyone in the Microsoft Store.

To install Ubuntu Pro for WSL from your Windows machine:

  1. Install the Ubuntu Pro for WSL application from the Microsoft Store
  2. Click I already have a token
  3. Enter your Ubuntu Pro token. You can get this from your Ubuntu Pro account dashboard.
  4. Click Apply

If done successfully, you’ll receive confirmation on the next page that your subscription is active.

Configure Ubuntu Pro for WSL for Landscape

To configure Ubuntu Pro for WSL so the Windows machine can be registered as a WSL host with Landscape:

  1. Open the Registry Editor in your Windows machine

    • To open the Registry Editor, either press the Windows key + R and type regedit or search “Registry Editor” in the taskbar and select it from the results.
  2. Go to HKEY_CURRENT_USER\Software

  3. Create a new key and name it “Canonical”. You can do this with Edit or Right Click > New > Key

  4. Create a new key inside the Canonical key and name it “UbuntuPro” (Edit or Right Click > New > Key)

  5. Add a new multi-string value key within the HKEY_CURRENT_USER\Software\Canonical\UbuntuPro key. You can do this with Edit or Right Click > New > Multi-string value

  6. Name this key “LandscapeConfig”

  7. Open the LandscapeConfig key and add the following lines in the Value data field:

    [host]
    url = {HOST_URL:PORT}
    
    [client]
    account_name = {ACCOUNT_NAME}
    registration_key = {REGISTRATION_KEY}
    url = {CLIENT_URL}
    log_level = debug
    ping_url = {PING_URL}
    

    Replace the following values:

    • {HOST_URL:PORT}: The URL of your Landscape account suffixed with a colon (:) followed by the port number. Port 6554 is the default for Landscape Quickstart installations. For example, https://landscape-server.domain.com:6554
    • {ACCOUNT_NAME}: The Landscape account name this computer belongs to. This is located on your organisation’s home page in the Landscape web portal. For self-hosted Landscape accounts, the account name defaults to “standalone”.
    • {REGISTRATION_KEY}: An optional account-wide key used to register new clients. There is no key defined by default, but one can be set in your Landscape account settings. If you have a registration key, it’s located on your organisation’s home page in your Landscape web portal. If you don’t have a registration key, leave this field blank.
    • {CLIENT_URL}: The main URL for the Landscape Server to connect this client to. This defaults to the URL of your Landscape account suffixed with /message-system, although you may be using a different URL. For example, https://landscape-server.domain.com/message-system.
    • {PING_URL}: The ping URL you want this client to report to. This defaults to the URL of your Landscape account suffixed with /ping, although you may be using a different URL. For example, https://landscape-server.domain.com/ping.

    Your final LandscapeConfig key should be similar to the following example:

    [host]
    url = https://landscape-server.domain.com:6554
    
    [client]
    account_name = standalone
    url = https://landscape-server.domain.com/message-system
    log_level = debug
    ping_url = https://landscape-server.domain.com/ping
    

Finalize the Windows machine registration

To finish registering your WSL host to Landscape:

  1. Restart Windows
  2. Wait for your Windows machine to appear in your Landscape account. This can take a few minutes, and you may need to refresh the page.
  3. Accept the pending computer
    • To accept it, tick the checkbox near its name, assign it to an access group, and click Accept

That’s it! Your Windows host machine is now registered in Landscape. To register WSL-Ubuntu instances, see how to register WSL instances.

(If necessary) Troubleshoot

If your Windows host machine doesn’t appear as a pending computer in your Landscape account:

  • Ensure you’re logged in to the same Landscape account that your WSL host is registering with

    You must be logged into the Landscape account associated your WSL host registration.

  • Wait a few minutes and refresh your Landscape account

    The registration process won’t be immediate; it may take a few minutes. If you haven’t already, wait a few minutes and try refreshing the page to see if your Windows machine appears as a pending computer in your Landscape account.

  • Ensure your LandscapeConfig key is in the correct location in the Registry Editor

    The full path for your LandscapeConfig key is HKEY_CURRENT_USER\Software\Canonical\UbuntuPro\LandscapeConfig. This LandscapeConfig key must have the [host] and [client] sections completed similar to what was exampled in the previous configuration section.

  • Check your LandscapeConfig key to ensure it has the correct information for your Landscape account

    You should check closely that the values in your LandscapeConfig registry key match your system’s configuration. In the [client] section, your url and ping_url values may be different than the defaults.

  • Check that the url in the [host] section of your LandscapeConfig key is suffixed with the port number (usually Port 6554)

    Your url value must include the port number. The Landscape Quickstart installation uses Port 6554 by default, although your specific port may be different if you’ve changed the configuration. For example:

    [host]
    url = https://landscape-server.domain.com:6554
    
  • Ensure your firewall settings are configured appropriately

    You may need to adjust your firewall settings to allow inbound and outbound traffic on Port 6554, or whichever port you’re routing traffic on if you’ve changed the port. Port 6554 is the default for landscape-server-quickstart installations.

  • If your Landscape URL isn’t registered with a public or private DNS, you may need to register it or update your Windows Hosts file

    Your domain name won’t resolve if it’s not registered with DNS. If you plan to update your Windows Hosts file instead of registering the domain with DNS, it’s recommended that you proceed with extreme caution and consult Microsoft’s documentation first.

  • If you’re using a registration key, ensure that the registration key in the LandscapeConfig key matches the registration key in your Landscape account

    If you’re using a registration key, the registration key you use in your LandscapeConfig key must match exactly with the registration key in your Landscape account. Your registration key can be found in the Account tab on the web portal.

  • If you have auto-registration enabled, check if your Windows machine is already listed as a computer in your Landscape account

    Landscape has an auto-registration feature that allows you to register computers without manually approving each one. If you’re using a registration key and you have this feature enabled, your Windows machine won’t appear as a pending computer. Instead, it’ll auto-register and appear in your list of computers. For more information, see how to auto-register new computers.

  • Check that your Ubuntu Pro token was applied correctly

    If you successfully completed the previous steps on activating Ubuntu Pro for WSL, your Ubuntu Pro token should be active. However, you can also check if it’s active in the Registry Editor. In HKEY_CURRENT_USER\Software\Canonical\UbuntuPro, there should be a key titled UbuntuProToken with your token inside. If this isn’t there, you can add these values in to the Registry Editor, or you can re-do the previous steps on installing and activating Ubuntu Pro for WSL.

  • Reboot your Windows machine

    If you haven’t already, try rebooting your Windows machine to ensure the Landscape configuration was applied.

  • Access the Ubuntu Pro for WSL logs

    If you’ve completed the previous troubleshooting steps and your Windows machine still doesn’t appear as a pending computer in Landscape, you should review the Ubuntu Pro for WSL logs. To access those logs, see Ubuntu Pro for WSL’s guide on how to access the logs.

    Landscape won’t have awareness of the Windows host machine until it’s a pending computer or auto-registered in your Landscape account. The Landscape logs won’t be helpful when troubleshooting this registration issue.

On the registry section: it is missing some steps (2 through 4):

  1. Open the registry
  2. Go to HKEY_CURRENT_USER\Software
  3. Create key Canonical under Software (Right Click > New > Key)
  4. Create key under Canonical called UbuntuPro (Right Click > New > Key)
  5. Within this key (HKEY_CURRENT_USER\Software\Canonical\UbuntuPro ), create a new multi-string value called LandscapeConfig.
1 Like

Thanks for the feedback, @edugomez! I’ve just updated it to include these steps.

I can not find Ubuntu Pro for WSL in the Microsoft Store. I’ve got WSL 2 and Ubuntu installed and I’m using Windows 11 Pro.

1 Like

Hey @benwagener! This doc is for a future beta release. Ubuntu Pro for WSL isn’t available to everyone just yet, but it’s coming soon! :blush:

I just changed the disclaimer so it’s more clear that Ubuntu Pro for WSL isn’t available for everyone yet in the Microsoft Store. Sorry for the unclear messaging, but it sounds like you have the other pieces in place to use WSL with Landscape (when it’s ready).

Thanks for your feedback and contributing to the Landscape community!!

1 Like