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/howto/02-install.md b/docs/howto/02-install.md similarity index 100% rename from docs/dev/howto/02-install.md rename to docs/howto/02-install.md diff --git a/docs/dev/howto/03-restart.md b/docs/howto/03-restart.md similarity index 100% rename from docs/dev/howto/03-restart.md rename to docs/howto/03-restart.md diff --git a/docs/dev/howto/06-access-the-logs.md b/docs/howto/06-access-the-logs.md similarity index 100% rename from docs/dev/howto/06-access-the-logs.md rename to docs/howto/06-access-the-logs.md diff --git a/docs/dev/howto/07-toggle-features.md b/docs/howto/07-toggle-features.md similarity index 100% rename from docs/dev/howto/07-toggle-features.md rename to docs/howto/07-toggle-features.md diff --git a/docs/dev/howto/index.md b/docs/howto/index-contributing.md similarity index 60% rename from docs/dev/howto/index.md rename to docs/howto/index-contributing.md index b5db4c6a0..73c4ccef5 100644 --- a/docs/dev/howto/index.md +++ b/docs/howto/index-contributing.md @@ -1,11 +1,12 @@ -(dev-howtos)= +(index-contributing)= -# How-to guides +# Contributing to UP4W -These how-to guides cover key operations and processes in Ubuntu Pro for WSL. +These how-to guides help you complete tasks when developing for UP4W. ```{toctree} :titlesonly: +:maxdepth: 1 Install UP4W <02-install> Restart UP4W <03-restart> @@ -13,3 +14,4 @@ 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..3fb9a3a3b 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 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/dev/howto/reset-factory.md b/docs/howto/reset-factory.md similarity index 100% rename from docs/dev/howto/reset-factory.md rename to docs/howto/reset-factory.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) - 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 ``` diff --git a/docs/dev/reference/07-windows-agent-command-line-reference.md b/docs/reference/07-windows-agent-command-line-reference.md similarity index 100% rename from docs/dev/reference/07-windows-agent-command-line-reference.md rename to docs/reference/07-windows-agent-command-line-reference.md diff --git a/docs/dev/reference/08-wsl-pro-service-command-line-reference.md b/docs/reference/08-wsl-pro-service-command-line-reference.md similarity index 100% rename from docs/dev/reference/08-wsl-pro-service-command-line-reference.md rename to docs/reference/08-wsl-pro-service-command-line-reference.md diff --git a/docs/dev/reference/09-qa-process-reference.md b/docs/reference/09-qa-process-reference.md similarity index 100% rename from docs/dev/reference/09-qa-process-reference.md rename to docs/reference/09-qa-process-reference.md 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 diff --git a/docs/reference/index.md b/docs/reference/index.md index 39890a113..55c85ef4c 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 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/dev/reference/index.md b/docs/reference/index_up4w_development.md similarity index 53% rename from docs/dev/reference/index.md rename to docs/reference/index_up4w_development.md index b5de36c8e..f95fdcf5c 100644 --- a/docs/dev/reference/index.md +++ b/docs/reference/index_up4w_development.md @@ -1,13 +1,13 @@ -(reference)= +(debugging-and-testing)= -# Reference +# Debugging and testing -The reference material in this section provides technical descriptions of Ubuntu Pro for WSL. +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 deleted file mode 100644 index ed790e567..000000000 --- a/docs/reference/wsl.md +++ /dev/null @@ -1,7 +0,0 @@ -(ref::wsl)= -# Windows Subsystem for Linux (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) \ No newline at end of file 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 ``` 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: