docs: Add machine token usage explanation

custom_wordlist.txt

@@ -26,6 +26,7 @@ CVE
 CVEAPIFixExecuteResult
 cves
 CVEs
+CSV
 devel
 DISA
 Dockerfile
@@ -58,6 +59,7 @@ html
 https
 init
 internetless
+IaaS
 IOTG
 json
 latencies

docs/explanations.rst

@@ -73,4 +73,5 @@ Other Pro features explained
     explanations/what_is_the_daemon.md
     explanations/errors_explained.md
     explanations/deprecation_policy.rst
+    explanations/pro_token_and_machine_usage.rst
 

docs/explanations/pro_token_and_machine_usage.rst

@@ -0,0 +1,70 @@
+.. _pro_token_and_machine_usage:
+
+Machine counts and token usage for Ubuntu Pro
+*********************************************
+
+Ubuntu Pro tokens are used to authenticate your machine and enable access to the services you are entitled to. tokens are unique and specific to your account, so you should treat them as a secret (as you would with a password).
+
+Since tokens are attached to your account and not your machine, you can re-use tokens, even multiple times per day. In this page, we'll discuss how tokens work and how machines are counted against your subscription.
+
+Pro tokens
+----------
+
+- Obtaining tokens:
+    After subscribing to Ubuntu Pro, you can access your tokens through the `Ubuntu Pro Dashboard <Pro_dashboard_>`_. Each token can be used to attach multiple machines depending on the subscription.
+
+- Attaching tokens:
+    Command: Use ``sudo pro attach`` to connect a machine to your Ubuntu Pro subscription.
+
+- Detaching tokens:
+    Command: Use ``sudo pro detach`` to remove a machine from the subscription. Once a machine is detached, the token can be reused to attach another machine. If you are attached on a VM you intend to delete, the token does not need to be detached before the VM is destroyed.
+
+For further information regarding pro commands, refer to our :ref:`Getting started-with Ubuntu Pro client tutorial<tutorial-commands>`.
+
+Monitoring active machines:
+---------------------------
+
+
+- Machine Limits: 
+    Each subscription type has a limit on the number of machines it can cover. For personal subscriptions, this limit is 5 physical machines with unlimited VMs on these machines. For enterprise subscriptions, the limit is based on the number of physical hosts and VMs. 
+    For extensive use beyond 5 machines, consider a commercial subscription. Ubuntu Pro offers scalable solutions for both personal and enterprise needs.
+
+- Active Machine Tracking: 
+    The Ubuntu Pro dashboard and tools like `Landscape <Landscape_>`_ help track the number of active machines, ensuring compliance with subscription limits.
+
+- Unused Licenses and Active Users:
+    The Ubuntu Pro dashboard provides a comprehensive view of all active and attached machines. It shows the number of active machines and helps track unused Landscape licenses, ensuring that you remain within the subscription limits.
+
+- Monitoring with Landscape:
+    Setup: Install the Landscape client and connect it to the Landscape server. For instructions on how to install the Landscape client, refer to the `Landscape Installation Guide <Landscape_install_>`_.
+
+    Audit Machines: Use Landscape’s remote script execution capability to run audit scripts, such as ``uastatus.sh``, to gather detailed information about your Ubuntu Pro subscription across all machines. This information can be exported into a CSV report for further analysis.
+
+Dealing with multiple VMs:
+---------------------------
+
+- VM License Management: 
+    In an IaaS environment where node control is limited, you can contact `Canonical's sales team <pro_sales_form_>`_ to discuss purchasing licenses per single VM rather than per physical node.
+
+- Centralised Management: 
+    For enterprise environments, using Landscape ensures all Ubuntu instances have the necessary Ubuntu Pro entitlements, helping identify any discrepancies or unauthorised usage.
+
+Handling overage of active machines:
+------------------------------------
+
+Canonical monitors the number of active machines. Occasional overages are generally acceptable, but persistent overages may lead to subscription termination.
+
+Frequently Asked Questions:
+===========================
+
+- Can I use Ubuntu Pro Desktop for server use cases?
+    No, using Ubuntu Pro Desktop for non-desktop use cases violates the terms of service. Use an Ubuntu Pro Server subscription for server use.
+
+- How can I handle Ubuntu Pro in airgapped environments?
+    Use an airgapped contract server to distribute tokens within isolated environments, coordinated with Canonical’s Customer Success team. Using Ubuntu Pro in airgapped environments requires a paid subscription and is not available for free susbcriptions.
+
+If you have any additional questions, please visit the `Ubuntu Pro FAQ <FAQ_>`_ for further information.
+
+.. LINKS
+
+.. include:: ../links.txt

docs/links.txt

@@ -15,6 +15,7 @@
 .. _pro_IRC: https://kiwiirc.com/nextclient/irc.libera.chat/ubuntu-server
 .. _tox: https://tox.readthedocs.io/en/latest/
 .. _Ubuntu One: https://login.ubuntu.com/
+.. _pro_sales_form: https://ubuntu.com/contact-us/form?product=pro
 
 .. SERVICES - security
 
@@ -35,6 +36,7 @@
 .. _Livepatch: https://ubuntu.com/security/livepatch
 .. _Landscape: https://ubuntu.com/landscape
 .. _landscape_saas: https://landscape.canonical.com
+.. _landscape_install: https://ubuntu.com/landscape/install
 .. _realtime: https://ubuntu.com/realtime-kernel
 .. _supported_kernels: https://ubuntu.com/security/livepatch/docs/livepatch/reference/kernels