### Install Project Dependencies

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/develop-with-ubuntu-wsl.md

Installs all the packages listed in the 'devDependencies' section of your 'package.json' file. This is necessary before starting the server.

```bash
$ npm install
```

--------------------------------

### Installation Bundle Directory Setup

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/gui/packages/ubuntupro/linux/CMakeLists.txt

Configures the installation prefix to create a relocatable bundle in the build directory. Clears the bundle directory before installation.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)
```

--------------------------------

### Install Ubuntu WSL instance

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/cloud-init.md

Execute the installation command in PowerShell to trigger the cloud-init provisioning process.

```text
> wsl --install Ubuntu-24.04
```

--------------------------------

### List installed Ubuntu instances

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/README.md

Shows all currently installed Ubuntu instances and their status on the machine.

```powershell
wsl -l -v
```

--------------------------------

### Install Ubuntu on WSL

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/develop-with-ubuntu-wsl.md

Use this command to install a specific version of Ubuntu on WSL. Ensure you have WSL installed and configured.

```bash
wsl --install Ubuntu-22.04
```

--------------------------------

### Install Ubuntu on WSL

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/README.md

Installs a specific Ubuntu distribution on Windows using PowerShell.

```powershell
wsl --install <Ubuntu distro>
```

--------------------------------

### Install WSL Instances with Specific Cloud-init Configurations

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/manage-and-configure.md

Install Ubuntu-24.04 instances with unique names, which will trigger their respective cloud-init configurations.

```bash
> wsl --install Ubuntu-24.04 --name UbuntuWebDev
> wsl --install Ubuntu-24.04 --name UbuntuDataScience
```

--------------------------------

### Start Node.js Web Server

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/develop-with-ubuntu-wsl.md

Starts the development server defined in 'package.json'. This command will typically launch 'lite-server' to serve your project files.

```bash
$ npm start
```

--------------------------------

### Ubuntu Prompt Example

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/contributing.md

This is an example of an Ubuntu prompt with username and host, used to distinguish Ubuntu commands in documentation.

```text
<username>@<host>:~$ 
```

--------------------------------

### Install Application Executable

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/gui/packages/ubuntupro/linux/CMakeLists.txt

Installs the application executable to the root of the bundle destination.

```cmake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)
```

--------------------------------

### Build CUDA Sample Application

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/gpu-cuda.md

Install CMake and build the deviceQuery sample project.

```bash
$ sudo apt install cmake

$ cd ~/Dev/cuda-samples/Samples/1_Utilities/deviceQuery

$ cmake -S . -B build

$ cmake --build build
```

--------------------------------

### Install Ubuntu distribution from file

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/explanation/security-overview.md

Install an Ubuntu distribution using a downloaded WSL image file. This command is used after manually verifying the file's checksum.

```bash
wsl --install --from-file ubuntu-<version number>-wsl.amd64.wsl
```

--------------------------------

### Install WSL via PowerShell

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/install-ubuntu-wsl2.md

Initial command to install and enable the Windows Subsystem for Linux components.

```text
> wsl --install
```

--------------------------------

### Manage multiple Ubuntu instances

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/develop-with-ubuntu-wsl.md

Install and run a secondary Ubuntu instance with a custom name.

```text
> wsl --install Ubuntu-24.04 --name Ubuntu-tutorial
```

```text
> wsl -d Ubuntu-tutorial
```

--------------------------------

### Cloud-init with Project-Specific Configurations

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/manage-and-configure.md

Example structure for organizing multiple cloud-init configurations for different projects under the .cloud-init directory.

```text
C:\Users\<user>
└── .cloud-init
    ├── Ubuntu-22.04.user-data
    ├── Ubuntu-24.04.user-data
    ├── Ubuntu-web-dev.user-data
    └── Ubuntu-data-science.user-data
```

--------------------------------

### Install WSL Pro Service (Linux)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/02-install.md

Install the WSL Pro Service .deb package using apt. Ensure you are in the directory containing the .deb file.

```bash
$ sudo apt install ./wsl-pro-service_*.deb
```

--------------------------------

### Install WSL Instance with Custom Name

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/manage-and-configure.md

Use the `--name` flag during installation to assign a custom name to a new WSL instance.

```bash
> wsl --install Ubuntu-24.04 --name UbuntuWebDev
```

--------------------------------

### WSL install Action

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/actions.md

Installs the Windows Subsystem for Linux application and optionally an Ubuntu WSL distribution.

```APIDOC
## WSL install

### Description
Installs the Windows Subsystem for Linux application, and optionally an Ubuntu WSL application.

### Parameters
#### Request Body
- **distro** (string) - Optional - The name of the distro to install from the Microsoft store.

### Request Example
```yaml
- name: Install or update WSL
  uses: Ubuntu/WSL/.github/actions/wsl-install@main
  with:
    distro: Ubuntu-20.04
```
```

--------------------------------

### Install WSL on Windows

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/getting-started-with-up4w.md

Executes the installation and enablement of WSL on a Windows machine.

```text
wsl --install
```

--------------------------------

### Install Ubuntu 24.04 on WSL

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/getting-started-with-up4w.md

Downloads and installs the Ubuntu 24.04 LTS distribution via WSL.

```text
wsl --install Ubuntu-24.04
```

--------------------------------

### Landscape configuration file example

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/landscape_config.md

A sample configuration file demonstrating the [host] and [client] sections required for Landscape integration.

```ini
[host]
url = landscape-server.domain.com:6554

[client]
url = https://landscape-server.domain.com/message-system
ping_url  = http://landscape-server.domain.com/ping
account_name = standalone
log_level = debug
ssl_public_key = C:\Users\user\Downloads\landscape_server.pem
```

--------------------------------

### Run CUDA Sample Application

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/gpu-cuda.md

Execute the compiled deviceQuery binary to verify the CUDA setup.

```bash
$ ./build/deviceQuery
```

--------------------------------

### Install Ubuntu Pro for WSL via WinGet

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/set-up-up4w.md

Use this command in PowerShell to install the Ubuntu Pro for WSL application.

```text
> winget install Canonical.UbuntuProforWSL
```

--------------------------------

### Installation Paths for Bundle Contents

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/gui/packages/ubuntupro/linux/CMakeLists.txt

Defines installation paths for data and library directories within the bundle.

```cmake
set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")
```

--------------------------------

### Install Flutter Library

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/gui/packages/ubuntupro/linux/CMakeLists.txt

Installs the main Flutter library file to the bundle's library directory.

```cmake
install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Send WSL Installation Request to Multiple Targets (Bash)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/custom-rootfs-multiple-targets.md

Iterates through a list of computer IDs, sending a POST request to the Landscape API to initiate WSL installation on each target machine.

```bash
for COMPUTER_ID in "${PARENT_COMPUTER_IDS[@]}"; do
    API_RESPONSE=$( curl -s -X POST                             \
        "$LANDSCAPE_URL/api/v2/computers/$COMPUTER_ID/children" \
        --data "$WSL_JSON"                                      \
        --header "Authorization:Bearer $JWT"                    \
        --header "Content-Type: application/json"               \
        --header "Accept: application/json" )

    # show the response
    echo $API_RESPONSE
    echo
done
```

--------------------------------

### Build Output Log

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/gpu-cuda.md

Example output showing a successful CMake configuration and build process for the deviceQuery sample.

```text
g@mib01:~/Dev/cuda-samples/Samples/1_Utilities/deviceQuery$ cmake -S . -B build
-- The C compiler identification is GNU 13.3.0
-- The CXX compiler identification is GNU 13.3.0
-- The CUDA compiler identification is NVIDIA 13.2.51 with host compiler GNU 13.3.0
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /usr/bin/cc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Detecting CUDA compiler ABI info
-- Detecting CUDA compiler ABI info - done
-- Check for working CUDA compiler: /usr/local/cuda-13/bin/nvcc - skipped
-- Detecting CUDA compile features
-- Detecting CUDA compile features - done
-- Found CUDAToolkit: /usr/local/cuda-13/targets/x86_64-linux/include (found version "13.2.51")
-- Performing Test CMAKE_HAVE_LIBC_PTHREAD
-- Performing Test CMAKE_HAVE_LIBC_PTHREAD - Success
-- Found Threads: TRUE
-- CUDA Samples installation configured:
--   Architecture: x86_64
--   OS: linux
--   Build Type: release
--   Install Prefix: /home/g/Dev/cuda-samples/Samples/1_Utilities/deviceQuery/build/bin
--   Install Directory: /home/g/Dev/cuda-samples/Samples/1_Utilities/deviceQuery/build/bin/x86_64/linux/release
-- Configuring done (43.2s)
-- Generating done (0.0s)
-- Build files have been written to: /home/g/Dev/cuda-samples/Samples/1_Utilities/deviceQuery/build
g@mib01:~/Dev/cuda-samples/Samples/1_Utilities/deviceQuery$ cmake --build build
[ 50%] Building CXX object CMakeFiles/deviceQuery.dir/deviceQuery.cpp.o
[100%] Linking CXX executable deviceQuery
[100%] Built target deviceQuery
g@mib01:~/Dev/cuda-samples/Samples/1_Utilities/deviceQuery$
```

--------------------------------

### Start Ubuntu in Home Directory from PowerShell

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/install-ubuntu-wsl2.md

Initiate an Ubuntu session directly from PowerShell, with the working directory set to the Ubuntu home directory. This bypasses the need to manually change directories after starting.

```powershell
> wsl ~ -d Ubuntu
```

--------------------------------

### Installation Rules for Runtime Components

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/gui/packages/ubuntupro/windows/CMakeLists.txt

Configures the installation of the main executable, Flutter ICU data, libraries, and bundled plugin libraries. It ensures assets are correctly copied and the AOT library is installed for non-Debug builds.

```cmake
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()

set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)
```

--------------------------------

### Launch WSL Instance by Custom Name

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/manage-and-configure.md

Launch a WSL instance using its custom name after installation.

```bash
> wsl -d UbuntuWebDev
```

--------------------------------

### Start Ubuntu in Current Windows Directory

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/install-ubuntu-wsl2.md

Launch an Ubuntu session that starts in the same directory as your current PowerShell session. The prompt will reflect the mounted Windows C: drive.

```text
<ubuntu-username>@<hostname>:/mnt/c/Users/<windows-username>$
```

```bash
wsl -d <Distro>
```

--------------------------------

### Install ImageMagick and convert icon

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/custom-ubuntu-distro.md

Install ImageMagick to convert an input icon to a grayscale format for the distro icon.

```text
$sudo apt update
$sudo apt install imagemagick
$convert ~/myNewUbuntu/usr/share/wsl/input.ico -colorspace Gray ~/myNewUbuntu/usr/share/wsl/myIcon.ico
```

--------------------------------

### Install Node.js and npm

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/develop-with-ubuntu-wsl.md

Install Node.js and its package manager, npm, on your Ubuntu WSL instance. These are required for running JavaScript applications.

```bash
$ sudo apt-get install nodejs
```

```bash
$ sudo apt install npm
```

--------------------------------

### Install Additional Ubuntu Distribution

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/getting-started-with-up4w.md

Install a different version of Ubuntu via PowerShell to test automatic Pro-attachment.

```text
> wsl --install Ubuntu-22.04
```

--------------------------------

### Build WSL Installation Payload (Bash)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/custom-rootfs-multiple-targets.md

Uses `jq` to dynamically build the JSON payload for WSL installation with variables for rootfs URL, computer name, and cloud-init data.

```bash
WSL_JSON=$( jq -n                           \
    --arg rf "$ROOTFS_URL"                  \
    --arg cn "$COMPUTER_NAME"               \
    --arg b64 "$BASE64_ENCODED_CLOUD_INIT"  \
    '{rootfs_url: $rf, computer_name: $cn, cloud_init: $b64}' )
```

--------------------------------

### PowerShell Prompt Example

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/contributing.md

This is an example of a PowerShell prompt with a path, used to distinguish PowerShell commands in documentation.

```text
PS C:\Users\username>
```

--------------------------------

### WSL Pro Service Fish Completion - Setup for New Sessions

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/08-wsl-pro-service-command-line-reference.md

Sets up fish autocompletion for all new shell sessions by saving the script to the fish completions directory.

```none
wsl-pro-service completion fish > ~/.config/fish/completions/wsl-pro-service.fish
```

--------------------------------

### Install Bundled Plugin Libraries

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/gui/packages/ubuntupro/linux/CMakeLists.txt

Installs any bundled plugin libraries to the bundle's library directory. This loop iterates over PLUGIN_BUNDLED_LIBRARIES.

```cmake
foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)
```

--------------------------------

### Sample Application Output

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/gpu-cuda.md

Example output from running the deviceQuery application, displaying detected CUDA device information.

```text
./build/deviceQuery Starting...

 CUDA Device Query (Runtime API) version (CUDART static linking)

Detected 1 CUDA Capable device(s)

Device 0: "NVIDIA GeForce MX130"
  CUDA Driver Version / Runtime Version          13.0 / 13.2
  CUDA Capability Major/Minor version number:    5.0
  Total amount of global memory:                 2048 MBytes (2147352576 bytes)
  (003) Multiprocessors, (128) CUDA Cores/MP:    384 CUDA Cores
  GPU Max Clock rate:                            1189 MHz (1.19 GHz)
  Memory Clock rate:                             2505 Mhz
  Memory Bus Width:                              64-bit
  L2 Cache Size:                                 1048576 bytes
  Maximum Texture Dimension Size (x,y,z)         1D=(65536), 2D=(65536, 65536), 3D=(4096, 4096, 4096)
  Maximum Layered 1D Texture Size, (num) layers  1D=(16384), 2048 layers
  Maximum Layered 2D Texture Size, (num) layers  2D=(16384, 16384), 2048 layers
  Total amount of constant memory:               65536 bytes
  Total amount of shared memory per block:       49152 bytes
  Total shared memory per multiprocessor:        65536 bytes
  Total number of registers available per block: 65536
  Warp size:                                     32
  Maximum number of threads per multiprocessor:  2048
  Maximum number of threads per block:           1024
  Max dimension size of a thread block (x,y,z): (1024, 1024, 64)
  Max dimension size of a grid size    (x,y,z): (2147483647, 65535, 65535)
  Maximum memory pitch:                          2147483647 bytes
  Texture alignment:                             512 bytes
  Concurrent copy and kernel execution:          Yes with 4 copy engine(s)
  Run time limit on kernels:                     Yes
  Integrated GPU sharing Host Memory:            No
  Support host page-locked memory mapping:       Yes
  Alignment requirement for Surfaces:            Yes
  Device has ECC support:                        Disabled
```

--------------------------------

### List WSL instances

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/manage-and-configure.md

View a list of all installed WSL instances, their state, and version. This command is useful for verifying newly created or imported instances.

```text
NAME            STATE         VERSION
Ubuntu-24.04    Stopped       2
ubuntu2404b     Stopped       2
ubuntu2404c     Stopped       2
```

--------------------------------

### Full Script: Deploy Custom RootFS to Multiple WSL Targets (Bash)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/custom-rootfs-multiple-targets.md

A comprehensive Bash script that automates the process of base64 encoding cloud-init, obtaining a JWT, building the installation payload, and issuing installation requests to multiple WSL targets.

```bash
#!/usr/bin/env bash

# Base64-encoding the cloud-config file contents
BASE64_ENCODED_CLOUD_INIT=$(cat $CLOUD_INIT_FILE | base64 --wrap=0)

# Build the auth payload
LOGIN_JSON=$( jq -n                      \
    --arg em "$LANDSCAPE_USER_EMAIL"     \
    --arg pwd "$LANDSCAPE_USER_PASSWORD" \
    '{email: $em, password: $pwd}' )

# Issue an auth request and retrieve the JWT
LOGIN_RESPONSE=$( curl -s -X POST "$LANDSCAPE_URL/api/v2/login" \
    --data "$LOGIN_JSON"                                        \
    --header "Content-Type: application/json"                   \
    --header "Accept: application/json" )

JWT=$( echo $LOGIN_RESPONSE | jq .token | tr -d '"')

# Build the installation payload
WSL_JSON=$( jq -n                           \
    --arg rf "$ROOTFS_URL"                  \
    --arg cn "$COMPUTER_NAME"               \
    --arg b64 "$BASE64_ENCODED_CLOUD_INIT"  \
    '{rootfs_url: $rf, computer_name: $cn, cloud_init: $b64}' )

# Issue the command for each Windows machine
for COMPUTER_ID in "${PARENT_COMPUTER_IDS[@]}"; do
    API_RESPONSE=$( curl -s -X POST                             \
        "$LANDSCAPE_URL/api/v2/computers/$COMPUTER_ID/children" \
        --data "$WSL_JSON"                                      \
        --header "Authorization:Bearer $JWT"                    \
        --header "Content-Type: application/json"               \
        --header "Accept: application/json" )

    # show the response
    echo $API_RESPONSE
    echo
done
```

--------------------------------

### Example pro status output

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/verify-subscribe-attach.md

This represents the expected output format when checking the status of Ubuntu Pro services and subscription details.

```text
SERVICE          ENTITLED  STATUS       DESCRIPTION
esm-apps         yes       enabled      Expanded Security Maintenance for Applications
esm-infra        yes       enabled      Expanded Security Maintenance for Infrastructure

NOTICES
Operation in progress: pro attach

For a list of all Ubuntu Pro services, run 'pro status --all'
Enable services with: pro enable <service>

     Account: username@ubuntu.com
Subscription: Ubuntu Pro - free personal subscription
```

--------------------------------

### WSL Pro Service Bash Completion - Setup for New Sessions (macOS)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/08-wsl-pro-service-command-line-reference.md

Sets up bash autocompletion for all new shell sessions on macOS using Homebrew's prefix.

```none
wsl-pro-service completion bash > $(brew --prefix)/etc/bash_completion.d/wsl-pro-service
```

--------------------------------

### Cloud-init Configuration for Ubuntu WSL Instance

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/deployment.md

This cloud-init configuration sets up a default user, installs the CUDA toolkit, and configures the WSL environment for an Ubuntu instance.

```yaml
#cloud-config
locale: en_GB.UTF-8
users:
- name: u
  gecos: Ubuntu
  groups: [adm,dialout,cdrom,floppy,sudo,audio,dip,video,plugdev,netdev]
  sudo: ALL=(ALL) NOPASSWD:ALL
  shell: /bin/bash

write_files:
- path: /etc/wsl.conf
  append: true
  content: |
    [user]
    default=u

runcmd:
  - cd /tmp
  - wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
  - dpkg -i cuda-keyring_1.1-1_all.deb
  - apt-get update
  - apt-get -y install cuda-toolkit-12-6

```

--------------------------------

### List WSL distributions

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/develop-with-ubuntu-wsl.md

List installed or available Ubuntu distributions on WSL.

```text
> wsl --list
```

```text
Ubuntu (Default)
```

```text
> wsl --list --online
```

--------------------------------

### Cloud-init User Data File Structure

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/manage-and-configure.md

Example structure for cloud-init user data files located in the .cloud-init directory within the Windows home directory.

```text
C:\Users\<user>
└── .cloud-init
    ├── Ubuntu-22.04.user-data
    └── Ubuntu-24.04.user-data
```

--------------------------------

### List available Ubuntu distributions

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/README.md

Displays a list of Ubuntu distributions available for installation via WSL.

```powershell
wsl --list --online
```

--------------------------------

### Terminal prompts

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/develop-with-ubuntu-wsl.md

Examples of PowerShell and Ubuntu terminal command prompts.

```text
PS C:\Users\windows-username>
```

```text
ubuntu-username@hostname:~$
```

--------------------------------

### Full Script: Deploy Custom RootFS to Multiple WSL Targets (PowerShell)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/custom-rootfs-multiple-targets.md

A complete PowerShell script that handles base64 encoding of cloud-init content, authenticates to retrieve a JWT, constructs the installation payload, and dispatches installation commands to multiple WSL targets.

```powershell
# Base64-encoding the cloud-config file contents
$content = Get-Content -Path $CLOUD_INIT_FILE -Raw
$bytes = [System.Text.Encoding]::UTF8.GetBytes($content)
$BASE64_ENCODED_CLOUD_INIT = [System.Convert]::ToBase64String($bytes)

# Build the auth payload
$LOGIN_JSON = @{
 email = "$LANDSCAPE_USER_EMAIL"
 password = "$LANDSCAPE_USER_PASSWORD"
} | ConvertTo-Json

# Issue an auth request and retrieve the JWT
$LOGIN_RESPONSE = Invoke-WebRequest -Method POST `
    -URI "$LANDSCAPE_URL/api/v2/login"           `
    -Body "$LOGIN_JSON" -ContentType "application/json"

$JWT = ConvertTo-SecureString -AsPlainText -Force $( $LOGIN_RESPONSE.Content | ConvertFrom-Json).token

# Build the installation payload
$WSL_JSON = @{
 rootfs_url = "$ROOTFS_URL"
 computer_name = "$COMPUTER_NAME"
 cloud_init = "$BASE64_ENCODED_CLOUD_INIT"
} | ConvertTo-Json

# Issue the command for each Windows machine
foreach ($COMPUTER_ID in $PARENT_COMPUTER_IDS) {
    $API_RESPONSE = Invoke-WebRequest -Method POST -Body "$WSL_JSON" `
        -Uri "$LANDSCAPE_URL/api/v2/computers/$COMPUTER_ID/children" `
        -Authentication Bearer -Token $JWT -ContentType "application/json"

    # show the response
    Write-Output $API_RESPONSE
}
```

--------------------------------

### Send WSL Installation Request to Multiple Targets (PowerShell)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/custom-rootfs-multiple-targets.md

Uses a `foreach` loop to send POST requests via `Invoke-WebRequest` to the Landscape API for WSL installation on each specified Windows machine.

```powershell
foreach ($COMPUTER_ID in $PARENT_COMPUTER_IDS) {
    $API_RESPONSE = Invoke-WebRequest -Method POST -Body "$WSL_JSON" `
        -Uri "$LANDSCAPE_URL/api/v2/computers/$COMPUTER_ID/children" `
        -Authentication Bearer -Token $JWT -ContentType "application/json"

    # show the response
    Write-Output $API_RESPONSE
}
```

--------------------------------

### Ubuntu Pro Agent Shell Completion Setup

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/07-windows-agent-command-line-reference.md

This snippet shows how to set up Zsh shell completion for the ubuntu-pro-agent. After running this command, you need to start a new shell session for the changes to take effect.

```APIDOC
## ubuntu-pro-agent completion zsh

### Description
Generates Zsh shell completion scripts for the ubuntu-pro-agent.

### Method
CLI Command

### Endpoint
N/A (CLI Command)

### Parameters
#### Query Parameters
- **--config** (string) - Optional - configuration file path
- **--verbosity** (count) - Optional - issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output

#### Request Body
N/A

### Request Example
```bash
ubuntu-pro-agent completion zsh > $(brew --prefix)/share/zsh/site-functions/_ubuntu-pro-agent
```

### Response
N/A (CLI command output)

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### WSL Pro Service Zsh Completion - Setup for New Sessions (macOS)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/08-wsl-pro-service-command-line-reference.md

Sets up zsh autocompletion for all new shell sessions on macOS using Homebrew's prefix.

```none
wsl-pro-service completion zsh > $(brew --prefix)/share/zsh/site-functions/_wsl-pro-service
```

--------------------------------

### List WSL Distributions

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/deployment.md

Use this command on the Windows host to list all installed WSL distributions and check their status.

```text
> wsl -l -v

```

--------------------------------

### Create and Navigate to Project Directory

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/develop-with-ubuntu-wsl.md

Set up a new directory for your server project and change into it. These commands are essential for organizing your code.

```bash
$ mkdir serverexample/
```

```bash
$ cd serverexample/
```

--------------------------------

### List available WSL distributions

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/install-ubuntu-wsl2.md

Displays a list of valid Linux distributions available for installation on WSL.

```text
The following is a list of valid distributions that can be installed.
Install using 'wsl --install <Distro>'.

  NAME                                   FRIENDLY NAME
  AlmaLinux-8                            AlmaLinux OS 8
  ...                                    ...
  Ubuntu                                 Ubuntu
  Ubuntu-24.04                           Ubuntu 24.04 LTS
  archlinux                              Arch Linux
  kali-linux                             Kali Linux Rolling
  ...                                    ...
  Ubuntu-18.04                           Ubuntu 18.04 LTS
  Ubuntu-20.04                           Ubuntu 20.04 LTS
  Ubuntu-22.04                           Ubuntu 22.04 LTS
...
```

--------------------------------

### Manage Packages in Custom Ubuntu

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/custom-ubuntu-distro.md

Installs the 'btop' resource monitor within the chrooted custom Ubuntu environment. It first updates the package lists and upgrades existing packages.

```bash
apt update
apt upgrade -y
apt install btop
```

--------------------------------

### Configure Landscape client settings

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/set-up-landscape-client.md

Example configuration file format used for both Windows registry LandscapeConfig values and the Advanced Configuration GUI option.

```ini
[host]
url = landscape-server.domain.com:6554

[client]
url = https://landscape-server.domain.com/message-system
ping_url  = http://landscape-server.domain.com/ping
account_name = standalone
log_level = debug
ssl_public_key = C:\Users\<username>\Downloads\landscape_server.pem
```

--------------------------------

### Update and Install Octave on Ubuntu WSL

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/data-science-and-engineering.md

Run these commands in an Ubuntu WSL terminal to update package lists and install the GNU Octave application. Ensure your WSL environment is up-to-date before installation.

```bash
$ sudo apt update
$ sudo apt install -y octave
```

--------------------------------

### Terminal prompt examples

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/CONTRIBUTING.md

Standard prompt formats used to distinguish between PowerShell and Ubuntu terminal commands.

```text
>
```

```text
C:\Users\username>
```

```text
PS C:\Users\username>
```

```text
$
```

```text
<username>@<host>:~$
```

--------------------------------

### List Available Ubuntu LTS Releases

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/upgrade-ubuntu.md

Run this command in your WSL terminal to see a list of Ubuntu LTS versions available for installation.

```bash
wsl --list --online
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/contributing.md

Use this command to serve the documentation locally on port 8000, allowing for live previewing as changes are saved.

```text
make run
```

--------------------------------

### Check CUDA Toolkit Installation

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/deployment.md

Verify that the CUDA toolkit has been installed correctly by checking its package policy.

```bash
$ apt policy cuda-toolkit-12-6

```

--------------------------------

### PowerShell script to start Ubuntu Pro for WSL agent

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/start-agent-remotely.md

A simple script to trigger the agent executable. Ensure the file is saved with UTF-8 encoding for Intune compatibility.

```powershell
Write-Output "Starting the Pro for WSL background agent remotely from Intune"
ubuntu-pro-agent.exe
```

--------------------------------

### Create a new Ubuntu WSL instance

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/verify-subscribe-attach.md

Use this command in PowerShell to initialize a new Ubuntu 24.04 instance, which triggers the automatic Pro-attachment process.

```text
> wsl ~ -d Ubuntu-24.04
```

--------------------------------

### Import WSL Instance from Backup

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/deployment.md

Restore a WSL instance from a tarball to a specified directory.

```text
> wsl --import Ubuntu-24.04 <directory-to-install-filesystem> .\backup\Ubuntu-24.04.tar.gz

```

--------------------------------

### Install or update WSL

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/actions.md

Installs the Windows Subsystem for Linux application and optionally a specific Ubuntu WSL distribution.

```yaml
 - name: Install or update WSL
   uses: Ubuntu/WSL/.github/actions/wsl-install@main
   with:
    distro: Ubuntu-20.04
```

--------------------------------

### Create backup directory

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/manage-and-configure.md

Before backing up an instance, create a directory to store the backup files.

```text
> mkdir backup
```

--------------------------------

### Launch derived Ubuntu instance as specific user

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/manage-and-configure.md

Launch a derived Ubuntu instance (created from a backup) and log in as a specific user. This is useful for accessing user-specific configurations in the new instance.

```text
> wsl -d ubuntu2404b -u k
```

--------------------------------

### Install CUDA Toolkit for WSL on Ubuntu

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/gpu-cuda.md

These commands install the WSL-specific CUDA toolkit version 13.2 on Ubuntu 24.04 AMD64. Ensure you do not install the Linux NVIDIA graphics driver. Older CUDA versions (<10) do not support WSL 2.

```bash
$ wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb

$ sudo dpkg -i cuda-keyring_1.1-1_all.deb

$ sudo apt-get update

$ sudo apt-get -y install cuda-toolkit-13-2
```

--------------------------------

### Install ICU Data File

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/gui/packages/ubuntupro/linux/CMakeLists.txt

Installs the ICU data file to the bundle's data directory. This is required for internationalization.

```cmake
install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Run an Ubuntu instance on WSL

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/custom-ubuntu-distro.md

Open a PowerShell terminal and run an instance of Ubuntu on WSL.

```text
> wsl ~ -d Ubuntu-24.04
```

--------------------------------

### Update Ubuntu Packages

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/develop-with-ubuntu-wsl.md

Ensure your Ubuntu system on WSL is up-to-date by updating package lists and upgrading installed packages. Run this before installing new software.

```bash
$ sudo apt update && sudo apt upgrade -y
```

--------------------------------

### WSL Pro Service Bash Completion - Setup for New Sessions (Linux)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/08-wsl-pro-service-command-line-reference.md

Sets up bash autocompletion for all new shell sessions on Linux by saving the script to the system's completion directory.

```none
wsl-pro-service completion bash > /etc/bash_completion.d/wsl-pro-service
```

--------------------------------

### Conditionally install AOT library with CMake

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/gui/packages/ubuntupro/linux/CMakeLists.txt

Use this logic to ensure the AOT library is only installed for non-Debug build types. It requires the AOT_LIBRARY and INSTALL_BUNDLE_LIB_DIR variables to be defined.

```cmake
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Open a specific Ubuntu instance

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/README.md

Launches a specific Ubuntu instance in its home directory.

```powershell
wsl ~ -d <Instance name>
```

--------------------------------

### VS Code Server Installation Message

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/develop-with-ubuntu-wsl.md

This message appears when you first run 'code .' from WSL. It indicates that VS Code is installing its server component within your WSL environment.

```text
Installing VS Code Server for x64...
Downloading:

```

--------------------------------

### CUDA Toolkit Installation Confirmation on Ubuntu

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/gpu-cuda.md

A successful CUDA toolkit installation on Ubuntu for WSL 2 will end with output similar to this, indicating that components like cuda-toolkit-13-2 have been set up.

```bash
done.
Setting up default-jre-headless (2:1.21-75+exp1) ...
Setting up openjdk-21-jre:amd64 (21.0.10+7-1~24.04) ...
Setting up default-jre (2:1.21-75+exp1) ...
Setting up cuda-nsight-13-2 (13.2.20-1) ...
Setting up cuda-visual-tools-13-2 (13.2.0-1) ...
Setting up cuda-tools-13-2 (13.2.0-1) ...
Setting up cuda-toolkit-13-2 (13.2.0-1) ...
g@mib01:~$ 
```

--------------------------------

### Build WSL Installation Payload (PowerShell)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/custom-rootfs-multiple-targets.md

Uses PowerShell hashtables and `ConvertTo-Json` to construct the JSON payload for WSL installation, incorporating variables for rootfs URL, computer name, and cloud-init data.

```powershell
$WSL_JSON = @{
 rootfs_url = "$ROOTFS_URL"
 computer_name = "$COMPUTER_NAME"
 cloud_init = "$BASE64_ENCODED_CLOUD_INIT"
} | ConvertTo-Json
```

--------------------------------

### Build WSL Installation Payload (JSON)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/custom-rootfs-multiple-targets.md

Constructs the JSON payload required for installing a custom WSL root filesystem. Includes the URL for the rootfs, the desired computer name, and cloud-init data.

```json
{"rootfs_url": "http://landscape.mib.com:9009/ubuntu-24.04-custom.tar.gz", "computer_name": "Carbonizer", "cloud_init": "<base64 encoded material>"}
```

--------------------------------

### WSL Pro Service Zsh Completion - Setup for New Sessions (Linux)

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/08-wsl-pro-service-command-line-reference.md

Sets up zsh autocompletion for all new shell sessions on Linux by saving the script to the zsh site-functions directory.

```none
wsl-pro-service completion zsh > "${fpath[1]}/_wsl-pro-service"
```

--------------------------------

### Manually Attach Ubuntu Pro

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/explanation/pro-explanation.md

Use this command to manually attach Ubuntu Pro to an instance using a token. This method is suitable for a small number of instances.

```text
pro attach <token>
```

--------------------------------

### Zsh Autocompletion

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/07-windows-agent-command-line-reference.md

Commands to generate and install zsh completion scripts.

```none
echo "autoload -U compinit; compinit" >> ~/.zshrc
```

```none
source <(ubuntu-pro-agent completion zsh)
```

```none
ubuntu-pro-agent completion zsh > "${fpath[1]}/_ubuntu-pro-agent"
```

--------------------------------

### PowerShell Autocompletion

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/07-windows-agent-command-line-reference.md

Commands to generate and install PowerShell completion scripts.

```none
ubuntu-pro-agent completion powershell | Out-String | Invoke-Expression
```

```default
ubuntu-pro-agent completion powershell [flags]
```

```default
  -h, --help              help for powershell
      --no-descriptions   disable completion descriptions
```

```default
  -c, --config string     configuration file path
  -v, --verbosity count   issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output
```

--------------------------------

### Version command help options

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/windows-agent/README.md

Help flag specific to the version command.

```bash
  -h, --help   help for version
```

--------------------------------

### Fish Autocompletion

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/07-windows-agent-command-line-reference.md

Commands to generate and install fish completion scripts.

```none
ubuntu-pro-agent completion fish | source
```

```none
ubuntu-pro-agent completion fish > ~/.config/fish/completions/ubuntu-pro-agent.fish
```

```default
ubuntu-pro-agent completion fish [flags]
```

```default
  -h, --help              help for fish
      --no-descriptions   disable completion descriptions
```

```default
  -c, --config string     configuration file path
  -v, --verbosity count   issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output
```

--------------------------------

### Backup and Uninstall Ubuntu-24.04 Instance

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/tutorials/deployment.md

Commands to terminate, export (backup), and unregister an existing Ubuntu-24.04 instance from WSL.

```text
> wsl --terminate Ubuntu-24.04
> mkdir backup
> wsl --export Ubuntu-24.04 .\backup\Ubuntu-24.04.tar.gz
> wsl --unregister Ubuntu-24.04
```

--------------------------------

### Bash Autocompletion

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/reference/07-windows-agent-command-line-reference.md

Commands to generate and install bash completion scripts.

```none
source <(ubuntu-pro-agent completion bash)
```

```none
ubuntu-pro-agent completion bash > /etc/bash_completion.d/ubuntu-pro-agent
```

```none
ubuntu-pro-agent completion bash > $(brew --prefix)/etc/bash_completion.d/ubuntu-pro-agent
```

```default
ubuntu-pro-agent completion bash
```

```default
  -h, --help              help for bash
      --no-descriptions   disable completion descriptions
```

```default
  -c, --config string     configuration file path
  -v, --verbosity count   issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output
```

--------------------------------

### List Ubuntu Pro commands

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/verify-subscribe-attach.md

Displays the help menu for the pro command-line tool to view available management options.

```text
$ pro --help
```

--------------------------------

### Clean Documentation Build Environment

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/docs/howto/contributing.md

Execute this command to clean the build environment for the documentation.

```text
make clean
```

--------------------------------

### Generate zsh autocompletion

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/wsl-pro-service/README.md

Commands to generate and install zsh completion scripts.

```bash
echo "autoload -U compinit; compinit" >> ~/.zshrc
```

```bash
source <(wsl-pro-service completion zsh)
```

```bash
wsl-pro-service completion zsh > "${fpath[1]}/_wsl-pro-service"
```

```bash
wsl-pro-service completion zsh > $(brew --prefix)/share/zsh/site-functions/_wsl-pro-service
```

```bash
wsl-pro-service completion zsh [flags]
```

--------------------------------

### Generate powershell autocompletion

Source: https://github.com/canonical/ubuntu-pro-for-wsl/blob/main/wsl-pro-service/README.md

Commands to generate and install powershell completion scripts.

```powershell
wsl-pro-service completion powershell | Out-String | Invoke-Expression
```

```powershell
wsl-pro-service completion powershell [flags]
```