From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) by lore.proxmox.com (Postfix) with ESMTPS id 9E9171FF13E for ; Fri, 03 Apr 2026 18:56:29 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 612E2878E; Fri, 3 Apr 2026 18:57:00 +0200 (CEST) From: Christoph Heiss To: pdm-devel@lists.proxmox.com Subject: [PATCH datacenter-manager v3 24/38] docs: add documentation for auto-installer integration Date: Fri, 3 Apr 2026 18:53:56 +0200 Message-ID: <20260403165437.2166551-25-c.heiss@proxmox.com> X-Mailer: git-send-email 2.53.0 In-Reply-To: <20260403165437.2166551-1-c.heiss@proxmox.com> References: <20260403165437.2166551-1-c.heiss@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1775235349913 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.067 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: 7VMIMG3D3B5RQ7C7EJ57GCTQAFMCNCBM X-Message-ID-Hash: 7VMIMG3D3B5RQ7C7EJ57GCTQAFMCNCBM X-MailFrom: c.heiss@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox Datacenter Manager development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Signed-off-by: Christoph Heiss --- Changes v2 -> v3: * use concrete URL in example * add section about templating and token authentication Changes v1 -> v2: * new patch docs/automated-installations.rst | 124 +++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 125 insertions(+) create mode 100644 docs/automated-installations.rst diff --git a/docs/automated-installations.rst b/docs/automated-installations.rst new file mode 100644 index 0000000..7c0f828 --- /dev/null +++ b/docs/automated-installations.rst @@ -0,0 +1,124 @@ +.. _automated_installations: + +Automated Installations +======================= + +The Proxmox Datacenter Manager provides integration with the automated +installer for all Proxmox products. + +A detailed documentation of all available options can be found on `our dedicated +wiki page `_. + +.. _autoinst_overview: + +Overview +~~~~~~~~ + +The overview shows all past and ongoing installations done using the Proxmox +Datacenter Manager. It allows access to the raw system information data as sent +by the automated installer before the actual installation, and (if configured) +post-installation notification hook data, containing extensive information about +the newly installed system. + +.. _autoinst_answers: + +Prepared Answers +~~~~~~~~~~~~~~~~ + +This view provides an overview over all defined answer files and allows editing, +copying into new answers and deleting them. For a quick overview, it shows +whether an answer is the default and what target filters have been defined for +that particular configuration. + +Target filter +^^^^^^^^^^^^^ + +Target filter allow you to control what systems should match. + +`Filters`_ are key-value pairs in the format ``key=format``, with keys being +`JSON Pointers`_, and match systems based the identifying information sent by +the installer as JSON document. An example of such a document is provided `on +the wiki +`_. + +JSON Pointers allow for identifying specific values within a JSON document. For +example, to match only Proxmox VE installations by the product name, a filter +entry like ``/product/product=pve`` can be used. + +Values are *globs* and use the same syntax as the automated installer itself. +The following special characters can be used in filters: + +* ``?`` -- matches any single character +* ``*`` -- matches any number of characters, can be none +* ``[a]``, ``[abc]``, ``[0-9]`` -- matches any single character inside the + brackets, ranges are possible + +* ``[!a]`` -- negate the filter, any single character but the ones specified + +A prepared answer can be also set as default, in which case it will be used if +no other more specific answer matches based on its configured target filters. + +.. _autoinst_preparing_iso: + +Templating +^^^^^^^^^^ + +Certain fields support templating via `Handlebars`_ and definable *counters*. +Counters are automatically incremented each time an answer file is served to a +client, allowing for easy provisioning of unique fields, such as per-system +hostnames. + +The following counter is automatically defined when creating a new prepared +answer configuration: + +* ``installation-nr`` -- The current counter value of the number of + installations done with this particular answer configuration. + +This mechanism allows templating on the following fields for prepared answer +configurations: + +* **Administrator email address** +* **Hostname/FQDN** +* **Network IP address (CIDR)** +* **Network gateway** +* **DNS Server address** + +Authentication token management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To use the automated installer integration of Proxmox Datacenter Manager, an +installation process must authenticate itself. This also provides for an +additional scoping mechanism for prepared answer configurations. + +The automated installer integration uses a dedicated token mechanism, separate +from the normal API tokens. + +Preparing an ISO +~~~~~~~~~~~~~~~~ + +To use an installation ISO of a Proxmox product with the Proxmox Datacenter +Manager functionality, the ISO must be appropriately prepared to `fetch an +answer via HTTP`_ from the Proxmox Datacenter Manager using the +``proxmox-auto-install-assistant`` tool, available from the Proxmox VE package +repositories. + +The `target URL`_ for the automated installer must point to +``https:///api2/json/auto-install/answer``, where ```` is the address +under which the Proxmox Datacenter Manager is reachable from the systems to be +installed. + +For example: + +.. code-block:: shell + + proxmox-auto-install-assistant prepare-iso /path/to/source.iso \ + --fetch-from http \ + --url 'https://datacenter.example.com/api2/json/auto-install/answer' \ + --cert-fingerprint 'ab:cd:ef:12:34:56:78:90:a1:b2:c3:d4:e5:f6:7a:8b:9c:0d:aa:bb:cc:dd:ee:ff:21:43:65:87:09:af:bd:ce' \ + --answer-auth-token 'mytoken!ee2a5901-1910-4eb0-b0a2-c914f4adbb75' + +.. _JSON Pointers: https://www.rfc-editor.org/rfc/rfc6901 +.. _fetch an answer via HTTP: https://pve.proxmox.com/edwiki/Automated_Installation#Answer_Fetched_via_HTTP +.. _Filters: https://pve.proxmox.com/wiki/Automated_Installation#Filters +.. _target URL: https://pve.proxmox.com/wiki/Automated_Installation#Answer_Fetched_via_HTTP +.. _Handlebars: https://handlebarsjs.com/guide/ diff --git a/docs/index.rst b/docs/index.rst index 8398f57..2fc8a5d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,6 +25,7 @@ in the section entitled "GNU Free Documentation License". web-ui.rst sdn-integration.rst remotes.rst + automated-installations.rst views.rst access-control.rst sysadmin.rst -- 2.53.0