From 10cdf43ce2645f3002d9c53dbf19e79e3d7400c7 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 26 Nov 2024 15:38:34 +0000 Subject: [PATCH 01/11] update path for autogen CLI refs --- windows-agent/generate/generate.yaml | 2 +- wsl-pro-service/generate/generate.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/windows-agent/generate/generate.yaml b/windows-agent/generate/generate.yaml index d1d566964..111535181 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/dev/reference/07-windows-agent-command-line-reference.md + docs: ../docs/reference/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 69ed1fa2c..40e0519e5 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/dev/reference/08-wsl-pro-service-command-line-reference.md + docs: ../docs/reference/08-wsl-pro-service-command-line-reference.md man: generated/usr/share, completions: generated/usr/share i18n: From 6bf50c654b6bf5f29bcc201bc61b2c7d247741fe Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 26 Nov 2024 15:40:35 +0000 Subject: [PATCH 02/11] adjust homepage grid these are just simple changes to improve presentation and interaction: - remove dev section - adjust grid arrangement for three cards - make entire card clickable --- docs/index.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/index.md b/docs/index.md index c2b15af33..b96d9d9a8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,33 +15,34 @@ Read our [getting started tutorial](tutorial/getting-started) to begin. ## In this documentation -````{grid} 1 1 2 2 +````{grid} 1 1 1 1 ```{grid-item-card} [Tutorials](tutorial/index) +:link: tutorial/index +:link-type: doc **Start here** with hands-on tutorials for new users, guiding you through your first-steps ``` +```` + +````{grid} 1 1 2 2 + ```{grid-item-card} [How-to guides](howto/index) +:link: howto/index +:link-type: doc **Follow step-by-step** instructions for key operations and common tasks ``` -```` - -````{grid} 1 1 2 2 -:reverse: ```{grid-item-card} [Reference](reference/index) +:link: reference/index +:link-type: doc **Read technical descriptions** of important factual information relating to UP4W ``` -```{grid-item-card} [UP4W Dev](dev/index) - -**Review guides and reference material** aimed at contributors -``` - ```` ## Project and community @@ -58,5 +59,4 @@ UP4W Tutorial How-to guides Reference -UP4W Dev ``` From 1ae4eba09cba173bf0435cd4ab1e755d0c329056 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 26 Nov 2024 15:41:34 +0000 Subject: [PATCH 03/11] remove dev folder content is incorporated into howto and ref sections --- docs/dev/howto/02-install.md | 72 ----- docs/dev/howto/03-restart.md | 33 --- docs/dev/howto/06-access-the-logs.md | 26 -- docs/dev/howto/07-toggle-features.md | 33 --- docs/dev/howto/index.md | 15 - docs/dev/howto/reset-factory.md | 27 -- docs/dev/index.md | 12 - ...07-windows-agent-command-line-reference.md | 263 ------------------ ...-wsl-pro-service-command-line-reference.md | 241 ---------------- docs/dev/reference/09-qa-process-reference.md | 77 ----- docs/dev/reference/index.md | 14 - 11 files changed, 813 deletions(-) delete mode 100644 docs/dev/howto/02-install.md delete mode 100644 docs/dev/howto/03-restart.md delete mode 100644 docs/dev/howto/06-access-the-logs.md delete mode 100644 docs/dev/howto/07-toggle-features.md delete mode 100644 docs/dev/howto/index.md delete mode 100644 docs/dev/howto/reset-factory.md delete mode 100644 docs/dev/index.md delete mode 100644 docs/dev/reference/07-windows-agent-command-line-reference.md delete mode 100644 docs/dev/reference/08-wsl-pro-service-command-line-reference.md delete mode 100644 docs/dev/reference/09-qa-process-reference.md delete mode 100644 docs/dev/reference/index.md diff --git a/docs/dev/howto/02-install.md b/docs/dev/howto/02-install.md deleted file mode 100644 index 0f7741607..000000000 --- a/docs/dev/howto/02-install.md +++ /dev/null @@ -1,72 +0,0 @@ -# How to install UP4W - -This guide will show you how to install UP4W for local development and testing. - -
- -**Requirements:** - -- A Windows machine with access to the internet -- Appx from the Microsoft Store: - - Windows Subsystem For Linux - - Either Ubuntu, Ubuntu 22.04, or Ubuntu (Preview) -- The Windows Subsystem for Windows optional feature enabled - -## 1. Download the Windows Agent and the WSL Pro Service - -1. Go to the [repository actions page](https://github.com/canonical/ubuntu-pro-for-wsl/actions/workflows/qa-azure.yaml?query=branch%3Amain+). -2. Click the latest successful workflow run. -3. Scroll down past any warnings or errors, until you reach the Artifacts section. -4. Download: - - Windows agent: UbuntuProForWSL+...-production - - wsl-pro-service: Wsl-pro-service_... - -Notice that, for the step above, there is also an alternative version of the MSIX bundle enabled for end-to-end testing. Most likely, that's not what you want to download. - -(dev::install-agent)= -## 2. Install the Windows Agent - -This is the Windows-side agent that manages the distros. - -1. Uninstall Ubuntu Pro for WSL if you had installed previously: - - ```powershell - Get-AppxPackage -Name CanonicalGroupLimited.UbuntuPro | Remove-AppxPackage - ``` - -2. Follow the download steps to download UbuntuProForWSL -3. Unzip the artefact -4. Find the certificate inside. Install it into `Local Machine/Trusted people`. -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. - -## 3. 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. - -1. Uninstall the WSL-Pro-Service from your distro if you had it installed previously: - - ```bash - sudo apt remove wsl-pro-service - ``` - -2. Follow the download steps to download the WSL-Pro-Service. -3. Unzip the artifact. -4. Navigate to the unzipped directory containing the .deb file. Here is a possible path: - - ```bash - cd /mnt/c/Users/WINDOWS-USER/Downloads/wsl-pro-service_* - ``` - -5. Install the deb package. - - ```bash - sudo apt install ./wsl-pro-service_*.deb - ``` - -6. Ensure it works via systemd: - - ```bash - systemctl status wsl-pro.service - ``` diff --git a/docs/dev/howto/03-restart.md b/docs/dev/howto/03-restart.md deleted file mode 100644 index dc4391eaa..000000000 --- a/docs/dev/howto/03-restart.md +++ /dev/null @@ -1,33 +0,0 @@ -# How to restart UP4W - -Some configuration changes only apply when you restart UP4W. Here is a guide on how to restart it. There are two options. - -## Option 1: Restart your UP4W host machine - -This is the simple one. If you're not in a hurry to see the configuration updated, just wait until next time you boot your machine. - -## Option 2: Restart only UP4W - -1. Stop the agent: - - ```powershell - Get-Process -Name Ubuntu-Pro-Agent | Stop-Process - ``` - -2. Stop the distro, or distros you installed WSL-Pro-Service in: - - ```powershell - wsl --terminate DISTRO_NAME_1 - wsl --terminate DISTRO_NAME_2 - # etc. - - # Alternatively, stop all distros: - wsl --shutdown - ``` - -7. Start the agent again: - 1. Open the start Menu and search for "Ubuntu Pro for WSL". - 2. The GUI should start. - 3. Wait a minute. - 4. Click on "Click to restart it". -8. Start the distro, or distros you installed WSL-Pro-Service in. diff --git a/docs/dev/howto/06-access-the-logs.md b/docs/dev/howto/06-access-the-logs.md deleted file mode 100644 index 50400dc8c..000000000 --- a/docs/dev/howto/06-access-the-logs.md +++ /dev/null @@ -1,26 +0,0 @@ -# How to access UP4W logs - -At some point you may want to read the UP4W logs, 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. - -## Access the logs for the 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. - -## Access the logs for the Windows Agent - -To access the logs for the Windows Agent: - -1. Go to your home directory - - Open the file explorer - - Write `%USERPROFILE%` at the address -2. In the home directory, find the `.ubuntupro` directory and double-click on it. -2. In the `.ubuntupto` folder, find file `log` and open it with any text editor. - - This file contains the logs sorted with the oldest entries at the top and the newest at the bottom. diff --git a/docs/dev/howto/07-toggle-features.md b/docs/dev/howto/07-toggle-features.md deleted file mode 100644 index de9e4c649..000000000 --- a/docs/dev/howto/07-toggle-features.md +++ /dev/null @@ -1,33 +0,0 @@ -# How to enable opt-in features - -Some features in UP4W are opt-in or can be toggled on and off via the Windows Registry. -While the code is arranged such that CI always tests with those features enabled, -when running UP4W on your machine, you may need to toggle them on and off -explicitly via the Windows registry. This guide shows you how to do that. - -## Enable subscribing via the Microsoft Store - -1. Open the Windows registry editor: press `Win + R`, type `regedit` and press `Enter`. -1. Navigate to the following key: `HKEY_CURRENT_USER\Software\Canonical\UbuntuPro\`. -1. Create a new DWORD value named `AllowStorePurchase` and set it to `1`. - -The next time you open the GUI you'll find the button to subscribe to Ubuntu -Pro via the Microsoft Store. - -```{warning} -Beware that can incur in real charges if you proceed with the purchase. -``` - -## Disable Landscape configuration in the GUI - -Landscape configuration page and related buttons are enabled by default, but can be disabled via registry. - -1. Open the Windows registry editor: press `Win + R`, type `regedit` and press `Enter`. -1. Navigate to the following key: `HKEY_CURRENT_USER\Software\Canonical\UbuntuPro\`. -1. Create a new DWORD value named `LandscapeConfigVisibility` and set it to `0`. - -The next time you open the GUI, you'll find that the Landscape configuration -page can be shown via the set up wizard or by clicking on the 'Configure -Landscape' button. -If that value is not present or set to anything other than `0`, Landscape configuration page -and related buttons will be visible. diff --git a/docs/dev/howto/index.md b/docs/dev/howto/index.md deleted file mode 100644 index b5db4c6a0..000000000 --- a/docs/dev/howto/index.md +++ /dev/null @@ -1,15 +0,0 @@ -(dev-howtos)= - -# How-to guides - -These how-to guides cover key operations and processes in Ubuntu Pro for WSL. - -```{toctree} -:titlesonly: - -Install UP4W <02-install> -Restart UP4W <03-restart> -Access UP4W logs <06-access-the-logs> -Enable opt-in features <07-toggle-features> -Reset UP4W -``` diff --git a/docs/dev/howto/reset-factory.md b/docs/dev/howto/reset-factory.md deleted file mode 100644 index 38f6758d9..000000000 --- a/docs/dev/howto/reset-factory.md +++ /dev/null @@ -1,27 +0,0 @@ -# How to reset UP4W back to factory settings - -You can reset Ubuntu Pro for WSL to factory settings following these steps: - -1. Shut down WSL - ```powershell - wsl --shutdown - ``` -2. Uninstall the package and shut down WSL: - - ```powershell - Get-AppxPackage -Name "CanonicalGroupLimited.UbuntuPro" | Remove-AppxPackage` - ``` -3. Remove the public directory: - ```powershell - Remove-Item -Recurse -Force "${env:UserProfile}\.ubuntupro\" - ``` -4. Remove the registry key: - 1. Press Win+R - 2. Type `regedit.exe` and click OK - 3. Write `HKEY_CURRENT_USER\Software\Canonical\UbuntuPro` at the address bar - - If this fails, you are done (the key does not exist). - 4. Find the `UbuntuPro` key on the left - 5. Right-click on it - 6. Click delete -5. Install the Windows Agent package again (see the section on [how to install](dev::install-agent)). You do not need to re-install the WSL-Pro-Service. -6. You're done. Next time you start the GUI it'll be like a fresh install. diff --git a/docs/dev/index.md b/docs/dev/index.md deleted file mode 100644 index 360616377..000000000 --- a/docs/dev/index.md +++ /dev/null @@ -1,12 +0,0 @@ -(dev)= - -# Ubuntu Pro for WSL - developer documentation - -Welcome - -```{toctree} -:titlesonly: - -howto/index -reference/index -``` diff --git a/docs/dev/reference/07-windows-agent-command-line-reference.md b/docs/dev/reference/07-windows-agent-command-line-reference.md deleted file mode 100644 index fdc638282..000000000 --- a/docs/dev/reference/07-windows-agent-command-line-reference.md +++ /dev/null @@ -1,263 +0,0 @@ -# Windows Agent CLI - -> See first: [UP4W - Windows Agent](ref::up4w-windows-agent) - - -## Usage - -### User commands - -#### ubuntu-pro-agent - -Ubuntu Pro for WSL agent - -##### Synopsis - -Ubuntu Pro for WSL agent for managing your pro-enabled distro. - -``` -ubuntu-pro-agent COMMAND [flags] -``` - -##### Options - -``` - -c, --config string configuration file path - -h, --help help for ubuntu-pro-agent - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### ubuntu-pro-agent clean - -Removes all the agent's data and exits - -``` -ubuntu-pro-agent clean [flags] -``` - -##### Options - -``` - -h, --help help for clean -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### ubuntu-pro-agent completion - -Generate the autocompletion script for the specified shell - -##### Synopsis - -Generate the autocompletion script for ubuntu-pro-agent for the specified shell. -See each sub-command's help for details on how to use the generated script. - - -##### Options - -``` - -h, --help help for completion -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### ubuntu-pro-agent completion bash - -Generate the autocompletion script for bash - -##### Synopsis - -Generate the autocompletion script for the bash shell. - -This script depends on the 'bash-completion' package. -If it is not installed already, you can install it via your OS's package manager. - -To load completions in your current shell session: - - source <(ubuntu-pro-agent completion bash) - -To load completions for every new session, execute once: - -###### Linux: - - ubuntu-pro-agent completion bash > /etc/bash_completion.d/ubuntu-pro-agent - -###### macOS: - - ubuntu-pro-agent completion bash > $(brew --prefix)/etc/bash_completion.d/ubuntu-pro-agent - -You will need to start a new shell for this setup to take effect. - - -``` -ubuntu-pro-agent completion bash -``` - -##### Options - -``` - -h, --help help for bash - --no-descriptions disable completion descriptions -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### ubuntu-pro-agent completion fish - -Generate the autocompletion script for fish - -##### Synopsis - -Generate the autocompletion script for the fish shell. - -To load completions in your current shell session: - - ubuntu-pro-agent completion fish | source - -To load completions for every new session, execute once: - - ubuntu-pro-agent completion fish > ~/.config/fish/completions/ubuntu-pro-agent.fish - -You will need to start a new shell for this setup to take effect. - - -``` -ubuntu-pro-agent completion fish [flags] -``` - -##### Options - -``` - -h, --help help for fish - --no-descriptions disable completion descriptions -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### ubuntu-pro-agent completion powershell - -Generate the autocompletion script for powershell - -##### Synopsis - -Generate the autocompletion script for powershell. - -To load completions in your current shell session: - - ubuntu-pro-agent completion powershell | Out-String | Invoke-Expression - -To load completions for every new session, add the output of the above command -to your powershell profile. - - -``` -ubuntu-pro-agent completion powershell [flags] -``` - -##### Options - -``` - -h, --help help for powershell - --no-descriptions disable completion descriptions -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### ubuntu-pro-agent completion zsh - -Generate the autocompletion script for zsh - -##### Synopsis - -Generate the autocompletion script for the zsh shell. - -If shell completion is not already enabled in your environment you will need -to enable it. You can execute the following once: - - echo "autoload -U compinit; compinit" >> ~/.zshrc - -To load completions in your current shell session: - - source <(ubuntu-pro-agent completion zsh) - -To load completions for every new session, execute once: - -###### Linux: - - ubuntu-pro-agent completion zsh > "${fpath[1]}/_ubuntu-pro-agent" - -###### macOS: - - ubuntu-pro-agent completion zsh > $(brew --prefix)/share/zsh/site-functions/_ubuntu-pro-agent - -You will need to start a new shell for this setup to take effect. - - -``` -ubuntu-pro-agent completion zsh [flags] -``` - -##### Options - -``` - -h, --help help for zsh - --no-descriptions disable completion descriptions -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### ubuntu-pro-agent version - -Returns version of agent and exits - -``` -ubuntu-pro-agent version [flags] -``` - -##### Options - -``` - -h, --help help for version -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -### Hidden commands - -Those commands are hidden from help and should primarily be used by the system or for debugging. - diff --git a/docs/dev/reference/08-wsl-pro-service-command-line-reference.md b/docs/dev/reference/08-wsl-pro-service-command-line-reference.md deleted file mode 100644 index 5c3b93727..000000000 --- a/docs/dev/reference/08-wsl-pro-service-command-line-reference.md +++ /dev/null @@ -1,241 +0,0 @@ -# WSL Pro Service CLI - -> See first: [UP4W - WSL Pro Service](ref::up4w-wsl-pro-service) - -## Usage - -### User commands - -#### wsl-pro-service - -WSL Pro Service - -##### Synopsis - -WSL Pro Service connects Ubuntu Pro for WSL agent to your distro. - -``` -wsl-pro-service COMMAND [flags] -``` - -##### Options - -``` - -c, --config string configuration file path - -h, --help help for wsl-pro-service - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### wsl-pro-service completion - -Generate the autocompletion script for the specified shell - -##### Synopsis - -Generate the autocompletion script for wsl-pro-service for the specified shell. -See each sub-command's help for details on how to use the generated script. - - -##### Options - -``` - -h, --help help for completion -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### wsl-pro-service completion bash - -Generate the autocompletion script for bash - -##### Synopsis - -Generate the autocompletion script for the bash shell. - -This script depends on the 'bash-completion' package. -If it is not installed already, you can install it via your OS's package manager. - -To load completions in your current shell session: - - source <(wsl-pro-service completion bash) - -To load completions for every new session, execute once: - -###### Linux: - - wsl-pro-service completion bash > /etc/bash_completion.d/wsl-pro-service - -###### macOS: - - wsl-pro-service completion bash > $(brew --prefix)/etc/bash_completion.d/wsl-pro-service - -You will need to start a new shell for this setup to take effect. - - -``` -wsl-pro-service completion bash -``` - -##### Options - -``` - -h, --help help for bash - --no-descriptions disable completion descriptions -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### wsl-pro-service completion fish - -Generate the autocompletion script for fish - -##### Synopsis - -Generate the autocompletion script for the fish shell. - -To load completions in your current shell session: - - wsl-pro-service completion fish | source - -To load completions for every new session, execute once: - - wsl-pro-service completion fish > ~/.config/fish/completions/wsl-pro-service.fish - -You will need to start a new shell for this setup to take effect. - - -``` -wsl-pro-service completion fish [flags] -``` - -##### Options - -``` - -h, --help help for fish - --no-descriptions disable completion descriptions -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### wsl-pro-service completion powershell - -Generate the autocompletion script for powershell - -##### Synopsis - -Generate the autocompletion script for powershell. - -To load completions in your current shell session: - - wsl-pro-service completion powershell | Out-String | Invoke-Expression - -To load completions for every new session, add the output of the above command -to your powershell profile. - - -``` -wsl-pro-service completion powershell [flags] -``` - -##### Options - -``` - -h, --help help for powershell - --no-descriptions disable completion descriptions -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### wsl-pro-service completion zsh - -Generate the autocompletion script for zsh - -##### Synopsis - -Generate the autocompletion script for the zsh shell. - -If shell completion is not already enabled in your environment you will need -to enable it. You can execute the following once: - - echo "autoload -U compinit; compinit" >> ~/.zshrc - -To load completions in your current shell session: - - source <(wsl-pro-service completion zsh) - -To load completions for every new session, execute once: - -###### Linux: - - wsl-pro-service completion zsh > "${fpath[1]}/_wsl-pro-service" - -###### macOS: - - wsl-pro-service completion zsh > $(brew --prefix)/share/zsh/site-functions/_wsl-pro-service - -You will need to start a new shell for this setup to take effect. - - -``` -wsl-pro-service completion zsh [flags] -``` - -##### Options - -``` - -h, --help help for zsh - --no-descriptions disable completion descriptions -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -#### wsl-pro-service version - -Returns version of agent and exits - -``` -wsl-pro-service version [flags] -``` - -##### Options - -``` - -h, --help help for version -``` - -##### Options inherited from parent commands - -``` - -c, --config string configuration file path - -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output -``` - -### Hidden commands - -Those commands are hidden from help and should primarily be used by the system or for debugging. - diff --git a/docs/dev/reference/09-qa-process-reference.md b/docs/dev/reference/09-qa-process-reference.md deleted file mode 100644 index 3f236434c..000000000 --- a/docs/dev/reference/09-qa-process-reference.md +++ /dev/null @@ -1,77 +0,0 @@ -# QA Process - -## Generalities - -`wsl-pro-service` is seeded only on WSL images. - -``` -Build-dep: golang-go (\>= 2:1.21\~) -``` - -At any point in time, only the latest two versions of the Go toolchain receive security patches. Hence, we need to keep backporting new releases to fix vulnerabilities. They follow an approximate 6-month release cycle, so Go 1.21 should fall out of support by August 2024. - -## Process - -WSL Pro Service follows a robust continuous integration and testing process. It is covered by [a comprehensive automated test suite](https://github.com/canonical/ubuntu-pro-for-wsl/actions/workflows/qa.yaml). - -The team applies the following quality criteria: - -- All changes are thoroughly reviewed and approved by core team members before integration. -- Each change is thoroughly tested at the unit, integration and system levels. All the tests pass in all supported architectures. -- Releases are reviewed as part of the [SRU exception](https://wiki.ubuntu.com/UbuntuProForWSLUpdates). - -The test plan is **completely automated** and runs **every time a change is merged**, as well as **during packaging**. This covers integration and end-to-end tests. Integration tests run on each LTS affected by the SRU to ensure compatibility. - -Testing also covers the upgrade from the current version to the proposed version. - -Tests are not executed on different versions of Windows due to testing environment limitations. - -## Packaging QA - -To prepare the release to LTS, the following procedure is being completed to ensure quality: - -- All autopkgtests pass. Unit tests are executed as autopkgtests. Running higher-level tests would require a Windows VM. It is not available in autopkgtest at the moment. Even if wsl-pro-service tests could run in a VM, they wouldn't test anything real. -- The package does not break when upgrading. -- The binary is identical to the CI build, with only Debian packaging changes. -- The copyrights and changelog are up to date. -- An upgrade test from the previous package version has been performed using apt install/upgrade. - -## Code sanity - -Code sanity checks are performed automatically on each build. They verify: - -- Code linting. -- Go module files are up to date. -- Generated files are up to date. -- Any binary in the project builds. -- The Debian package builds. -- Vulnerabilities. It is a run of `govulncheck`. - -All the layers are tested from APIs to mocks to the service itself - -### Example reports - -- Code sanity and unit testing: [QA workflow](https://github.com/canonical/ubuntu-pro-for-wsl/actions/workflows/qa.yaml?query=branch%3Amain) -- Integration tests: [end-to-to-end tests workflow](https://github.com/canonical/ubuntu-pro-for-wsl/actions/workflows/qa-azure.yaml?query=branch%3Amain) - - -![image](https://github.com/canonical/ubuntu-pro-for-wsl/assets/1928546/649084df-1889-471a-a211-df3ae890a8fd) - -## Code coverage - -There is no Codecov report due to the limitations of private projects. -However, code coverage is calculated and displayed at testing time. -Coverage is manually reviewed by the engineers. - -## Bug reporting - -The main bug tracker remains on GitHub. [GitHub Templates](https://github.com/canonical/ubuntu-pro-for-wsl/issues/new/choose) -are available to help the user with the bug-reporting process and provide the right information. - -Wsl-pro supports ubuntu-bug reporting to Launchpad with an apport hook but we are not collecting any data at the moment. - -## References - -- [Project Documentation](https://canonical-ubuntu-pro-for-wsl.readthedocs-hosted.com/en/latest/) -- [Ubuntu Pro for WSL SRU exception](https://wiki.ubuntu.com/UbuntuProForWSLUpdates) -- [Ubuntu Pro tools SRU exception](https://wiki.ubuntu.com/UbuntuAdvantageToolsUpdates) diff --git a/docs/dev/reference/index.md b/docs/dev/reference/index.md deleted file mode 100644 index b5de36c8e..000000000 --- a/docs/dev/reference/index.md +++ /dev/null @@ -1,14 +0,0 @@ -(reference)= - -# Reference - -The reference material in this section provides technical descriptions of Ubuntu Pro for WSL. - -```{toctree} -:titlesonly: - - -Windows Agent CLI <07-windows-agent-command-line-reference> -WSL Pro Service CLI <08-wsl-pro-service-command-line-reference> -QA process <09-qa-process-reference> -``` From 6d5e28fcb3a34781ece36c35c3c54727481559aa Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 26 Nov 2024 15:45:31 +0000 Subject: [PATCH 04/11] delete unused image --- docs/reference/assets/Landscape.drawio.svg | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 docs/reference/assets/Landscape.drawio.svg diff --git a/docs/reference/assets/Landscape.drawio.svg b/docs/reference/assets/Landscape.drawio.svg deleted file mode 100644 index 5b883f16d..000000000 --- a/docs/reference/assets/Landscape.drawio.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
Windows host
Windows host
Ubuntu Pro for WSL Agent
Ubuntu Pro for WSL Ag...
WSL distro
WSL distro
configures
configures
wsl-pro.service
wsl-pro.service
Distro management
commands
Distro management...
landscape-client.service
landscape-client.service
Lifetime management
commands
Lifetime management...
sends
configuration
sends...
configures
configures
Configuration module
Configuration module
executes
commands
executes...
System and WSL
information
System and WSL...
Landscape service
Landscape service
Windows registry
Windows registry
Distro
information
Distro...
reads
reads
Landscape server
Landscape serverText is not SVG - cannot display \ No newline at end of file From d3837032aa3da87c42f62c5494b59e7238fd7101 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 26 Nov 2024 15:46:26 +0000 Subject: [PATCH 05/11] delete using landscape server on WSL guide --- docs/howto/set-up-landscape-server-in-wsl.md | 99 -------------------- 1 file changed, 99 deletions(-) delete mode 100644 docs/howto/set-up-landscape-server-in-wsl.md diff --git a/docs/howto/set-up-landscape-server-in-wsl.md b/docs/howto/set-up-landscape-server-in-wsl.md deleted file mode 100644 index af04385d1..000000000 --- a/docs/howto/set-up-landscape-server-in-wsl.md +++ /dev/null @@ -1,99 +0,0 @@ -# Install Landscape server in a WSL instance - -## Motivation - -While a Landscape server typically runs on external computers, it can also be -set up on a WSL instance on a Windows machine. - -This is especially useful if you want to test UP4W on a single Windows device. -For example, the [deployment tutorial](../tutorial/deployment) can be completed with a Landscape -server running in an Ubuntu WSL instance. The Landscape server can then be used -to manage other WSL instances running UP4W and the Landscape client. - -(howto::config-landscape-server)= -## Guide - -In PowerShell, `shutdown` WSL then install the Ubuntu 24.04 LTS instance with -the `--root` option. - -```text -PS C:\Users\me\tutorial> wsl --shutdown - -PS C:\Users\me\tutorial> ubuntu2404.exe install --root -``` - -After successful installation log in to the new instance and add the landscape -apt repository: - - -```text -PS C:\Users\me\tutorial> ubuntu2204.exe - -root@mib:~$ add-apt-repository ppa:landscape/self-hosted-beta -y - -``` - -Update packages and then install the `landscape-server-quickstart` package. - -```text -root@mib:~$ apt update - -root@mib:~$ apt install landscape-server-quickstart -y -``` - -A dialog will appear for 'Postfix configuration'. For 'General mail -configuration type' select **No configuration**. Hit **Tab** to highlight the -**Ok** button, press **Enter** and you will be returned to the shell prompt. - -![Setting no Postfix configuration](./assets/postfix-config.png) - -If Landscape has installed successfully, the log will indicate that Landscape -systemd units are active. An example log is shown below for the first three -units: - -```text -root@mib:~$ systemctl --state=running --no-legend --no-pager | grep -m 3 landscape - landscape-api.service loaded active running LSB: Enable Landscape API - landscape-appserver.service loaded active running LSB: Enable Landscape frontend UI - landscape-async-frontend.service loaded active running LSB: Enable Landscape async frontend -``` - -Once installed Landscape will be served on `localhost` port 8080. Open your -favourite browser on Windows and navigate to `http://127.0.0.1:8080` to create -the Landscape global admin account. Enter the following credentials and click -the **Sign Up** button: - -| Field | Value | -| ----------------- | --------------- | -| Name | Admin | -| E-mail address | `admin@mib.com` | -| Passphrase | 123 | -| Verify passphrase | 123 | - -![New Landscape admin account creation](./assets/new-standalone-user.png) - -The Landscape client inside of any WSL instance will need the Landscape server -certificate to connect to the server. - -To achieve this copy the Landscape server certificate into your Windows user -profile directory: - -```text -root@mib:~$ cp /etc/ssl/certs/landscape_server.pem /mnt/c/users/me/ -``` - -Done -- your self-hosted Landscape server is now up and running! - -Now if you configure the Landscape client on any Ubuntu WSL instances to detect -this server, they will also be registered with the Landscape service included -in your Ubuntu Pro subscription. - -The server will stay running until you close the terminal. If you do close the -terminal running `ubuntu2404.exe` in a new terminal window will start the -Landscape server automatically. - -Using this server setup when following the [deployment tutorial](../tutorial/deployment) would -result in the following architecture: - -![architecture diagram showing management of WSL instances from a WSL instance on a single machine using Landscape and Ubuntu Pro for WSL](../diagrams/structurizr-Tutorial.png) - From 8f96f83bf423cf14bcaaaa8ad7149c1a33f9a7d7 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 26 Nov 2024 15:50:04 +0000 Subject: [PATCH 06/11] reorganise howtos - divides guides into subsections for setup, deployment, contributing - adds landing page text - adds howto content for developers --- docs/howto/02-install.md | 72 +++++++++++++++++++++++++++ docs/howto/03-restart.md | 33 ++++++++++++ docs/howto/06-access-the-logs.md | 26 ++++++++++ docs/howto/07-toggle-features.md | 33 ++++++++++++ docs/howto/index-contributing.md | 17 +++++++ docs/howto/index-remote-deployment.md | 15 ++++++ docs/howto/index-setup.md | 16 ++++++ docs/howto/index.md | 36 ++++++++++---- docs/howto/reset-factory.md | 27 ++++++++++ 9 files changed, 265 insertions(+), 10 deletions(-) create mode 100644 docs/howto/02-install.md create mode 100644 docs/howto/03-restart.md create mode 100644 docs/howto/06-access-the-logs.md create mode 100644 docs/howto/07-toggle-features.md create mode 100644 docs/howto/index-contributing.md create mode 100644 docs/howto/index-remote-deployment.md create mode 100644 docs/howto/index-setup.md create mode 100644 docs/howto/reset-factory.md diff --git a/docs/howto/02-install.md b/docs/howto/02-install.md new file mode 100644 index 000000000..0f7741607 --- /dev/null +++ b/docs/howto/02-install.md @@ -0,0 +1,72 @@ +# How to install UP4W + +This guide will show you how to install UP4W for local development and testing. + +
+ +**Requirements:** + +- A Windows machine with access to the internet +- Appx from the Microsoft Store: + - Windows Subsystem For Linux + - Either Ubuntu, Ubuntu 22.04, or Ubuntu (Preview) +- The Windows Subsystem for Windows optional feature enabled + +## 1. Download the Windows Agent and the WSL Pro Service + +1. Go to the [repository actions page](https://github.com/canonical/ubuntu-pro-for-wsl/actions/workflows/qa-azure.yaml?query=branch%3Amain+). +2. Click the latest successful workflow run. +3. Scroll down past any warnings or errors, until you reach the Artifacts section. +4. Download: + - Windows agent: UbuntuProForWSL+...-production + - wsl-pro-service: Wsl-pro-service_... + +Notice that, for the step above, there is also an alternative version of the MSIX bundle enabled for end-to-end testing. Most likely, that's not what you want to download. + +(dev::install-agent)= +## 2. Install the Windows Agent + +This is the Windows-side agent that manages the distros. + +1. Uninstall Ubuntu Pro for WSL if you had installed previously: + + ```powershell + Get-AppxPackage -Name CanonicalGroupLimited.UbuntuPro | Remove-AppxPackage + ``` + +2. Follow the download steps to download UbuntuProForWSL +3. Unzip the artefact +4. Find the certificate inside. Install it into `Local Machine/Trusted people`. +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. + +## 3. 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. + +1. Uninstall the WSL-Pro-Service from your distro if you had it installed previously: + + ```bash + sudo apt remove wsl-pro-service + ``` + +2. Follow the download steps to download the WSL-Pro-Service. +3. Unzip the artifact. +4. Navigate to the unzipped directory containing the .deb file. Here is a possible path: + + ```bash + cd /mnt/c/Users/WINDOWS-USER/Downloads/wsl-pro-service_* + ``` + +5. Install the deb package. + + ```bash + sudo apt install ./wsl-pro-service_*.deb + ``` + +6. Ensure it works via systemd: + + ```bash + systemctl status wsl-pro.service + ``` diff --git a/docs/howto/03-restart.md b/docs/howto/03-restart.md new file mode 100644 index 000000000..dc4391eaa --- /dev/null +++ b/docs/howto/03-restart.md @@ -0,0 +1,33 @@ +# How to restart UP4W + +Some configuration changes only apply when you restart UP4W. Here is a guide on how to restart it. There are two options. + +## Option 1: Restart your UP4W host machine + +This is the simple one. If you're not in a hurry to see the configuration updated, just wait until next time you boot your machine. + +## Option 2: Restart only UP4W + +1. Stop the agent: + + ```powershell + Get-Process -Name Ubuntu-Pro-Agent | Stop-Process + ``` + +2. Stop the distro, or distros you installed WSL-Pro-Service in: + + ```powershell + wsl --terminate DISTRO_NAME_1 + wsl --terminate DISTRO_NAME_2 + # etc. + + # Alternatively, stop all distros: + wsl --shutdown + ``` + +7. Start the agent again: + 1. Open the start Menu and search for "Ubuntu Pro for WSL". + 2. The GUI should start. + 3. Wait a minute. + 4. Click on "Click to restart it". +8. Start the distro, or distros you installed WSL-Pro-Service in. diff --git a/docs/howto/06-access-the-logs.md b/docs/howto/06-access-the-logs.md new file mode 100644 index 000000000..50400dc8c --- /dev/null +++ b/docs/howto/06-access-the-logs.md @@ -0,0 +1,26 @@ +# How to access UP4W logs + +At some point you may want to read the UP4W logs, 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. + +## Access the logs for the 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. + +## Access the logs for the Windows Agent + +To access the logs for the Windows Agent: + +1. Go to your home directory + - Open the file explorer + - Write `%USERPROFILE%` at the address +2. In the home directory, find the `.ubuntupro` directory and double-click on it. +2. In the `.ubuntupto` folder, find file `log` and open it with any text editor. + - This file contains the logs sorted with the oldest entries at the top and the newest at the bottom. diff --git a/docs/howto/07-toggle-features.md b/docs/howto/07-toggle-features.md new file mode 100644 index 000000000..de9e4c649 --- /dev/null +++ b/docs/howto/07-toggle-features.md @@ -0,0 +1,33 @@ +# How to enable opt-in features + +Some features in UP4W are opt-in or can be toggled on and off via the Windows Registry. +While the code is arranged such that CI always tests with those features enabled, +when running UP4W on your machine, you may need to toggle them on and off +explicitly via the Windows registry. This guide shows you how to do that. + +## Enable subscribing via the Microsoft Store + +1. Open the Windows registry editor: press `Win + R`, type `regedit` and press `Enter`. +1. Navigate to the following key: `HKEY_CURRENT_USER\Software\Canonical\UbuntuPro\`. +1. Create a new DWORD value named `AllowStorePurchase` and set it to `1`. + +The next time you open the GUI you'll find the button to subscribe to Ubuntu +Pro via the Microsoft Store. + +```{warning} +Beware that can incur in real charges if you proceed with the purchase. +``` + +## Disable Landscape configuration in the GUI + +Landscape configuration page and related buttons are enabled by default, but can be disabled via registry. + +1. Open the Windows registry editor: press `Win + R`, type `regedit` and press `Enter`. +1. Navigate to the following key: `HKEY_CURRENT_USER\Software\Canonical\UbuntuPro\`. +1. Create a new DWORD value named `LandscapeConfigVisibility` and set it to `0`. + +The next time you open the GUI, you'll find that the Landscape configuration +page can be shown via the set up wizard or by clicking on the 'Configure +Landscape' button. +If that value is not present or set to anything other than `0`, Landscape configuration page +and related buttons will be visible. diff --git a/docs/howto/index-contributing.md b/docs/howto/index-contributing.md new file mode 100644 index 000000000..73c4ccef5 --- /dev/null +++ b/docs/howto/index-contributing.md @@ -0,0 +1,17 @@ +(index-contributing)= + +# Contributing to UP4W + +These how-to guides help you complete tasks when developing for UP4W. + +```{toctree} +:titlesonly: +:maxdepth: 1 + +Install UP4W <02-install> +Restart UP4W <03-restart> +Access UP4W logs <06-access-the-logs> +Enable opt-in features <07-toggle-features> +Reset UP4W +``` + diff --git a/docs/howto/index-remote-deployment.md b/docs/howto/index-remote-deployment.md new file mode 100644 index 000000000..f6a3e531d --- /dev/null +++ b/docs/howto/index-remote-deployment.md @@ -0,0 +1,15 @@ +(index-remote-deployment)= + +# Remote deployment + +These how-to guides help you deploy and manage WSL instances with UP4W. + +```{toctree} +:titlesonly: +:maxdepth: 1 + +Configure the Landscape client with UP4W +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/index-setup.md b/docs/howto/index-setup.md new file mode 100644 index 000000000..827c93f20 --- /dev/null +++ b/docs/howto/index-setup.md @@ -0,0 +1,16 @@ +(index-setup)= + +# UP4W setup + +These how-to guides show you how to set up UP4W. + +```{toctree} +:titlesonly: +:maxdepth: 1 + +Install UP4W and add a Pro token +Verify Pro subscription and attachment +Back up and restore Ubuntu WSL instances +Uninstalling UP4W, Ubuntu WSL apps and WSL +``` + diff --git a/docs/howto/index.md b/docs/howto/index.md index 3c536981b..cb602df9e 100644 --- a/docs/howto/index.md +++ b/docs/howto/index.md @@ -2,18 +2,34 @@ # How-to guides -These how-to guides cover key operations and processes in UP4W. +The guides in this section will help you quickly +complete specific tasks with UP4W. + +Install and set up of UP4W is with the aid of these guides: + +```{toctree} +:titlesonly: + +index-setup + +``` + +When remotely deploying and managing Ubuntu WSL instances, the following guides +are helpful: ```{toctree} :titlesonly: -Install UP4W and add a Pro token -Verify Pro subscription and attachment -Back up and restore Ubuntu WSL instances -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 +index-remote-deployment + +``` + +If you are interested in contributing to UP4W as a developer, consult the +guides below: + +```{toctree} +:titlesonly: + +index-contributing + ``` diff --git a/docs/howto/reset-factory.md b/docs/howto/reset-factory.md new file mode 100644 index 000000000..38f6758d9 --- /dev/null +++ b/docs/howto/reset-factory.md @@ -0,0 +1,27 @@ +# How to reset UP4W back to factory settings + +You can reset Ubuntu Pro for WSL to factory settings following these steps: + +1. Shut down WSL + ```powershell + wsl --shutdown + ``` +2. Uninstall the package and shut down WSL: + + ```powershell + Get-AppxPackage -Name "CanonicalGroupLimited.UbuntuPro" | Remove-AppxPackage` + ``` +3. Remove the public directory: + ```powershell + Remove-Item -Recurse -Force "${env:UserProfile}\.ubuntupro\" + ``` +4. Remove the registry key: + 1. Press Win+R + 2. Type `regedit.exe` and click OK + 3. Write `HKEY_CURRENT_USER\Software\Canonical\UbuntuPro` at the address bar + - If this fails, you are done (the key does not exist). + 4. Find the `UbuntuPro` key on the left + 5. Right-click on it + 6. Click delete +5. Install the Windows Agent package again (see the section on [how to install](dev::install-agent)). You do not need to re-install the WSL-Pro-Service. +6. You're done. Next time you start the GUI it'll be like a fresh install. From 8a8d0b42c5672b3edfaab96a7bea955467c352b9 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 26 Nov 2024 15:51:42 +0000 Subject: [PATCH 07/11] reorganise ref content - divides content into components, configuration and debugging/testing - adds landing page text and structure - removes generic content on Ubuntu Pro, Landscape and WSL - adds reference content for developers (CLI and QA) --- ...07-windows-agent-command-line-reference.md | 263 ++++++++++++++++++ ...-wsl-pro-service-command-line-reference.md | 241 ++++++++++++++++ docs/reference/09-qa-process-reference.md | 77 +++++ docs/reference/index.md | 39 ++- docs/reference/index_system_configuration.md | 15 + docs/reference/index_up4w_components.md | 41 +++ docs/reference/index_up4w_development.md | 14 + docs/reference/landscape_client.md | 5 +- .../{landscape.md => landscape_config.md} | 20 +- docs/reference/ubuntu_pro.md | 22 -- docs/reference/ubuntu_pro_client.md | 24 +- docs/reference/ubuntu_wsl.md | 5 - docs/reference/up4w-gui.md | 4 +- docs/reference/up4w-windows_agent.md | 2 +- docs/reference/up4w-wsl_pro_service.md | 2 +- docs/reference/up4w.md | 14 - docs/reference/windows_registry.md | 2 +- docs/reference/wsl.md | 10 +- 18 files changed, 713 insertions(+), 87 deletions(-) create mode 100644 docs/reference/07-windows-agent-command-line-reference.md create mode 100644 docs/reference/08-wsl-pro-service-command-line-reference.md create mode 100644 docs/reference/09-qa-process-reference.md create mode 100644 docs/reference/index_system_configuration.md create mode 100644 docs/reference/index_up4w_components.md create mode 100644 docs/reference/index_up4w_development.md rename docs/reference/{landscape.md => landscape_config.md} (67%) delete mode 100644 docs/reference/ubuntu_pro.md delete mode 100644 docs/reference/ubuntu_wsl.md delete mode 100644 docs/reference/up4w.md diff --git a/docs/reference/07-windows-agent-command-line-reference.md b/docs/reference/07-windows-agent-command-line-reference.md new file mode 100644 index 000000000..fdc638282 --- /dev/null +++ b/docs/reference/07-windows-agent-command-line-reference.md @@ -0,0 +1,263 @@ +# Windows Agent CLI + +> See first: [UP4W - Windows Agent](ref::up4w-windows-agent) + + +## Usage + +### User commands + +#### ubuntu-pro-agent + +Ubuntu Pro for WSL agent + +##### Synopsis + +Ubuntu Pro for WSL agent for managing your pro-enabled distro. + +``` +ubuntu-pro-agent COMMAND [flags] +``` + +##### Options + +``` + -c, --config string configuration file path + -h, --help help for ubuntu-pro-agent + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### ubuntu-pro-agent clean + +Removes all the agent's data and exits + +``` +ubuntu-pro-agent clean [flags] +``` + +##### Options + +``` + -h, --help help for clean +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### ubuntu-pro-agent completion + +Generate the autocompletion script for the specified shell + +##### Synopsis + +Generate the autocompletion script for ubuntu-pro-agent for the specified shell. +See each sub-command's help for details on how to use the generated script. + + +##### Options + +``` + -h, --help help for completion +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### ubuntu-pro-agent completion bash + +Generate the autocompletion script for bash + +##### Synopsis + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(ubuntu-pro-agent completion bash) + +To load completions for every new session, execute once: + +###### Linux: + + ubuntu-pro-agent completion bash > /etc/bash_completion.d/ubuntu-pro-agent + +###### macOS: + + ubuntu-pro-agent completion bash > $(brew --prefix)/etc/bash_completion.d/ubuntu-pro-agent + +You will need to start a new shell for this setup to take effect. + + +``` +ubuntu-pro-agent completion bash +``` + +##### Options + +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### ubuntu-pro-agent completion fish + +Generate the autocompletion script for fish + +##### Synopsis + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + ubuntu-pro-agent completion fish | source + +To load completions for every new session, execute once: + + ubuntu-pro-agent completion fish > ~/.config/fish/completions/ubuntu-pro-agent.fish + +You will need to start a new shell for this setup to take effect. + + +``` +ubuntu-pro-agent completion fish [flags] +``` + +##### Options + +``` + -h, --help help for fish + --no-descriptions disable completion descriptions +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### ubuntu-pro-agent completion powershell + +Generate the autocompletion script for powershell + +##### Synopsis + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + ubuntu-pro-agent completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + + +``` +ubuntu-pro-agent completion powershell [flags] +``` + +##### Options + +``` + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### ubuntu-pro-agent completion zsh + +Generate the autocompletion script for zsh + +##### Synopsis + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions in your current shell session: + + source <(ubuntu-pro-agent completion zsh) + +To load completions for every new session, execute once: + +###### Linux: + + ubuntu-pro-agent completion zsh > "${fpath[1]}/_ubuntu-pro-agent" + +###### macOS: + + ubuntu-pro-agent completion zsh > $(brew --prefix)/share/zsh/site-functions/_ubuntu-pro-agent + +You will need to start a new shell for this setup to take effect. + + +``` +ubuntu-pro-agent completion zsh [flags] +``` + +##### Options + +``` + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### ubuntu-pro-agent version + +Returns version of agent and exits + +``` +ubuntu-pro-agent version [flags] +``` + +##### Options + +``` + -h, --help help for version +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +### Hidden commands + +Those commands are hidden from help and should primarily be used by the system or for debugging. + diff --git a/docs/reference/08-wsl-pro-service-command-line-reference.md b/docs/reference/08-wsl-pro-service-command-line-reference.md new file mode 100644 index 000000000..5c3b93727 --- /dev/null +++ b/docs/reference/08-wsl-pro-service-command-line-reference.md @@ -0,0 +1,241 @@ +# WSL Pro Service CLI + +> See first: [UP4W - WSL Pro Service](ref::up4w-wsl-pro-service) + +## Usage + +### User commands + +#### wsl-pro-service + +WSL Pro Service + +##### Synopsis + +WSL Pro Service connects Ubuntu Pro for WSL agent to your distro. + +``` +wsl-pro-service COMMAND [flags] +``` + +##### Options + +``` + -c, --config string configuration file path + -h, --help help for wsl-pro-service + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### wsl-pro-service completion + +Generate the autocompletion script for the specified shell + +##### Synopsis + +Generate the autocompletion script for wsl-pro-service for the specified shell. +See each sub-command's help for details on how to use the generated script. + + +##### Options + +``` + -h, --help help for completion +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### wsl-pro-service completion bash + +Generate the autocompletion script for bash + +##### Synopsis + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(wsl-pro-service completion bash) + +To load completions for every new session, execute once: + +###### Linux: + + wsl-pro-service completion bash > /etc/bash_completion.d/wsl-pro-service + +###### macOS: + + wsl-pro-service completion bash > $(brew --prefix)/etc/bash_completion.d/wsl-pro-service + +You will need to start a new shell for this setup to take effect. + + +``` +wsl-pro-service completion bash +``` + +##### Options + +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### wsl-pro-service completion fish + +Generate the autocompletion script for fish + +##### Synopsis + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + wsl-pro-service completion fish | source + +To load completions for every new session, execute once: + + wsl-pro-service completion fish > ~/.config/fish/completions/wsl-pro-service.fish + +You will need to start a new shell for this setup to take effect. + + +``` +wsl-pro-service completion fish [flags] +``` + +##### Options + +``` + -h, --help help for fish + --no-descriptions disable completion descriptions +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### wsl-pro-service completion powershell + +Generate the autocompletion script for powershell + +##### Synopsis + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + wsl-pro-service completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + + +``` +wsl-pro-service completion powershell [flags] +``` + +##### Options + +``` + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### wsl-pro-service completion zsh + +Generate the autocompletion script for zsh + +##### Synopsis + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions in your current shell session: + + source <(wsl-pro-service completion zsh) + +To load completions for every new session, execute once: + +###### Linux: + + wsl-pro-service completion zsh > "${fpath[1]}/_wsl-pro-service" + +###### macOS: + + wsl-pro-service completion zsh > $(brew --prefix)/share/zsh/site-functions/_wsl-pro-service + +You will need to start a new shell for this setup to take effect. + + +``` +wsl-pro-service completion zsh [flags] +``` + +##### Options + +``` + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +#### wsl-pro-service version + +Returns version of agent and exits + +``` +wsl-pro-service version [flags] +``` + +##### Options + +``` + -h, --help help for version +``` + +##### Options inherited from parent commands + +``` + -c, --config string configuration file path + -v, --verbosity count issue INFO (-v), DEBUG (-vv) or DEBUG with caller (-vvv) output +``` + +### Hidden commands + +Those commands are hidden from help and should primarily be used by the system or for debugging. + diff --git a/docs/reference/09-qa-process-reference.md b/docs/reference/09-qa-process-reference.md new file mode 100644 index 000000000..3f236434c --- /dev/null +++ b/docs/reference/09-qa-process-reference.md @@ -0,0 +1,77 @@ +# QA Process + +## Generalities + +`wsl-pro-service` is seeded only on WSL images. + +``` +Build-dep: golang-go (\>= 2:1.21\~) +``` + +At any point in time, only the latest two versions of the Go toolchain receive security patches. Hence, we need to keep backporting new releases to fix vulnerabilities. They follow an approximate 6-month release cycle, so Go 1.21 should fall out of support by August 2024. + +## Process + +WSL Pro Service follows a robust continuous integration and testing process. It is covered by [a comprehensive automated test suite](https://github.com/canonical/ubuntu-pro-for-wsl/actions/workflows/qa.yaml). + +The team applies the following quality criteria: + +- All changes are thoroughly reviewed and approved by core team members before integration. +- Each change is thoroughly tested at the unit, integration and system levels. All the tests pass in all supported architectures. +- Releases are reviewed as part of the [SRU exception](https://wiki.ubuntu.com/UbuntuProForWSLUpdates). + +The test plan is **completely automated** and runs **every time a change is merged**, as well as **during packaging**. This covers integration and end-to-end tests. Integration tests run on each LTS affected by the SRU to ensure compatibility. + +Testing also covers the upgrade from the current version to the proposed version. + +Tests are not executed on different versions of Windows due to testing environment limitations. + +## Packaging QA + +To prepare the release to LTS, the following procedure is being completed to ensure quality: + +- All autopkgtests pass. Unit tests are executed as autopkgtests. Running higher-level tests would require a Windows VM. It is not available in autopkgtest at the moment. Even if wsl-pro-service tests could run in a VM, they wouldn't test anything real. +- The package does not break when upgrading. +- The binary is identical to the CI build, with only Debian packaging changes. +- The copyrights and changelog are up to date. +- An upgrade test from the previous package version has been performed using apt install/upgrade. + +## Code sanity + +Code sanity checks are performed automatically on each build. They verify: + +- Code linting. +- Go module files are up to date. +- Generated files are up to date. +- Any binary in the project builds. +- The Debian package builds. +- Vulnerabilities. It is a run of `govulncheck`. + +All the layers are tested from APIs to mocks to the service itself + +### Example reports + +- Code sanity and unit testing: [QA workflow](https://github.com/canonical/ubuntu-pro-for-wsl/actions/workflows/qa.yaml?query=branch%3Amain) +- Integration tests: [end-to-to-end tests workflow](https://github.com/canonical/ubuntu-pro-for-wsl/actions/workflows/qa-azure.yaml?query=branch%3Amain) + + +![image](https://github.com/canonical/ubuntu-pro-for-wsl/assets/1928546/649084df-1889-471a-a211-df3ae890a8fd) + +## Code coverage + +There is no Codecov report due to the limitations of private projects. +However, code coverage is calculated and displayed at testing time. +Coverage is manually reviewed by the engineers. + +## Bug reporting + +The main bug tracker remains on GitHub. [GitHub Templates](https://github.com/canonical/ubuntu-pro-for-wsl/issues/new/choose) +are available to help the user with the bug-reporting process and provide the right information. + +Wsl-pro supports ubuntu-bug reporting to Launchpad with an apport hook but we are not collecting any data at the moment. + +## References + +- [Project Documentation](https://canonical-ubuntu-pro-for-wsl.readthedocs-hosted.com/en/latest/) +- [Ubuntu Pro for WSL SRU exception](https://wiki.ubuntu.com/UbuntuProForWSLUpdates) +- [Ubuntu Pro tools SRU exception](https://wiki.ubuntu.com/UbuntuAdvantageToolsUpdates) diff --git a/docs/reference/index.md b/docs/reference/index.md index 39890a113..9c0e5acb6 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,21 +1,32 @@ +(reference)= + # Reference -Our reference section contains more detailed information about the several -pieces that make up the Ubuntu Pro for WSL tool and the value it provides. +This section contains concise references relating to how how UP4W is designed, +configured and developed: + +Descriptions of key UP4W components can be found here: + +```{toctree} +:titlesonly: + +index_up4w_components +``` + +Details on firewall configuration, Landscape setup and using the Windows +registry can be found here: + +```{toctree} +:titlesonly: + +index_system_configuration +``` + +Information for contributors that is helpful for debugging code and ensuring +code quality is outlined below: ```{toctree} :titlesonly: -firewall_requirements -landscape -landscape_client -ubuntu_pro -ubuntu_pro_client -ubuntu_wsl -UP4W -UP4W - GUI -up4w-windows_agent -up4w-wsl_pro_service -windows_registry -WSL +index_up4w_development ``` diff --git a/docs/reference/index_system_configuration.md b/docs/reference/index_system_configuration.md new file mode 100644 index 000000000..c911a3892 --- /dev/null +++ b/docs/reference/index_system_configuration.md @@ -0,0 +1,15 @@ +(index-system-configuration)= + +# System configuration + +When configuring firewall settings, Landscape clients or the Windows registry, +the following references may be useful: + +```{toctree} +:titlesonly: +:maxdepth: 1 + +firewall_requirements +landscape_config +windows_registry +``` diff --git a/docs/reference/index_up4w_components.md b/docs/reference/index_up4w_components.md new file mode 100644 index 000000000..a980d56f2 --- /dev/null +++ b/docs/reference/index_up4w_components.md @@ -0,0 +1,41 @@ +(index-system-components)= + +# UP4W components + +Some Ubuntu Pro for WSL (UP4W) components run on the Windows host: + +- The [UP4W Windows Agent](ref::up4w-windows-agent) that provides automation +services. +- The [UP4W GUI](ref::up4w-gui) for end users to manage their Ubuntu Pro +subscription and Landscape configuration. + +UP4W also requires a component running inside each of the WSL distros: + +- The [WSL Pro Service](ref::up4w-wsl-pro-service) communicates with the +Windows Agent to provide automation services. + +Find additional detail on the individual components of UP4W below: + +```{toctree} +:titlesonly: +:maxdepth: 1 + +up4w-windows_agent +up4w-gui +up4w-wsl_pro_service +landscape_client +ubuntu_pro_client +``` + +```{admonition} Supporting technologies +Windows Subsystem for Linux (**WSL**) makes it possible to run Linux +distributions on Windows. UP4W runs on Windows hosts to manage **Ubuntu WSL** +instances, automatically attaching them to an **Ubuntu Pro** subscription and +enrolling them into **Landscape**. For more information on these technologies, +you can refer to their official documentation: + +* [Official Ubuntu WSL documentation](https://documentation.ubuntu.com/wsl/en/latest/) +* [Official Microsoft WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/) +* [Official Landscape documentation](https://ubuntu.com/landscape/docs) + +``` diff --git a/docs/reference/index_up4w_development.md b/docs/reference/index_up4w_development.md new file mode 100644 index 000000000..f95fdcf5c --- /dev/null +++ b/docs/reference/index_up4w_development.md @@ -0,0 +1,14 @@ +(debugging-and-testing)= + +# Debugging and testing + +The reference material in this section is helpful for contributors when debugging the application +and contributing code. + +```{toctree} +:titlesonly: + +Windows Agent CLI <07-windows-agent-command-line-reference> +WSL Pro Service CLI <08-wsl-pro-service-command-line-reference> +QA process <09-qa-process-reference> +``` diff --git a/docs/reference/landscape_client.md b/docs/reference/landscape_client.md index a9d6df44b..36e7440dc 100644 --- a/docs/reference/landscape_client.md +++ b/docs/reference/landscape_client.md @@ -1,7 +1,7 @@ (ref::landscape-client)= -# Landscape (client) +# Landscape client -The Landscape client is a `systemd` unit running on [Landscape](ref::landscape)-managed Ubuntu machines. It sends information about the system to the Landscape server. The server, in turn, sends instructions that the client executes. +The Landscape client is a `systemd` unit running on [Landscape](https://ubuntu.com/landscape/docs)-managed Ubuntu machines. It sends information about the system to the Landscape server. The server, in turn, sends instructions that the client executes. In WSL, there is one Landscape client inside every Ubuntu WSL distro. The Landscape client comes pre-installed in your distro as part of the package `landscape-client`, but it must be configured before it can start running. @@ -10,6 +10,7 @@ In WSL, there is one Landscape client inside every Ubuntu WSL distro. The Landsc UP4W will configure all Ubuntu WSL distros for you, so you don't need to configure each WSL instance separately; you specify the configuration once and UP4W will distribute it to every distro. You can see the status of the Landscape client in any particular Ubuntu WSL instance by starting a shell in that instance and running: + ```bash systemctl status landscape-client.service ``` diff --git a/docs/reference/landscape.md b/docs/reference/landscape_config.md similarity index 67% rename from docs/reference/landscape.md rename to docs/reference/landscape_config.md index ef8f3bb4e..c0c0c2b8c 100644 --- a/docs/reference/landscape.md +++ b/docs/reference/landscape_config.md @@ -1,19 +1,5 @@ -(ref::landscape)= -# Landscape - -Landscape is a systems management tool designed to help you manage and monitor your Ubuntu systems from a unified platform. -> See more: [Landscape | Documentation ](https://ubuntu.com/landscape/docs) - -In UP4W, Landscape consists of a remote server and two clients: - -1. the usual Ubuntu-side client, in this case a [Landscape client](ref::landscape-client) that comes automatically with any Ubuntu WSL instance, and - -2. a Windows-side client, a Landscape client that is built into the [UP4W Windows Agent](ref::up4w-windows-agent). - -The latter offers advantages unique to Ubuntu WSL – the ability to create new instances through Landscape and the ability to configure all your instances at scale (when you configure the Windows-side client, the UP4W agent forwards the configuration to the client on each instance). - (ref::landscape-config)= -## Landscape configuration schema +# Landscape configuration schema Both Landscape clients are configured via a single, plain text configuration file (e.g., `landscape.conf` or `landscape.ini`). This file is provided to the Windows host. @@ -35,12 +21,12 @@ log_level = debug ssl_public_key = C:\Users\user\Downloads\landscape_server.pem ``` -### Host +## Host This section contains settings unique to the Windows-side client. Currently these consist of a single key: - `url`: The URL of your Landscape account followed by a colon (`:`) and the port number. Port 6554 is the default for Landscape Quickstart installations. -### Client +## Client This section contains settings used by both clients. Most keys in this section behave the same way they would on a traditional Landscape setup. Only the following keys behave differently: - `ssl_public_key`: This key must be a Windows path. The WSL instances will have this path translated automatically. diff --git a/docs/reference/ubuntu_pro.md b/docs/reference/ubuntu_pro.md deleted file mode 100644 index 2c0128047..000000000 --- a/docs/reference/ubuntu_pro.md +++ /dev/null @@ -1,22 +0,0 @@ -(ref::ubuntu-pro)= -# Ubuntu Pro - -Ubuntu Pro is a subscription service offered by Canonical on top of the Long Term Support (LTS) releases of Ubuntu. It provides access to the following offerings: -- Landscape -- Center for Internet Security (CIS) compliance -- Expanded Security Maintenance (ESM) -- Canonical Support line - -> See more: [Ubuntu | Ubuntu Pro](https://ubuntu.com/pro) - -Ubuntu Pro services are managed by the [Ubuntu Pro client](ref::ubuntu-pro-client). - -(ref::ubuntu-pro-token)= -## Ubuntu Pro token - -An Ubuntu pro token is a secret string of numbers and letters that acts as proof of purchase for your Ubuntu Pro subscription. Services provided by the Ubuntu Pro subscription will require a token to run. -> See more: [Pro-attach](ref::pro-attach) - -You can find out what your Ubuntu Pro token is by visiting your Ubuntu Pro dashboard and logging in. -> See more: [Ubuntu | Ubuntu Pro dashboard](https://ubuntu.com/pro/dashboard) - diff --git a/docs/reference/ubuntu_pro_client.md b/docs/reference/ubuntu_pro_client.md index 161e504bd..4da7ae04f 100644 --- a/docs/reference/ubuntu_pro_client.md +++ b/docs/reference/ubuntu_pro_client.md @@ -1,11 +1,27 @@ (ref::ubuntu-pro-client)= -# Ubuntu Pro (client) +# Ubuntu Pro client -The Ubuntu Pro client is a command-line utility (a CLI) that manages the different offerings of your Ubuntu Pro subscription. In UP4W, this executable is used within each of the managed WSL distros to enable [Ubuntu Pro](ref::ubuntu-pro) services within that distro. +The Ubuntu Pro client is a command-line utility (a CLI) that manages the +different offerings of your Ubuntu Pro subscription. In UP4W, this executable +is used within each of the managed WSL distros to enable [Ubuntu +Pro](https://documentation.ubuntu.com/pro/) services within that distro. -This executable is provided as part of the `ubuntu-advantage-tools` package, which comes pre-installed in your Ubuntu WSL distros. +This executable is provided as part of the `ubuntu-advantage-tools` package, +which comes pre-installed in your Ubuntu WSL distros. > See more: [Ubuntu manuals | Ubuntu advantage tools](https://manpages.ubuntu.com/manpages/noble/en/man1/ubuntu-advantage.1.html) (ref::pro-attach)= ## Pro-attach -_Pro-attaching_ a machine (e.g. a desktop computer, a WSL distro, a server, a virtual machine, etc.) means to provide your [Ubuntu Pro token](ref::ubuntu-pro-token) to the Ubuntu Pro client, so that it can enable Ubuntu Pro services. +_Pro-attaching_ a machine (e.g. a desktop computer, a WSL distro, a server, a +virtual machine, etc.) means to provide your Ubuntu Pro token to the Ubuntu Pro +client, so that it can enable Ubuntu Pro services. + +(ref::ubuntu-pro-token)= +## Pro token +An Ubuntu pro token is a secret string of numbers and letters that acts as +proof of purchase for your Ubuntu Pro subscription. Services provided by the +Ubuntu Pro subscription will require a token to run. + +You can find out what your Ubuntu Pro token is by visiting your Ubuntu Pro +dashboard and logging in. +> See more: [Ubuntu | Ubuntu Pro dashboard](https://ubuntu.com/pro/dashboard) diff --git a/docs/reference/ubuntu_wsl.md b/docs/reference/ubuntu_wsl.md deleted file mode 100644 index 3a796b348..000000000 --- a/docs/reference/ubuntu_wsl.md +++ /dev/null @@ -1,5 +0,0 @@ -# Ubuntu WSL - -Ubuntu WSL refers to the set of Ubuntu releases that target [WSL](ref::wsl). Each of these releases is distributed as a separate Microsoft Store application. Once installed, each of these releases will run as a separate WSL instance. - -> See more: [Ubuntu WSL | Documentation](https://canonical-ubuntu-wsl.readthedocs-hosted.com/en/latest/) diff --git a/docs/reference/up4w-gui.md b/docs/reference/up4w-gui.md index 35dfae1fa..3e6c41878 100644 --- a/docs/reference/up4w-gui.md +++ b/docs/reference/up4w-gui.md @@ -1,5 +1,5 @@ (ref::up4w-gui)= -# UP4W - Graphical User Interface (GUI) +# Application GUI UP4W has a small GUI to help users with: - Providing or acquiring an [Ubuntu Pro token](ref::ubuntu-pro-token). @@ -9,4 +9,4 @@ UP4W has a small GUI to help users with: ## Interaction between the GUI and the agent -When the GUI starts, it attempts to establish a connection to the [UP4W Windows Agent](ref::up4w-windows-agent). If this fails, the agent is restarted. For troubleshooting purposes, you can restart the Agent by stopping the Windows process `ubuntu-pro-agent-launcher.exe` and starting the GUI. \ No newline at end of file +When the GUI starts, it attempts to establish a connection to the [UP4W Windows Agent](ref::up4w-windows-agent). If this fails, the agent is restarted. For troubleshooting purposes, you can restart the Agent by stopping the Windows process `ubuntu-pro-agent-launcher.exe` and starting the GUI. diff --git a/docs/reference/up4w-windows_agent.md b/docs/reference/up4w-windows_agent.md index 0d435bcdd..1af72b872 100644 --- a/docs/reference/up4w-windows_agent.md +++ b/docs/reference/up4w-windows_agent.md @@ -1,5 +1,5 @@ (ref::up4w-windows-agent)= -# UP4W - Windows Agent +# Windows Agent UP4W's Windows Agent is a Windows application running in the background. It starts automatically when the user logs in to Windows. If it stops for some reason, it can also be started by launching the UP4W GUI. diff --git a/docs/reference/up4w-wsl_pro_service.md b/docs/reference/up4w-wsl_pro_service.md index 20ef9d7ad..2ae05b5d0 100644 --- a/docs/reference/up4w-wsl_pro_service.md +++ b/docs/reference/up4w-wsl_pro_service.md @@ -1,5 +1,5 @@ (ref::up4w-wsl-pro-service)= -# UP4W - WSL Pro service +# WSL Pro service A `systemd` unit running inside every Ubuntu WSL instance. The [Windows Agent](ref::up4w-windows-agent) running on the Windows host sends commands that the WSL Pro Service executes, such as [pro-attaching](ref::pro-attach) or configuring the [Landscape client](ref::landscape-client). diff --git a/docs/reference/up4w.md b/docs/reference/up4w.md deleted file mode 100644 index a7fb62297..000000000 --- a/docs/reference/up4w.md +++ /dev/null @@ -1,14 +0,0 @@ -# Ubuntu Pro for WSL (UP4W) - -Ubuntu Pro for WSL (UP4W) is an automation tool running on Windows hosts to manage Ubuntu WSL instances, providing them with compliance by attaching them to your Ubuntu Pro subscription and enrolling them into Landscape. - -Some Ubuntu Pro for WSL components run on the Windows host: -- the [UP4W Windows Agent](ref::up4w-windows-agent) providing automation services. -- the [UP4W GUI](ref::up4w-gui) for end users to manage their Ubuntu Pro subscription and Landscape configuration. - -Additionally, Ubuntu Pro for WSL requires a component running inside each of the WSL distros: -- the [WSL Pro Service](ref::up4w-wsl-pro-service) communicates with the Windows Agent to provide automation services. - -A top-level summary of the architecture is shown below: - -![System Landscape](../diagrams/structurizr-SystemLandscape.png) diff --git a/docs/reference/windows_registry.md b/docs/reference/windows_registry.md index 30ddd0cb6..17309a29d 100644 --- a/docs/reference/windows_registry.md +++ b/docs/reference/windows_registry.md @@ -5,7 +5,7 @@ The Windows registry is a database provided by Windows where programs can read a > See more: [Microsoft Learn | Windows registry information for advanced users](https://learn.microsoft.com/en-us/troubleshoot/windows-server/performance/windows-registry-advanced-users) -In UP4W, you can use the Windows registry to supply the configuration for [Ubuntu Pro](ref::ubuntu-pro) and [Landscape](ref::landscape) to the [Windows Agent](ref::up4w-windows-agent). +In UP4W, you can use the Windows registry to supply the configuration for Ubuntu Pro and Landscape to the [Windows Agent](ref::up4w-windows-agent). > See more: [install UP4W and add a Pro token](howto::config-up4w) diff --git a/docs/reference/wsl.md b/docs/reference/wsl.md index ed790e567..edda2ee93 100644 --- a/docs/reference/wsl.md +++ b/docs/reference/wsl.md @@ -1,7 +1,9 @@ (ref::wsl)= -# Windows Subsystem for Linux (WSL) +# WSL +Windows Subsystem for Linux (WSL) is a Microsoft product, distributed as part +of Windows 10 and Windows 11. It allows the user to run a Linux environment on +the Windows machine, without the need for a traditional virtual machine or a +dual boot setup. -Windows Subsystem for Linux (WSL) is a Microsoft product, distributed as part of Windows 10 and Windows 11. It allows the user to run a Linux environment on the Windows machine, without the need for a traditional virtual machine or a dual boot setup. - -> See more: [WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/about) \ No newline at end of file +> See more: [WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/about) From 076fa5bfd277508183604f6f511c35877b092236 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 26 Nov 2024 15:53:23 +0000 Subject: [PATCH 08/11] tutorials reorganisation - adds landing page text and structure - minor fixes to wording and links --- docs/tutorial/deployment.md | 9 ++++----- docs/tutorial/getting-started.md | 3 +-- docs/tutorial/index.md | 14 +++++++++++++- 3 files changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/tutorial/deployment.md b/docs/tutorial/deployment.md index 58e7dcc1d..a752f97a9 100644 --- a/docs/tutorial/deployment.md +++ b/docs/tutorial/deployment.md @@ -1,4 +1,4 @@ -# Deployment with UP4W and Landscape +# Deploy WSL instances with UP4W and Landscape With Ubuntu Pro for WSL (UP4W) an [Ubuntu Pro](https://ubuntu.com/pro) subscription empowers you to manage Ubuntu WSL instances at scale. @@ -138,7 +138,6 @@ You know how to leverage UP4W and Landscape to efficiently manage your Ubuntu WS ## Next steps -In the rest of the documentation you can find [how-to guides](../howto/index) -for completing specific tasks, [reference](../reference/index) material -describing key information relating to UP4W and dedicated [documentation for -developers](../dev/index). +Our documentation includes several [how-to guides](../howto/index) +for completing specific tasks and [reference](../reference/index) material +describing key information relating to UP4W. diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md index e1f4265bf..8cd3098d2 100644 --- a/docs/tutorial/getting-started.md +++ b/docs/tutorial/getting-started.md @@ -208,5 +208,4 @@ with your Landscape server: Our documentation includes several other [how-to guides](../howto/index) for completing specific tasks, [reference](../reference/index) material -describing key information relating to UP4W and dedicated [documentation for -developers](../dev/index). +describing key information relating to UP4W. diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index ccd348191..c6c051daf 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -2,11 +2,23 @@ # Tutorials -These tutorials will help you learn to get the best out of UP4W's features. +These tutorials guide you through setting up UP4W and using it to deploy Ubuntu +WSL instances. + +First, learn how to install UP4W then automatically Pro-attach your Ubuntu WSL +instances: ```{toctree} :titlesonly: Get started with UP4W +``` + +Next, learn how UP4W's Landscape integration can be used to deploy Ubuntu WSL +instances at scale: + +```{toctree} +:titlesonly: + Deploy WSL instances with UP4W and Landscape ``` From e205bf0dbbe1b2e4944f91eaf639596fbb6fab12 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 26 Nov 2024 16:44:34 +0000 Subject: [PATCH 09/11] remove short WSL ref --- docs/reference/wsl.md | 9 --------- 1 file changed, 9 deletions(-) delete mode 100644 docs/reference/wsl.md diff --git a/docs/reference/wsl.md b/docs/reference/wsl.md deleted file mode 100644 index edda2ee93..000000000 --- a/docs/reference/wsl.md +++ /dev/null @@ -1,9 +0,0 @@ -(ref::wsl)= -# WSL - -Windows Subsystem for Linux (WSL) is a Microsoft product, distributed as part -of Windows 10 and Windows 11. It allows the user to run a Linux environment on -the Windows machine, without the need for a traditional virtual machine or a -dual boot setup. - -> See more: [WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/about) From 933ee567e72b1d06135a06fc19e94e697f0515fa Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 26 Nov 2024 17:15:46 +0000 Subject: [PATCH 10/11] remove duplicate word --- docs/reference/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/index.md b/docs/reference/index.md index 9c0e5acb6..55c85ef4c 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -2,7 +2,7 @@ # Reference -This section contains concise references relating to how how UP4W is designed, +This section contains concise references relating to how UP4W is designed, configured and developed: Descriptions of key UP4W components can be found here: From bccc9c4a70cf579deb85b22e0c966178364dd056 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Wed, 27 Nov 2024 11:12:02 +0000 Subject: [PATCH 11/11] fix wording --- docs/howto/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/index.md b/docs/howto/index.md index cb602df9e..3fb9a3a3b 100644 --- a/docs/howto/index.md +++ b/docs/howto/index.md @@ -5,7 +5,7 @@ The guides in this section will help you quickly complete specific tasks with UP4W. -Install and set up of UP4W is with the aid of these guides: +Install and set up of UP4W with the aid of these guides: ```{toctree} :titlesonly: