diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 7b5ebce0e..d4a072855 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -15,4 +15,4 @@ systemd ubuntu UbuntuProForWindows wsl -zsh +zsh \ No newline at end of file diff --git a/docs/02-install.md b/docs/02-install.md index 4e8c041a6..7b5e09d05 100644 --- a/docs/02-install.md +++ b/docs/02-install.md @@ -25,19 +25,13 @@ 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 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. diff --git a/docs/03-restart.md b/docs/03-restart.md index e5a423631..906432749 100644 --- a/docs/03-restart.md +++ b/docs/03-restart.md @@ -26,12 +26,12 @@ 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 Ubuntu Pro For Windows 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. +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. 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/06-access-the-logs.md b/docs/06-access-the-logs.md new file mode 100644 index 000000000..41541550e --- /dev/null +++ b/docs/06-access-the-logs.md @@ -0,0 +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 where to find each of the logs. + +## WSL Pro service +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 +``` +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 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 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..3a2415973 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,10 +18,11 @@ 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> -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 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> ``` 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: