diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 361cb0c8c..a6b6fd117 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -15,6 +15,7 @@ Codecov distro distros ESM +gRPC Intune macOS MSIX diff --git a/docs/explanation/index.md b/docs/explanation/index.md new file mode 100644 index 000000000..b7bef473e --- /dev/null +++ b/docs/explanation/index.md @@ -0,0 +1,12 @@ +(explanation)= + +# Explanation + +This section contains explanations that will help you develop a deeper +understanding of how UP4W is designed. + +```{toctree} +:titlesonly: + +ref-arch-explanation +``` diff --git a/docs/explanation/ref-arch-explanation.md b/docs/explanation/ref-arch-explanation.md new file mode 100644 index 000000000..fecdbad63 --- /dev/null +++ b/docs/explanation/ref-arch-explanation.md @@ -0,0 +1,139 @@ +# UP4W architecture + +This page describes the different components of UP4W and how they integrate +together to form the software architecture. + +## Background + +### What is Ubuntu WSL? + +With the Windows Subsystem for Linux (WSL), Linux distributions can be run on +Windows with minimal overhead. Ubuntu WSL is an image that is optimised for +running Ubuntu WSL. A user can create an Ubuntu WSL instance on a Windows +machine and use that instance as a production-ready development environment. +Ubuntu WSL also benefits from tight integration with Ubuntu Pro and +Landscape, which makes it easier to secure Ubuntu WSL instances and manage them +at scale. + +### Why is managing WSL instances at scale difficult? + +An individual user can create and configure multiple, independent instances of +Ubuntu WSL on their machine. For a system administrator, who is managing +fleets of Windows machines with multiple users, the potential number of Ubuntu +WSL instances increases dramatically. While the system administrator has tools +for managing Windows machines, WSL instances can be a black box that cannot be +directly monitored or patched. This can result in WSL instances that do not +follow system administration policies. + +### How does Ubuntu Pro for WSL solve this problem? + +Ubuntu Pro for WSL (UP4W) helps automate the management of Ubuntu WSL. +For each new instance that is discovered or created, UP4W will automatically: + +* Attach them to your Ubuntu Pro subscription +* Enrol them with your Landscape server + +The integration with Ubuntu Pro keeps instances secure, while the +integration with Landscape enables remote deployment and management. + +Without UP4W, these configurations would be manual, time-consuming and +error-prone. + +## The components of UP4W + +```{admonition} WSL architecture +:class: tip +WSL is maintained by Microsoft and its architecture is outside the scope of this page. + +A good overview of WSL architecture is provided in [this blog from Microsoft](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/cmdline/wsl-architectural-overview). +``` + +### Overview + +UP4W consists of some components that run on a Windows host +and others that run within instances of Ubuntu WSL. + +A user interacts with the UP4W application. UP4W then automatically +pro-attaches and Landscape-enrols each new instance of Ubuntu WSL that is +created on the Windows host. + +In an organisation, multiple users of Windows machines can create Ubuntu WSL +instances, which are secured by Ubuntu Pro and that can be managed by Landscape. + +```{figure} ../diagrams/structurizr-SystemLandscape.png +:name: user-interact-arch +:alt: architecture diagram showing user interaction with Ubuntu Pro for WSL +:align: center +``` + +### Components on the Windows host + +The Windows host is a single machine running the Windows OS. WSL instances can +be created and instanced on this host. The UP4W application that is installed +on the Windows host consists of a GUI front end and an agent that runs in the +background. + +A user enters a Pro token and Landscape configuration using the GUI. When the +GUI is launched it starts the Windows Agent, if it's not already running. The agent runs in the background +on the Windows host and manages communication with other components, including +the remote Landscape server and the Pro service running within each instance of +Ubuntu WSL. The agent is responsible for managing the state of instances and +acts as a bridge between those instances and Landscape. If the configuration +details are valid, all new instances will have Ubuntu Pro enabled and will be +able to communicate with the Landscape server. + +```{figure} ../diagrams/structurizr-SystemContainers.png +:name: top-level-arch +:alt: architecture diagram showing coordinating role of agent +:align: center +``` + +It is possible to bypass the GUI and instead configure UP4W using the Windows +registry. This may be the preferred option for those operating at scale. When +UP4W is launched, a registry path is created that can be used to store a Pro +token and a Landscape configuration. A system administrator can use a remote +management solution like Intune to configure the registry on fleets of devices. + +### Components on Ubuntu WSL instances + +The WSL Pro service runs in each instance of Ubuntu WSL. From the host, the +Windows agent communicates with this service. This allows commands to be sent +from the host, which are then executed by the Pro service on each instance. +When an Ubuntu WSL instance is started, the WSL Pro service runs and queries +the Windows agent on the host for the status of the Pro subscription. +If the Pro token is valid, it is retrieved from the Windows agent and +passed to the Pro service running on Ubuntu WSL instances. +If not, Ubuntu Pro is disabled on the instances. + +Pre-installed on each instance of Ubuntu WSL is an Ubuntu Pro client +and a Landscape client. +After a Pro token is provided, the Windows agent can send a +command to the Ubuntu Pro client to execute pro-attach on active instances. +Similarly, when a Landscape configuration is provided, the Windows agent +can send a command to configure the Landscape client in each instance. + +The administrator of the Landscape server can also send commands to the agent +to deploy new instances or delete existing instances. + +```{figure} ../diagrams/structurizr-Production.png +:name: production-arch +:alt: architecture diagram for production, with instances deployed from remote server +:align: center +``` + +Ubuntu WSL instances that are deployed at scale can be extensively customised. +The Landscape API can be used to automate the deployment of a custom rootfs. As +of Ubuntu 24.04 LTS, cloud-init is pre-installed on Ubuntu WSL instances, which +makes it possible to automate the configuration of instances created from that +release. + +### Source code + +UP4W is open-source software. You can look at the code in the [GitHub +repo](https://github.com/canonical/ubuntu-pro-for-wsl). + +The following technologies are used to build UP4W: + +* **Go**: Windows agent and WSL Pro service +* **Flutter**: GUI front end +* **gRPC**: communication between back end and front end diff --git a/docs/index.md b/docs/index.md index b96d9d9a8..52fa3f4f8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,7 +15,7 @@ Read our [getting started tutorial](tutorial/getting-started) to begin. ## In this documentation -````{grid} 1 1 1 1 +````{grid} 1 1 2 2 ```{grid-item-card} [Tutorials](tutorial/index) :link: tutorial/index @@ -24,10 +24,6 @@ Read our [getting started tutorial](tutorial/getting-started) to begin. **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 @@ -35,6 +31,9 @@ Read our [getting started tutorial](tutorial/getting-started) to begin. **Follow step-by-step** instructions for key operations and common tasks ``` +```` + +````{grid} 1 1 2 2 ```{grid-item-card} [Reference](reference/index) :link: reference/index @@ -43,6 +42,13 @@ Read our [getting started tutorial](tutorial/getting-started) to begin. **Read technical descriptions** of important factual information relating to UP4W ``` +```{grid-item-card} [Explanation](explanation/index) +:link: explanation/index +:link-type: doc + +**Read an explanation** of UP4W's system architecture +``` + ```` ## Project and community @@ -59,4 +65,5 @@ UP4W Tutorial How-to guides Reference +Explanation ``` diff --git a/docs/reference/09-qa-process-reference.md b/docs/reference/09-qa-process-reference.md index 3f236434c..712e243de 100644 --- a/docs/reference/09-qa-process-reference.md +++ b/docs/reference/09-qa-process-reference.md @@ -2,6 +2,12 @@ ## Generalities +```{note} +We always use the latest Go version available. Information about specific Go +versions on this page may be outdated, as the version used is periodically +updated. +``` + `wsl-pro-service` is seeded only on WSL images. ``` diff --git a/docs/reference/glossary_up4w_components.md b/docs/reference/glossary_up4w_components.md new file mode 100644 index 000000000..4f21268da --- /dev/null +++ b/docs/reference/glossary_up4w_components.md @@ -0,0 +1,65 @@ +(ref::glossary-up4w-components)= +# Glossary of UP4W components + +The architecture of UP4W and how its components integrate together is covered in our detailed [explanation article](../explanation/ref-arch-explanation.md). +This glossary includes concise descriptions of the components for reference. + +(ref::up4w-gui)= +## GUI front end + +UP4W has a small GUI that helps users provide an Ubuntu Pro token and +[configure Landscape](ref::landscape-config). + +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 first stopping the Windows process `ubuntu-pro-agent-launcher.exe` in Windows Task Manger or by issuing the following command in a PowerShell terminal: + +```text +Stop-Process -Name ubuntu-pro-agent.exe +``` + +You can then launch the GUI to complete the restart. + +(ref::landscape-client)= +## Landscape client + +The Landscape client is a `systemd` unit running inside every Ubuntu WSL instance. It sends information about the system to the Landscape server. The server, in turn, sends instructions that the client executes. + +The Landscape client comes pre-installed in your distro as part of the package `landscape-client`. + +You can check the status of the Landscape client in any particular Ubuntu WSL instance by starting a shell in that instance and running: + +```text +systemctl status landscape-client.service +``` + +(ref::ubuntu-pro-client)= +## Ubuntu Pro client + +The Ubuntu Pro client is a command-line utility 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-pro-client` package, +which comes pre-installed in Ubuntu WSL instances since Ubuntu 24.04 LTS. + +(ref::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 any reason, it can be started by launching the UP4W GUI or running the executable from the terminal, optionally with `-vvv` for verbose logging: + +```text +ubuntu-pro-agent.exe -vvv +``` + +The Windows agent is UP4W's central hub that communicates with all the components to coordinate them. + +(ref::up4w-wsl-pro-service)= +## WSL Pro service + +This is 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 or configuring the [Landscape client](ref::landscape-client). + +You can check the current status of the WSL Pro Service in any particular distro with: + +```text +systemctl status wsl-pro.service +``` diff --git a/docs/reference/index.md b/docs/reference/index.md index 55c85ef4c..90fdb14e1 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -3,14 +3,14 @@ # Reference This section contains concise references relating to how UP4W is designed, -configured and developed: +configured and developed. -Descriptions of key UP4W components can be found here: +A glossary of key UP4W system components can be found here: ```{toctree} :titlesonly: -index_up4w_components +glossary_up4w_components ``` Details on firewall configuration, Landscape setup and using the Windows diff --git a/docs/reference/index_up4w_components.md b/docs/reference/index_up4w_components.md deleted file mode 100644 index a980d56f2..000000000 --- a/docs/reference/index_up4w_components.md +++ /dev/null @@ -1,41 +0,0 @@ -(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/landscape_client.md b/docs/reference/landscape_client.md deleted file mode 100644 index 36e7440dc..000000000 --- a/docs/reference/landscape_client.md +++ /dev/null @@ -1,16 +0,0 @@ -(ref::landscape-client)= -# Landscape client - -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. - -> See more: [Ubuntu manuals | Landscape client](https://manpages.ubuntu.com/manpages/noble/man1/landscape-client.1.html) - -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/ubuntu_pro_client.md b/docs/reference/ubuntu_pro_client.md deleted file mode 100644 index 4da7ae04f..000000000 --- a/docs/reference/ubuntu_pro_client.md +++ /dev/null @@ -1,27 +0,0 @@ -(ref::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](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. -> 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 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/up4w-gui.md b/docs/reference/up4w-gui.md deleted file mode 100644 index 3e6c41878..000000000 --- a/docs/reference/up4w-gui.md +++ /dev/null @@ -1,12 +0,0 @@ -(ref::up4w-gui)= -# Application GUI - -UP4W has a small GUI to help users with: -- Providing or acquiring an [Ubuntu Pro token](ref::ubuntu-pro-token). -- Providing the [Landscape configuration](ref::landscape-config). - -![Image of the Ubuntu Pro for WSL GUI.](./assets/up4w-gui.png) - -## 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. diff --git a/docs/reference/up4w-windows_agent.md b/docs/reference/up4w-windows_agent.md deleted file mode 100644 index 1af72b872..000000000 --- a/docs/reference/up4w-windows_agent.md +++ /dev/null @@ -1,9 +0,0 @@ -(ref::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. - -The Windows agent is UP4W's central hub that communicates with all the components to coordinate them. - - -![Diagram displaying the Windows agent communicating with the GUI, the Landscape server and the WSL-Pro-Service. It also reads the registry.](../diagrams/structurizr-SystemContainers.png) diff --git a/docs/reference/up4w-wsl_pro_service.md b/docs/reference/up4w-wsl_pro_service.md deleted file mode 100644 index 2ae05b5d0..000000000 --- a/docs/reference/up4w-wsl_pro_service.md +++ /dev/null @@ -1,10 +0,0 @@ -(ref::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). - - -You can check the current status of the WSL Pro Service in any particular distro with: -```bash -systemctl status wsl-pro.service -``` diff --git a/docs/reference/windows_registry.md b/docs/reference/windows_registry.md index 17309a29d..ef8172c9f 100644 --- a/docs/reference/windows_registry.md +++ b/docs/reference/windows_registry.md @@ -15,6 +15,6 @@ In UP4W, you can use the Windows registry to supply the configuration for Ubuntu The Windows agent will read the following values from the key at `HK_CURRENT_USER\Software\Canonical\UbuntuPro`: -- Value `UbuntuProToken` (type `String`) expects the [Ubuntu Pro token](ref::ubuntu-pro-token) for the user. +- Value `UbuntuProToken` (type `String`) expects the [Ubuntu Pro token](https://ubuntu.com/pro/subscribe) for the user. - Value `LandscapeConfig` (type `String` or `Multi-line string`) expects the [Landscape configuration](ref::landscape-config).