feat(docs): How-to guides about UP4W agent startup (#944)

As agreed in WS037, I'm bringing two pieces of documentation about how
system administrators can have UP4W background agent start without
explicit end user interaction.

One guide relies on being able to start the agent via CLI (reason why
this PR is based on #941 ) by deploying an one-shot PowerShell script
via Intune to be executed with the current user's credentials.

The other guide relies on the registry, but leverages [Intune
Remediations](https://learn.microsoft.com/en-us/mem/intune/fundamentals/remediations)
to make that approach more reliable, by having that tool automatically
checking and fixing non-compliant state, thus multi-shot (should end
users disable the startup task, Intune would eventually find it and fix
it).

---

This PR completes UDENG-4623 and closes #912 .

docs/.custom_wordlist.txt

@@ -3,6 +3,8 @@ artifact
 artifacts
 autocompletion
 enablement
+Remediations
+remediations
 
 # Tools and brands
 apport
@@ -13,6 +15,7 @@ Codecov
 distro
 distros
 ESM
+Intune
 macOS
 MSIX
 powershell
@@ -65,9 +68,11 @@ zshrc
 ESM
 Ok
 scalability
+UTF
 
 # Registry keys and types
 DWORD
 UbuntuPro
+UbuntuProAutoStart
 UbuntuProToken
 LandscapeConfig

docs/howto/enforce-agent-startup-remotely-registry.md

@@ -0,0 +1,118 @@
+# How to enforce the UP4W background agent startup remotely using the Windows Registry
+
+Ubuntu Pro for WSL, being a Microsoft Store application, cannot ship user services as of the time of writing (late
+2024), but can deploy startup tasks instead, programs that run with user permissions when the user logs into the
+Windows device. The UP4W background agent runs as a startup task, which is only enabled by the
+operating system when the user interacts with the application for the first time. While this behaviour is a feature for
+end-users it presents a source of friction for deployments at scale, when system administrators expect zero-touch
+deployment of UP4W to just work.
+
+This guide shows how sysadmins can use the Windows Registry to enforce the enablement of the UP4W background agent
+startup task without depending on end-user interaction. While this guide uses
+[Intune](https://learn.microsoft.com/en-us/mem/intune/fundamentals/what-is-intune), it should be reproducible with any
+remote management solution capable of deploying MS Store (or MSIX-packaged) applications and registry keys.
+
+## Pre-requisites
+
+- At least one managed Windows device.
+- A Windows remote management solution.
+- If using Intune, an Enterprise E3 or E5 or Education A3 or A5 licenses.
+
+## Overview
+
+1. The registry path `"HKCU:\Software\Classes\Local Settings\Software\Microsoft\Windows\CurrentVersion\AppModel\SystemAppData\CanonicalGroupLimited.UbuntuPro_79rhkp1fndgsc"`
+   holds configuration information specific about UP4W and is created or overwritten when the MSIX package is
+   installed.
+2. A sub-key named `UbuntuProAutoStart` governs the startup task state.
+3. Setting the DWORD value named `State` to `4` makes the operating system interpret it as
+   ["Enabled by Policy"](https://learn.microsoft.com/en-us/uwp/api/windows.applicationmodel.startuptaskstate).
+4. When the user logs in, Windows executes the UP4W startup task, even if the user has not interacted with the application.
+5. A Windows remote management solution can monitor that registry key value and proactively fix it, thus enforcing the
+   UP4W startup task to be always enabled.
+
+(howto::enforce-with-intune)=
+## Using Intune Remediations
+
+Remediations are script packages that can detect and fix common issues on a user's device before they realise
+there's a problem. Each script package consists of a detection script, a remediation script, and metadata. Through
+Intune, you can deploy these script packages and monitor reports of their effectiveness.
+[Visit the Microsoft Intune documentation](https://learn.microsoft.com/en-us/mem/intune/fundamentals/remediations)
+to learn more. Those scripts run on a predefined schedule and if the detection script reports a failure (by
+`exit 1`) then the remediation script will run. That allows system administrators to watch for the specific Registry
+key value that represents the enablement of the UP4W background agent startup task. The contents of both scripts are
+presented below. **Make sure to save them encoded in UTF-8**, as required by Intune.
+
+### Detection script
+
+```powershell
+$Path = "HKCU:\Software\Classes\Local Settings\Software\Microsoft\Windows\CurrentVersion\AppModel\SystemAppData\CanonicalGroupLimited.UbuntuPro_79rhkp1fndgsc\UbuntuProAutoStart"
+$Name = "State"
+$Value = 4
+
+Try {
+    $Registry = Get-ItemProperty -Path $Path -Name $Name -ErrorAction Stop | Select-Object -ExpandProperty $Name
+    If ($Registry -eq $Value){
+        Write-Output "Compliant"
+        Exit 0
+    }
+    Write-Warning "Not Compliant"
+    Exit 1
+}
+Catch {
+    Write-Warning "Not Compliant"
+    Exit 1
+}
+```
+
+### Remediation script
+
+```powershell
+$Path = "HKCU:\Software\Classes\Local Settings\Software\Microsoft\Windows\CurrentVersion\AppModel\SystemAppData\CanonicalGroupLimited.UbuntuPro_79rhkp1fndgsc\UbuntuProAutoStart"
+$Name = "State"
+$KeyFormat = "DWORD"
+$value = 4
+
+
+try{
+    if(!(Test-Path $Path)){New-Item -Path $Path -Force}
+    if(!$Name){Set-Item -Path $Path -Value $Value}
+    else{Set-ItemProperty -Path $Path -Name $Name -Value $Value -Type $KeyFormat}
+    Write-Output "Key set: $Name = $Value"
+}catch{
+    Write-Error $_
+}
+
+```
+
+### Running the scripts with Intune
+
+Access your organisation's [Intune Admin Center](https://intune.microsoft.com) and when logged in go to **Devices > Monitor > Manage Devices > Scripts and remediations**.
+![Scripts and remediations option revealed in the Intune portal](./assets/intune-remediations.png).
+
+Click on the "Create" button to create a new script package. Fill in the **Basics** form with name, description and other details and proceed to **Settings**.
+During that step, upload the scripts in the correct boxes and use the following options:
+
+- Run this script using the logged-on credentials (important because the script refers to a registry path under `HKCU`
+  a.k.a `HKEY_CURRENT_USER`)
+- Enforce script signature check: No (unless otherwise required by your company's policies)
+- Run script in 64-bit PowerShell: No
+
+Finally, select "Next" and assign "Scope tags" (if relevant) and in the "Assignments" select
+the device or user groups that are required.
+
+Follow [this guide](https://learn.microsoft.com/en-us/mem/intune/fundamentals/remediations#deploy-the-script-packages)
+if you need more detail on the steps outlined above.
+
+When users covered by the assignment next log in, Intune executes the detection script and then runs the remediation
+script if the device is found to be non-compliant.
+
+## Remarks
+
+Careful readers may notice that there is an inherent race condition between setting the registry value and installing
+the MSIX (if remotely deployed): when the MSIX is installed the registry sub-key that is referenced is recreated, overwriting any
+previous value that the remote management solution would have deployed if that happened before the package installation.
+
+An advantage of Intune Remediation scripts in this scenario is that eventually Intune finds the non-compliant
+state and fixes it automatically. A potential disadvantage is that the fix doesn't start the UP4W background
+agent, The fix enables the startup task and the agent will start at next user login.
+

docs/howto/index.md

@@ -14,4 +14,6 @@ Uninstalling UP4W, Ubuntu WSL apps and WSL <uninstalling>
 Configure the Landscape client with UP4W  <set-up-landscape-client>
 Set up a Landscape server within WSL <set-up-landscape-server-in-wsl>
 Create WSL instances on multiple Windows machines with the Landscape API <custom-rootfs-multiple-targets>
+Enforce the UP4W background agent startup remotely using the Windows Registry <enforce-agent-startup-remotely-registry>
+Start the UP4W background agent remotely <start-agent-remotely>
 ```

docs/howto/start-agent-remotely.md

@@ -0,0 +1,73 @@
+# How to start the agent remotely
+
+Ubuntu Pro for WSL, being a Microsoft Store application, cannot ship user services as of the time of writing (late
+2024), but can deploy startup tasks instead, programs that run with user permissions when the user logs into the
+Windows device. The UP4W background agent runs as a startup task, which is only enabled by the
+operating system when the user interacts with the application for the first time. While this behaviour is a feature for
+end-users it presents a source of friction for deployments at scale, when system administrators expect zero-touch
+deployment of UP4W to just work.
+
+This guide shows how system administrators can leverage Windows remote management solutions to start the UP4W background agent once
+with user credentials, thus interacting with the application on the user's behalf. Subsequent logins will have the UP4W
+background agent started automatically as a consequence of the interaction.
+
+While this guide uses Intune, readers can translate the steps for the remote management solution of their
+choice, as long as the said solution can run scripts with current user's credentials.
+
+## Pre-requisites
+
+- At least one managed Windows device.
+- A Windows remote management solution.
+
+## Overview
+
+1. Running a script as user to start the UP4W background agent makes it immediately available.
+2. Remote management solutions can be used to start the agent.
+3. The startup task is then also enabled on the operating system.
+4. On subsequent logins, the UP4W background agent starts automatically, as expected.
+
+## Using Intune to run the UP4W background agent
+
+The contents of the script can be far more elaborate, but for the purposes of this guide the following is enough:
+
+```powershell
+Write-Output "Starting the UP4W background agent remotely from Intune"
+ubuntu-pro-agent.exe
+```
+**Make sure to save that as UTF-8**, as required by Intune.
+
+```{note}
+Follow [this section from Intune documentation](https://learn.microsoft.com/en-us/mem/intune/apps/intune-management-extension#create-a-script-policy-and-assign-it)
+if you need more detailed step-by-step guide on how to create and assign script policies.
+```
+
+Access your organisation's [Intune Admin Center](https://intune.microsoft.com) and when logged in go to **Devices > Monitor > Manage Devices > Scripts and remediations**.
+On that page, click on the **Platform scripts** tab.
+![Platform scripts revealed under Devices > Scripts and remediations](./assets/intune-platform-scripts.png)
+
+Click on the "Add" button to create a new script policy and select the platform **Windows 10 and later**.
+
+Fill in the **Basics** form with a name and description for the script being created.
+
+In the **Settings** tab, browse your machine to the PowerShell script to be deployed, and select the following options:
+- Run this script using the logged on credentials: Yes (the default). UP4W must run with user credentials.
+- Enforce script signature check: No (unless required otherwise by your company's policies).
+- Run script in 64-bit PowerShell host: No (the default).
+
+Apply the "Scope tags" according to your company's practices and, in "Assignments" make sure to select one or more
+groups encompassing the users that must receive and run the script.
+
+You can then monitor the execution of this script in the Intune Admin Center.
+
+When the selected users log in to their devices, Intune will eventually start the UP4W background agent. A terminal window
+will appear to the user showing its regular outputs. This will only happen once.
+
+## Remarks
+
+Careful readers might have noticed that if the script is deployed in conjunction with a policy installing the UP4W, it
+would be theoretically possible to have the script running before the application gets installed. A more elaborate
+solution is required if that scenario is possible, like looping in the script or using a more proactive solution such as
+[Intune Remediations](https://learn.microsoft.com/en-us/mem/intune/fundamentals/remediations).
+
+[This guide](howto::enforce-with-intune) shows how to use that tool to enforce the UP4W startup task state.
+

msix/UbuntuProForWSL/Package.appxmanifest

@@ -31,7 +31,7 @@
       </uap:VisualElements>
       <Extensions>
         <uap5:Extension Category="windows.startupTask" Executable="agent\ubuntu-pro-agent-launcher.exe" EntryPoint="Windows.FullTrustApplication">
-          <uap5:StartupTask TaskId="UbuntuPro" Enabled="true" DisplayName="Ubuntu Pro for WSL background agent" />
+          <uap5:StartupTask TaskId="UbuntuProAutoStart" Enabled="true" DisplayName="Ubuntu Pro for WSL background agent" />
         </uap5:Extension>
         <uap3:Extension Category="windows.appExecutionAlias" Executable="agent\ubuntu-pro-agent.exe" EntryPoint="Windows.FullTrustApplication">
           <uap3:AppExecutionAlias>