From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <a.lauterer@proxmox.com>
Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68])
(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
key-exchange X25519 server-signature RSA-PSS (2048 bits))
(No client certificate requested)
by lists.proxmox.com (Postfix) with ESMTPS id 9F44C9A46
for <pve-devel@lists.proxmox.com>; Tue, 5 Sep 2023 15:29:05 +0200 (CEST)
Received: from firstgate.proxmox.com (localhost [127.0.0.1])
by firstgate.proxmox.com (Proxmox) with ESMTP id 6871F19F0E
for <pve-devel@lists.proxmox.com>; Tue, 5 Sep 2023 15:28:35 +0200 (CEST)
Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com
[94.136.29.106])
(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
key-exchange X25519 server-signature RSA-PSS (2048 bits))
(No client certificate requested)
by firstgate.proxmox.com (Proxmox) with ESMTPS
for <pve-devel@lists.proxmox.com>; Tue, 5 Sep 2023 15:28:34 +0200 (CEST)
Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1])
by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 7BC854228F
for <pve-devel@lists.proxmox.com>; Tue, 5 Sep 2023 15:28:34 +0200 (CEST)
From: Aaron Lauterer <a.lauterer@proxmox.com>
To: pve-devel@lists.proxmox.com
Date: Tue, 5 Sep 2023 15:28:32 +0200
Message-Id: <20230905132832.3179097-7-a.lauterer@proxmox.com>
X-Mailer: git-send-email 2.39.2
In-Reply-To: <20230905132832.3179097-1-a.lauterer@proxmox.com>
References: <20230905132832.3179097-1-a.lauterer@proxmox.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
X-SPAM-LEVEL: Spam detection results: 0
AWL -2.583 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
KAM_SOMETLD_ARE_BAD_TLD 5 .bar, .beauty, .buzz, .cam, .casa, .cfd, .club,
.date, .guru, .link, .live, .monster, .online, .press, .pw, .quest, .rest,
.sbs, .shop, .stream, .top, .trade, .wiki, .work, .xyz TLD abuse
SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record
SPF_PASS -0.001 SPF: sender matches SPF record
Subject: [pve-devel] [RFC docs 6/6] installation: add unattended
documentation
X-BeenThere: pve-devel@lists.proxmox.com
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Proxmox VE development discussion <pve-devel.lists.proxmox.com>
List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pve-devel>,
<mailto:pve-devel-request@lists.proxmox.com?subject=unsubscribe>
List-Archive: <http://lists.proxmox.com/pipermail/pve-devel/>
List-Post: <mailto:pve-devel@lists.proxmox.com>
List-Help: <mailto:pve-devel-request@lists.proxmox.com?subject=help>
List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel>,
<mailto:pve-devel-request@lists.proxmox.com?subject=subscribe>
X-List-Received-Date: Tue, 05 Sep 2023 13:29:05 -0000
Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
---
pve-installation.adoc | 245 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 245 insertions(+)
diff --git a/pve-installation.adoc b/pve-installation.adoc
index aa4e4c9..9011d09 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -298,6 +298,251 @@ following command:
# zpool add <pool-name> log </dev/path_to_fast_ssd>
----
+[[installation_auto]]
+Unattended Installation
+-----------------------
+
+// TODO: rework once it is clearer how the process actually works
+
+The unattended installation can help to automate the installation process from
+the very beginning. It needs the dedicated ISO image for unattended
+installations.
+
+The options that the regular installer would ask for, need to be provided in an
+answer file. The answer file can be placed on a USB flash drive. The volume
+needs to be labeled 'PROXMOXINST' and needs to contain the answer file named
+'answer.toml'.
+
+The answer file allows for fuzzy matching to select the network card and disks
+used for the installation.
+
+[[installation_auto_answer_file]]
+Answer file
+~~~~~~~~~~~
+
+The answer file is expected in `TOML` format. The following example shows an
+answer file that uses the DHCP provided network settings. It will use a ZFS
+Raid 10 with an 'ashift' of '12' and will use all Micron disks it can find.
+
+----
+[global]
+keyboard = "de"
+country = "at"
+fqdn = "pve-1.example.com"
+mailto = "mail@example.com"
+timezone = "Europe/Vienna"
+password = "123456"
+
+[network]
+use_dhcp = true
+
+[disks]
+filesystem = "zfs-raid10"
+zfs.ashift = 12
+filter.ID_SERIAL = "Micron_*"
+----
+
+Global Section
+^^^^^^^^^^^^^^
+
+This section contains the following keys:
+
+`keyboard`:: The keyboard layout. The following options are possible:
+* `de`
+* `de-ch`
+* `dk`
+* `en-gb`
+* `en-us`
+* `es`
+* `fi`
+* `fr`
+* `fr-be`
+* `fr-ca`
+* `fr-ch`
+* `hu`
+* `is`
+* `it`
+* `jp`
+* `lt`
+* `mk`
+* `nl`
+* `no`
+* `pl`
+* `pt`
+* `pt-br`
+* `se`
+* `si`
+* `tr`
+
+`country`:: The country code in the two letter variant. For example `at`, `us`,
+ or `fr`.
+
+`fqdn`:: The fully qualified domain of the host. The domain part will be used
+as the search domain.
+
+`mailto`:: The default email address. Used for notifications.
+
+`timezone`:: The timezone in `tzdata` format. For example `Europe/Vienna` or
+`America/New_York`.
+
+`password`:: The password for the `root` user.
+
+`pre_command`:: A list of commands to run prior to the installation.
+
+`post_command`:: A list of commands run after the installation.
+
+TODO: explain commands and list of available useful CLI tools in the iso
+
+Network Section
+^^^^^^^^^^^^^^^
+
+`use_dhcp`:: Set to `true` if the IP configuration received by DHCP should be
+used.
+
+`cidr`:: IP address in CIDR notation. For example `192.168.1.10/24`.
+
+`dns`:: IP address of the DNS server.
+
+`gateway`:: IP address of the default gateway.
+
+`filter`:: Filter against `UDEV` properties to select the network card. See
+xref:installation_auto_filter[Filters].
+
+
+Disks Section
+^^^^^^^^^^^^^
+
+`filesystem`:: The file system used for the installation. The options are:
+* `ext4`
+* `xfs`
+* `zfs-raid0`
+* `zfs-raid1`
+* `zfs-raid10`
+* `zfs-raidz1`
+* `zfs-raidz2`
+* `zfs-raidz3`
+* `btrfs-raid0`
+* `btrfs-raid1`
+* `btrfs-raid10`
+
+`disk_selection`:: List of disks to use. Useful if you are sure about the disk
+names. For example:
+----
+disk_selection = ["sda", "sdb"]
+----
+
+`filter_match`:: Can be `any` or `all`. Decides if a match of any filter is
+enough or if all filters need to match for a disk to be selected. Default is `any`.
+
+`filter`:: Filter against `UDEV` properties to select disks to install to. See
+xref:installation_auto_filter[Filters]. Filters won't be used if
+`disk_selection` is configured.
+
+`zfs`:: ZFS specific properties. See xref:advanced_zfs_options[Advanced ZFS Configuration Options]
+for more details. The properties are:
+ * `ashift`
+ * `checksum`
+ * `compress`
+ * `copies`
+ * `hdsize`
+
+`lvm`:: Advanced properties that can be used when `ext4` or `xfs` is used as `filesystem`.
+See xref:advanced_lvm_options[Advanced LVM Configuration Options] for more details. The properties are:
+ * `hdsize`
+ * `swapsize`
+ * `maxroot`
+ * `maxvz`
+ * `minfree`
+
+`btrfs`:: BTRFS specific settings. Currently there is only `hdsize`.
+
+[[installation_auto_filter]]
+Filters
+~~~~~~~
+
+Filters allow you to match against device properties exposed by `udevadm`. You
+can see them if you run the following commands. The first is for a disk, the
+second for a network card.
+----
+udevadm info /sys/block/{disk name}
+udevadm info /sys/class/net/{NIC name}
+----
+
+For example:
+
+----
+# udevadm info -p /sys/class/net/enp129s0f0np0 | grep "E:"
+E: DEVPATH=/devices/pci0000:80/0000:80:01.1/0000:81:00.0/net/enp129s0f0np0
+E: SUBSYSTEM=net
+E: INTERFACE=enp129s0f0np0
+E: IFINDEX=6
+E: USEC_INITIALIZED=4808080
+E: ID_NET_NAMING_SCHEME=v252
+E: ID_NET_NAME_MAC=enx1c34da5c5e24
+E: ID_OUI_FROM_DATABASE=Mellanox Technologies, Inc.
+E: ID_NET_NAME_PATH=enp129s0f0np0
+E: ID_BUS=pci
+E: ID_VENDOR_ID=0x15b3
+E: ID_MODEL_ID=0x1015
+E: ID_PCI_CLASS_FROM_DATABASE=Network controller
+E: ID_PCI_SUBCLASS_FROM_DATABASE=Ethernet controller
+E: ID_VENDOR_FROM_DATABASE=Mellanox Technologies
+E: ID_MODEL_FROM_DATABASE=MT27710 Family [ConnectX-4 Lx] (MCX4421A-ACQN ConnectX-4 Lx EN OCP,2x25G)
+E: ID_PATH=pci-0000:81:00.0
+E: ID_PATH_TAG=pci-0000_81_00_0
+E: ID_NET_DRIVER=mlx5_core
+E: ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
+E: ID_NET_NAME=enp129s0f0np0
+E: SYSTEMD_ALIAS=/sys/subsystem/net/devices/enp129s0f0np0
+E: TAGS=:systemd:
+E: CURRENT_TAGS=:systemd:
+----
+
+The key of the filter decides on which property it should be applied to. For
+example, to match against the name of the network card, the filter could look
+like this:
+
+----
+filter.ID_NET_NAME = "enp129s0fn0np0"
+----
+
+Filter support globbing (`*`) at the beginning and end of the search
+string. For example, if we want to match against the vendor part of the MAC
+address in the property `ID_NET_NAME_MAC`, we can use the following filter:
+
+----
+filter.ID_NET_NAME_MAC = "*1c34da*"
+----
+
+In case we would want to match against the full MAC address, we only need to
+use the glob character at the beginning:
+
+----
+filter.ID_NET_NAME_MAC = "*1c34da5c5e24"
+----
+
+Useful Properties
+^^^^^^^^^^^^^^^^^
+
+For network cards, the following properties can be useful:
+
+* `ID_NET_NAME`
+* `ID_NET_NAME_MAC`
+* `ID_VENDOR_FROM_DATABASE`
+* `ID_MODEL_FROM_DATABASE`
+
+For disks, these properties can be useful:
+
+* `DEVNAME`
+* `ID_SERIAL_SHORT`
+* `ID_WWN`
+* `ID_MODEL`
+* `ID_SERIAL`
+
+
+// TODO: showcase a more complicated answer file
+
+
ifndef::wiki[]
Install {pve} on Debian
--
2.39.2