From c2bbc86d030fc19c57f6637705951f16d503f9eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Tue, 28 Nov 2023 14:23:18 +0100 Subject: [PATCH 01/12] Simplify explanation for MSIX install No need for powershell, double-clicking is enough. --- docs/02-install.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/02-install.md b/docs/02-install.md index 4e8c041a6..a7fb47cd1 100644 --- a/docs/02-install.md +++ b/docs/02-install.md @@ -30,14 +30,9 @@ This is the Windows-side agent that manages the distros. 2. Follow the download steps to download UbuntuProForWindows 3. Unzip the artefact 4. Find the certificate inside. Install it into `Local Machine/Trusted people`. -5. Open Powershell in this directory and run - ```powershell - Add-AppxPackage .\UbuntuProForWindows_*_x64.msixbundle - ``` -6. Open the start menu and search for "Ubuntu Pro For Windows". -7. The Firewall may ask for an exception. Allow it. -8. The GUI should show up. You’re done. - +5. Double click on the MSIX bundle and complete the installation. +6. The Firewall may ask for an exception. Allow it. +7. The GUI should show up. You’re done. ## Install the WSL Pro Service This is the Linux-side component that talks to the agent. Choose one or more distros Jammy or greater, and follow the instructions. From c5ecb40d420e4c094d7cfb03544b1043b4632fd9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 29 Nov 2023 09:12:40 +0100 Subject: [PATCH 02/12] Update reset to factory settings Now that the filesystem is virtualized, we can reset to factory settings just by uninstalling the MSIX. --- docs/03-restart.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/03-restart.md b/docs/03-restart.md index e5a423631..6495a4925 100644 --- a/docs/03-restart.md +++ b/docs/03-restart.md @@ -26,12 +26,11 @@ This is the simple one. If you're not in a hurry to see the configuration update 8. Start the distro, or distros you installed WSL-Pro-Service in. # How to reset Ubuntu Pro for Windows back to factory settings -If you want to restart UP4W with factory settings, do: -1. Stop the agent and WSL: +You can reset UP4W to factory settings following these steps: +1. Uninstall the package and shut down WSL: ```powershell - Get-Process -Name "Ubuntu-Pro-Agent" | Stop-Process` + Get-AppxPackage -Name "CanonicalGroupLimited.UbuntuProForWindows" | Remove-AppxPackage` wsl --shutdown ``` -1. Remove folder `$env:LocalAppData\UbuntuPro`. 2. Remove registry key `HKEY_CURRENT_USER\Software\Canonical\UbuntuPro`. 3. You're done. Next time you start the GUI it'll be like a fresh install. From 7a6e39cd1afdef8849a5fe1187a83d87891357a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Tue, 28 Nov 2023 14:25:35 +0100 Subject: [PATCH 03/12] Create documentation file for the logs --- docs/06-access-the-logs.md | 2 ++ ...ference.md => 07-windows-agent-command-line-reference.md} | 0 ...rence.md => 08-wsl-pro-service-command-line-reference.md} | 0 docs/index.md | 5 +++-- windows-agent/generate/generate.yaml | 2 +- wsl-pro-service/generate/generate.yaml | 2 +- 6 files changed, 7 insertions(+), 4 deletions(-) create mode 100644 docs/06-access-the-logs.md rename docs/{06-windows-agent-command-line-reference.md => 07-windows-agent-command-line-reference.md} (100%) rename docs/{07-wsl-pro-service-command-line-reference.md => 08-wsl-pro-service-command-line-reference.md} (100%) diff --git a/docs/06-access-the-logs.md b/docs/06-access-the-logs.md new file mode 100644 index 000000000..5b73b188b --- /dev/null +++ b/docs/06-access-the-logs.md @@ -0,0 +1,2 @@ +# How to access the logs + diff --git a/docs/06-windows-agent-command-line-reference.md b/docs/07-windows-agent-command-line-reference.md similarity index 100% rename from docs/06-windows-agent-command-line-reference.md rename to docs/07-windows-agent-command-line-reference.md diff --git a/docs/07-wsl-pro-service-command-line-reference.md b/docs/08-wsl-pro-service-command-line-reference.md similarity index 100% rename from docs/07-wsl-pro-service-command-line-reference.md rename to docs/08-wsl-pro-service-command-line-reference.md diff --git a/docs/index.md b/docs/index.md index 60998d90c..f9fe6bad4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,6 +22,7 @@ Install <02-install> Restart Ubuntu Pro For Windows <03-restart> Auto-enable Ubuntu Pro <04-enable-pro> Auto-attach distros to Landscape <05-attach-landscape> -Windows Agent command line interface <06-windows-agent-command-line-reference> -WSL Pro Service command line interface <07-wsl-pro-service-command-line-reference> +How to access the logs <06-access-the-logs.md> +Windows Agent command line interface <07-windows-agent-command-line-reference> +WSL Pro Service command line interface <08-wsl-pro-service-command-line-reference> ``` diff --git a/windows-agent/generate/generate.yaml b/windows-agent/generate/generate.yaml index fbfa33b03..614df0fd4 100644 --- a/windows-agent/generate/generate.yaml +++ b/windows-agent/generate/generate.yaml @@ -1,7 +1,7 @@ project-root: ".." docs: readme: README.md - docs: ../docs/06-windows-agent-command-line-reference.md + docs: ../docs/07-windows-agent-command-line-reference.md man: generated/usr/share, completions: generated/usr/share i18n: diff --git a/wsl-pro-service/generate/generate.yaml b/wsl-pro-service/generate/generate.yaml index ce5d543d5..931210157 100644 --- a/wsl-pro-service/generate/generate.yaml +++ b/wsl-pro-service/generate/generate.yaml @@ -1,7 +1,7 @@ project-root: ".." docs: readme: README.md - docs: ../docs/07-wsl-pro-service-command-line-reference.md + docs: ../docs/08-wsl-pro-service-command-line-reference.md man: generated/usr/share, completions: generated/usr/share i18n: From 061b489bd3c958a9b3882b31cab26225be4d2687 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Tue, 28 Nov 2023 17:00:12 +0100 Subject: [PATCH 04/12] Write how to find the logs --- docs/06-access-the-logs.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/06-access-the-logs.md b/docs/06-access-the-logs.md index 5b73b188b..a4c55414a 100644 --- a/docs/06-access-the-logs.md +++ b/docs/06-access-the-logs.md @@ -1,2 +1,23 @@ # How to access the logs +At some point you may want to read the logs of Ubuntu Pro for Windows, most likely for debugging purposes. The agent and the service store their logs separately. This guide shows you were to find each of the logs. + +## WSL Pro service +In order to access the logs for a particular distro's WSL-Pro-Service, you need to start that distro and query the journal: +```bash +journalctl -u wsl-pro.service +``` +For more information on using the journal, you can check out its man page with `man journalctl` or [online](https://man7.org/linux/man-pages/man1/journalctl.1.html). + +These logs may be insufficient for proper debugging, so you may be interested in looking at the agent's logs as well. + +## Windows agent +Follow these steps in order to access the logs for the Windows agent. +1. On powershell, go to the package's directory: + ```powershell + Set-Location "$env:LocalAppData\Packages\CanonicalGroupLimited.UbuntuProForWindows_*" + Set-Location "LocalCache\Local\Ubuntu Pro" + ``` +2. If any of these folders do not exist, the Appx probably did not install. Otherwise, continue. +3. In the current folder, there should be various files. Modifying any of them could result in data loss. +4. Open file `log` with any text editor to see the logs. They are sorted from older at the top to newer at the bottom. \ No newline at end of file From c8446be97a3bc68f27adacaa7fb665be5620d378 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 29 Nov 2023 08:53:33 +0100 Subject: [PATCH 05/12] Add "distro's" to the dictionary This is not a good spellchecker :S --- docs/.custom_wordlist.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 7b5ebce0e..73c030cd2 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -8,6 +8,7 @@ enablement appx MSIX distro +distro's distros macOS powershell @@ -15,4 +16,4 @@ systemd ubuntu UbuntuProForWindows wsl -zsh +zsh \ No newline at end of file From 50f1cfa670dd6a75636d707b1c2f032b186aec94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 29 Nov 2023 08:58:40 +0100 Subject: [PATCH 06/12] Rename TOC entries to match their titles Some entries in the table of contents did not match the titles of the pages they link to. This is now fixed. --- docs/04-enable-pro.md | 2 +- docs/05-attach-landscape.md | 2 +- docs/index.md | 8 ++++---- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/04-enable-pro.md b/docs/04-enable-pro.md index a90380bc1..b2ef8a7b3 100644 --- a/docs/04-enable-pro.md +++ b/docs/04-enable-pro.md @@ -1,4 +1,4 @@ -# How to enable Ubuntu Pro with UP4W +# How to auto-attach distros to Ubuntu Pro ## Manual pro enablement 1. Go to your [Ubuntu Pro dashboard](https://ubuntu.com/pro) to get your Ubuntu Pro token. diff --git a/docs/05-attach-landscape.md b/docs/05-attach-landscape.md index 6e0881743..8d15f9df7 100644 --- a/docs/05-attach-landscape.md +++ b/docs/05-attach-landscape.md @@ -1,4 +1,4 @@ -# How to auto-register WSL distros to Landscape with UP4W +# How to auto-register distros to Landscape You can use a private Landscape instance (different from [landscape.canonical.com](https://landscape.canonical.com)). It must be over HTTP, as using certificates is not yet supported. To do so, follow these steps: 1. Find registry key `HKEY_CURRENT_USER\Software\Canonical\UbuntuPro`, field `LandscapeConfig`. 2. Copy the contents of the Landscape configuration file into the registry key: diff --git a/docs/index.md b/docs/index.md index f9fe6bad4..3a2415973 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,10 +18,10 @@ Thinking about using Ubuntu Pro for Windows for your next project? Get in touch! ```{toctree} :hidden: -Install <02-install> -Restart Ubuntu Pro For Windows <03-restart> -Auto-enable Ubuntu Pro <04-enable-pro> -Auto-attach distros to Landscape <05-attach-landscape> +How to install Ubuntu Pro for Windows <02-install> +How to restart Ubuntu Pro For Windows <03-restart> +How to auto-attach distros to Ubuntu Pro <04-enable-pro> +How to auto-register distros to Landscape <05-attach-landscape> How to access the logs <06-access-the-logs.md> Windows Agent command line interface <07-windows-agent-command-line-reference> WSL Pro Service command line interface <08-wsl-pro-service-command-line-reference> From 5e3167ebdc80bd77198313e98a74a7aca9d4dc9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 29 Nov 2023 09:19:56 +0100 Subject: [PATCH 07/12] Remove reference to LocalAppData/Ubuntu Pro in install section --- docs/02-install.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/02-install.md b/docs/02-install.md index a7fb47cd1..7b5e09d05 100644 --- a/docs/02-install.md +++ b/docs/02-install.md @@ -25,7 +25,6 @@ This is the Windows-side agent that manages the distros. 1. Uninstall Ubuntu Pro For Windows if you had installed previously: ```powershell Get-AppxPackage -Name Ubuntu-Pro-For-Windows | Remove-AppxPackage - Remove-Item -Recurse "${env:LOCALAPPDATA}/Ubuntu Pro" ``` 2. Follow the download steps to download UbuntuProForWindows 3. Unzip the artefact From cc644af1836b8cd63ddfba8f031c071c50173693 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 29 Nov 2023 10:59:52 +0100 Subject: [PATCH 08/12] Avoid abbreviations --- docs/03-restart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/03-restart.md b/docs/03-restart.md index 6495a4925..7d1b9b600 100644 --- a/docs/03-restart.md +++ b/docs/03-restart.md @@ -26,7 +26,7 @@ This is the simple one. If you're not in a hurry to see the configuration update 8. Start the distro, or distros you installed WSL-Pro-Service in. # How to reset Ubuntu Pro for Windows back to factory settings -You can reset UP4W to factory settings following these steps: +You can reset Ubuntu Pro For Windows to factory settings following these steps: 1. Uninstall the package and shut down WSL: ```powershell Get-AppxPackage -Name "CanonicalGroupLimited.UbuntuProForWindows" | Remove-AppxPackage` From 48480ebf52652f74da35086090941225d6f5b03a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 29 Nov 2023 11:01:43 +0100 Subject: [PATCH 09/12] Add missing install step in reinstallation --- docs/03-restart.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/03-restart.md b/docs/03-restart.md index 7d1b9b600..906432749 100644 --- a/docs/03-restart.md +++ b/docs/03-restart.md @@ -33,4 +33,5 @@ You can reset Ubuntu Pro For Windows to factory settings following these steps: wsl --shutdown ``` 2. Remove registry key `HKEY_CURRENT_USER\Software\Canonical\UbuntuPro`. -3. You're done. Next time you start the GUI it'll be like a fresh install. +3. Install the package again (see the section on [how to install](./02-install.md)). +4. You're done. Next time you start the GUI it'll be like a fresh install. From 7e003c3dd440492ff5bc51a4ac867c580ecb115c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 29 Nov 2023 11:02:25 +0100 Subject: [PATCH 10/12] Fix typo in logs documentation --- docs/06-access-the-logs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/06-access-the-logs.md b/docs/06-access-the-logs.md index a4c55414a..994afc29e 100644 --- a/docs/06-access-the-logs.md +++ b/docs/06-access-the-logs.md @@ -1,6 +1,6 @@ # How to access the logs -At some point you may want to read the logs of Ubuntu Pro for Windows, most likely for debugging purposes. The agent and the service store their logs separately. This guide shows you were to find each of the logs. +At some point you may want to read the logs of Ubuntu Pro for Windows, most likely for debugging purposes. The agent and the service store their logs separately. This guide shows you where to find each of the logs. ## WSL Pro service In order to access the logs for a particular distro's WSL-Pro-Service, you need to start that distro and query the journal: From 9f019155b1379e01cbca2790271f927449bb0d14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 29 Nov 2023 11:05:33 +0100 Subject: [PATCH 11/12] Improve clarity of logs documentation --- docs/06-access-the-logs.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/06-access-the-logs.md b/docs/06-access-the-logs.md index 994afc29e..41541550e 100644 --- a/docs/06-access-the-logs.md +++ b/docs/06-access-the-logs.md @@ -3,7 +3,7 @@ At some point you may want to read the logs of Ubuntu Pro for Windows, most likely for debugging purposes. The agent and the service store their logs separately. This guide shows you where to find each of the logs. ## WSL Pro service -In order to access the logs for a particular distro's WSL-Pro-Service, you need to start that distro and query the journal: +To access the logs of a specific distribution's WSL-Pro-Service, you must first launch the distribution and then query the journal: ```bash journalctl -u wsl-pro.service ``` @@ -18,6 +18,6 @@ Follow these steps in order to access the logs for the Windows agent. Set-Location "$env:LocalAppData\Packages\CanonicalGroupLimited.UbuntuProForWindows_*" Set-Location "LocalCache\Local\Ubuntu Pro" ``` -2. If any of these folders do not exist, the Appx probably did not install. Otherwise, continue. -3. In the current folder, there should be various files. Modifying any of them could result in data loss. -4. Open file `log` with any text editor to see the logs. They are sorted from older at the top to newer at the bottom. \ No newline at end of file +2. If any of these folders are missing, the Appx probably did not install. Otherwise, proceed with the next steps. +3. In the current folder, there should be various files. Be aware that modifying any of them could result in data loss. +4. Open file `log` with any text editor to see the logs. They are sorted with the oldest entries at the top and the newest at the bottom. \ No newline at end of file From 16540af8c5c545b8a63234112b5398c9edf8689b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 29 Nov 2023 11:06:50 +0100 Subject: [PATCH 12/12] Remove entry "distro's" from the dictionary It is no longer used so let's avoid needlessly bloating the wordlist. --- docs/.custom_wordlist.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 73c030cd2..d4a072855 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -8,7 +8,6 @@ enablement appx MSIX distro -distro's distros macOS powershell