docs: Add machine token usage explanation

custom_wordlist.txt

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

docs/explanations.rst

@@ -74,3 +74,5 @@ Other Pro features explained
     explanations/errors_explained.md
     explanations/deprecation_policy.rst
     explanations/data_collection.rst
+    explanations/pro_token_and_machine_usage.rst
+

docs/explanations/pro_token_and_machine_usage.rst

@@ -0,0 +1,49 @@
+.. _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. These tokens are unique and specific to your account, so you should treat them as a secret (as you would with a password).
+
+In this page, we'll discuss how Ubuntu Pro tokens work and how machines are counted against your subscription.
+
+Ubuntu Pro token(s)
+--------------------
+
+- Obtaining Pro tokens:
+     After subscribing to Ubuntu Pro, you can access your subscriptions through the `Ubuntu Pro Dashboard <Pro_dashboard_>`_. Each subscription includes a Ubuntu Pro token that can be used to attach as many machines as the subscription allows.
+
+- Attaching Pro tokens:
+    Command: Use ``sudo pro attach`` to connect a machine to your Ubuntu Pro subscription.
+
+- Detaching Pro tokens:
+    Command: Use ``sudo pro detach`` to remove a machine from the subscription. 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:
+---------------------------
+
+Active machines are counted based on the number of machines attached to your subscription at a given time. An active machine is defined as a machine that has been attached to a given subscription at any point within the past 24 hours.
+
+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. Enterprise subscriptions will have a higher limit and may differentiate between physical and virtual machines.
+For use beyond 5 physical machines, consider an enterprise subscription.
+
+The Ubuntu Pro dashboard can help track the number of active machines, ensuring compliance with subscription limits. It provides a comprehensive view of all active and attached machines. It helps track the number of active machines, ensuring that you remain within the subscription limits.
+
+Dealing with multiple VMs:
+---------------------------
+
+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.
+
+
+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.
+
+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