[pve-devel] [RFC docs 6/6] installation: add unattended documentation
Aaron Lauterer
a.lauterer at proxmox.com
Tue Sep 5 15:28:32 CEST 2023
Signed-off-by: Aaron Lauterer <a.lauterer at 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 at 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
More information about the pve-devel
mailing list