From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 ; 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 ; 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 ; 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 ; Tue, 5 Sep 2023 15:28:34 +0200 (CEST) From: Aaron Lauterer 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 05 Sep 2023 13:29:05 -0000 Signed-off-by: Aaron Lauterer --- 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 log ---- +[[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