docs: added firewall requirements (#709)

Documented firewall requirements with a diagram and a table.
Added a link to the requirements from the how to set up page.

UDENG-2446

docs/.custom_wordlist.txt

@@ -37,14 +37,19 @@ changelog
 compinit
 config
 dev
+gapped
+grpc
+https
 FIPS
 fpath
 FQDN
 HIPAA
 Hostagent
 LTS
+os
 SLA
 SRU
+tcp
 toolchain
 zshrc
 ESM

docs/custom_conf.py

@@ -123,7 +123,10 @@
     'http://127.0.0.1:8000',
 
     # Linkcheck does not have access to the repo
-    'https://github.com/canonical/ubuntu-pro-for-wsl/*'
+    'https://github.com/canonical/ubuntu-pro-for-wsl/*',
+
+    # Not a URL in the reference document
+    r'http://contracts.canonical.com'
     ]
 
 # Pages on which to ignore anchors

docs/howto/set-up-up4w.md

@@ -1,11 +1,12 @@
 # How to install and configure UP4W
 
-## 1. Check that you meet UP4W prerequisites
+## 1. Check that you meet the prerequisites
 
 To install and configure UP4W you will need:
 
 - A Windows host
 - An Ubuntu Pro token
+- Verify that the [firewall rules are correctly set up](../reference/firewall_requirements.md)
 
 
 <details><summary> How do I get an Ubuntu Pro token? </summary> 

docs/reference/firewall_requirements.md

@@ -0,0 +1,26 @@
+# Firewall requirements
+
+Firewall rules must be configured for Ubuntu Pro for WSL to operate fully.
+
+The following figure shows the possible connections between the different components and their default ports and protocols.
+
+![Firewall considerations.](./assets/firewall_requirements.png)
+
+The following table lists the default ports and protocols used by Ubuntu Pro for WSL:
+
+| Description | Client System | Server System | Protocol | Default Port | Target address |
+|-------------|---------------|---------------|----------|--------------|----------------|
+| Required for online installation of WSL instances[^1].|Windows Host / Pro Agent |MS Store | tcp | 443 (https) | See [Microsoft documentation](https://learn.microsoft.com/en-us/microsoft-store/prerequisites-microsoft-store-for-business) for a list of addresses to allow. |
+| Ubuntu Pro enablement[^2] | Windows Host / Pro Agent |Canonical Contract Server |tcp |443 (https) | contracts.canonical.com |
+| Landscape management[^2] | Windows Host / Pro Agent | Landscape Server | tcp | 6554 (grpc) | On-premise Landscape address |
+| WSL instance management on the Windows host. Firewall rules set up at installation time of the WSL Pro agent. | WSL Instance / wsl-pro-service | Windows Host / Pro Agent | tcp | 49152-65535 (dynamic) | Hyper-V Virtual Ethernet Adapter IP |
+| Ubuntu Pro[^2][^3]. | WSL Instance / Ubuntu Pro client | Canonical Contract Server | tcp | 443 (https) | contracts.canonical.com |
+| Landscape[^2]. |  WSL Instance / Ubuntu Pro client | Landscape Server | tcp | 443 (https) | On-premise Landscape address |
+
+If the client system is behind a proxy, ensure that the proxy is configured to allow the required connections.
+
+[^1]: Access to the Microsoft Store is required for the online installation of WSL instances. Without it Ubuntu Pro for WSL will still be functional but it will not be possible to install WSL instances centrally from Landscape. In this case WSL instances have to be installed manually on the Windows hosts.
+
+[^2]: Access to the contract server and Landscape server is required for proper operation of Ubuntu Pro for WSL.
+
+[^3]: For air-gapped installation refer to the [Ubuntu Pro documentation](https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/explanations/using_pro_offline/).

docs/reference/index.md

@@ -6,6 +6,7 @@ pieces that make up the Ubuntu Pro for WSL tool and the value it provides.
 ```{toctree}
 :titlesonly:
 
+firewall_requirements
 landscape
 landscape_client
 ubuntu_pro