docs: restructur/expand offline key chapter

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

diff --git a/docs/offline-keys.rst b/docs/offline-keys.rst
index 5c18d88a9d1f94271ba6c525cf2bf9b819787727..1dfbd757b63b20b24164c43e48589f25a9907a0d 100644 (file)
--- a/docs/offline-keys.rst
+++ b/docs/offline-keys.rst
@@ -5,6 +5,14 @@ When using ``proxmox-offline-mirror`` with a corresponding Proxmox Offline Mirro
 it is possible to update subscription information for air-gapped systems, or those without access
 to the public internet.
 
+The offline mirror tool will take care of registering the subscription keys in the Proxmox shop,
+which then responds with a signed data blob, if the key is valid. The signed response can then get
+exported to a offline medium and used to set the subscription key in a Proxmox project, without any
+need for an internet connection on the host itself.
+
+Setup Offline Mirror Key
+------------------------
+
 First, add the `pom-<keyid>` mirror key using ``proxmox-offline-mirror key add-mirror-key <key>``.
 This command will activate the subscription of the mirroring system.
 
@@ -13,16 +21,41 @@ This command will activate the subscription of the mirroring system.
    Proxmox Mail Gateway hosts got standard or premium subscriptions you may be elligible for free
    offline mirroring subscription, in that case also write a mail to <sales@proxmox.com> for details.
 
-Next, gather the server IDs of the systems that shall be set up for offline keys, and add them
-together with the system's subscription key using ``proxmox-offline-mirror key add``. By default,
-this command will fetch updated subscription information from Proxmox licensing servers.
+Gather Server IDs
+-----------------
 
-You can refresh the subscription information for a single (``--key XX``) or all configured keys
-using ``proxmox-offline-mirror key refresh``. The subscription information is transferred to a
-medium (see below) and can then be activated on the offline system with either
-``proxmox-apt-repo offline-key`` or ``proxmox-apt-repo setup``. This process must be repeated at least
-once a year or before the nextduedate of the subscription key is reached, whichever comes first.
+Next, gather the server IDs of the systems that shall be set up for offline keys. That information
+is visible in the subscription panel of each host, or using the CLI like:
+
+- ``pvesubscription get`` for Proxmox VE
+
+- ``proxmox-backup-manager subscription get`` for Proxmox Backup server
+
+- ``pmgsubscription get`` for Proxmox Mail Gateway
+
+Register & Refresh Keys
+-----------------------
 
 .. note:: Configuring an active product subscription key (*as well as* a Proxmox Offline Mirror
    subscription) is required for ``proxmox-offline-mirror`` to be able to access and mirror a
    product's enterprise repository.
+
+Register the hosts with the systems's server IDs and subscription keys using
+``proxmox-offline-mirror key add``, for example:
+
+.. code-block:: console
+
+  proxmox-offline-mirror key add pve2p-12345... ABCDEF0123...
+
+By default, this command will fetch updated subscription information from Proxmox licensing servers.
+
+You can refresh the subscription information for a single (``--key XX``) or all configured keys
+using ``proxmox-offline-mirror key refresh``.
+
+Deploy Keys
+-----------
+
+The subscription information is transferred to a medium (see :ref:`sync_medium`) and can then be
+activated on the offline system with either ``proxmox-apt-repo offline-key`` or ``proxmox-apt-repo
+setup``. This process must be repeated at least once a year or before the nextduedate of the
+subscription key is reached, whichever comes first.

diff --git a/docs/offline-media.rst b/docs/offline-media.rst
index edfa0f7278513f4ef0471a06196218b89a62a157..0f10777a5d42977b2c3167392f170a7ba4c5f3a9 100644 (file)
--- a/docs/offline-media.rst
+++ b/docs/offline-media.rst
@@ -19,6 +19,8 @@ following command:
    --verify true \
    --mountpoint /path/where/medium/is/mounted
 
+.. _sync_medium:
+
 Syncing a Medium
 ----------------