[pve-devel] [RFC docs 6/6] installation: add unattended documentation

[Aaron Lauterer <a.lauterer@proxmox.com>]

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