diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index f068fb797..361cb0c8c 100644 --- a/docs/.custom_wordlist.txt +++ b/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 diff --git a/docs/howto/assets/intune-platform-scripts.png b/docs/howto/assets/intune-platform-scripts.png new file mode 100755 index 000000000..1b512ef11 Binary files /dev/null and b/docs/howto/assets/intune-platform-scripts.png differ diff --git a/docs/howto/assets/intune-remediations.png b/docs/howto/assets/intune-remediations.png new file mode 100755 index 000000000..e84bdc702 Binary files /dev/null and b/docs/howto/assets/intune-remediations.png differ diff --git a/docs/howto/enforce-agent-startup-remotely-registry.md b/docs/howto/enforce-agent-startup-remotely-registry.md new file mode 100644 index 000000000..28053209e --- /dev/null +++ b/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. + diff --git a/docs/howto/index.md b/docs/howto/index.md index 99b055a42..3c536981b 100644 --- a/docs/howto/index.md +++ b/docs/howto/index.md @@ -14,4 +14,6 @@ Uninstalling UP4W, Ubuntu WSL apps and WSL Configure the Landscape client with UP4W Set up a Landscape server within WSL Create WSL instances on multiple Windows machines with the Landscape API +Enforce the UP4W background agent startup remotely using the Windows Registry +Start the UP4W background agent remotely ``` diff --git a/docs/howto/start-agent-remotely.md b/docs/howto/start-agent-remotely.md new file mode 100644 index 000000000..ec1982391 --- /dev/null +++ b/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. + diff --git a/msix/UbuntuProForWSL/Package.appxmanifest b/msix/UbuntuProForWSL/Package.appxmanifest index cf5204e8d..a868cee76 100644 --- a/msix/UbuntuProForWSL/Package.appxmanifest +++ b/msix/UbuntuProForWSL/Package.appxmanifest @@ -31,7 +31,7 @@ - +