docs: document key handling

Signed-off-by: Fabian Grünbichler <f.gruenbichler@proxmox.com>

diff --git a/docs/introduction.rst b/docs/introduction.rst
index 8472ed99436b7de2fae2f5efb26118b4ed59b200..1cdda1d13856e4f5b1a469cc3a06a3b029e74310 100644 (file)
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -30,6 +30,33 @@ A default config path of `/etc/proxmox-offline-mirror.cfg` is used, but is
 overridable on a per command basis (for example, to allow operation as non-root
 user).
 
+Offline subscription keys
+=========================
+
+When using `proxmox-offline-mirror` with a corresponding Proxmox Offline Mirror subscription key,
+it is possible to update subscription information for air-gapped systems or those without access
+to the public internet.
+ 
+First, add the mirror key using `proxmox-offline-mirror key add-mirror-key`. This command will
+activate the subscription of the mirroring system.
+ 
+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.
+
+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.
+
+.. 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.
+
+Offline repository mirrors
+==========================
+
 Setting up a mirror
 -------------------
 
@@ -55,6 +82,9 @@ To create the first (and subsequent) snapshots, the following command can be use
 
  proxmox-offline-mirror mirror snapshot create --id debian-bullseye-security
 
+Offline media
+=============
+
 Setting up a medium
 -------------------