[pve-devel] [PATCH v1 docs 18/18] installation: add unattended documentation
Aaron Lauterer
a.lauterer at proxmox.com
Tue Jan 23 18:00:53 CET 2024
Signed-off-by: Aaron Lauterer <a.lauterer at proxmox.com>
---
Once we have defined the process on how it can be started, what the ISO
is called and so forth, we can include that in the documentation.
We should also add an example section to showcase the possibilities
better.
Maybe also explain how the post/pre commands can be used. Maybe even how
to chroot into the installation to add further customizations. For the
latter, a helper chroot tool, like the arch-chroot might be useful to
have.
pve-installation.adoc | 267 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 267 insertions(+)
diff --git a/pve-installation.adoc b/pve-installation.adoc
index 1e909e2..5d6d887 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -300,6 +300,273 @@ 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.
+
+
+For the automatic installation, 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 to match to select the network card and disks used for
+the installation by certain properties of the devices.
+
+[[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
+
+`reboot_on_error`:: Set to `true` is the installer should automatically reboot
+if erros are encountered. The default behavior is to wait to give the
+administrator a chance to investigate why the unattended installation failed.
+
+
+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`. The
+`proxmox-installer-filter` utility can show the properties and let you test
+filters in advance. It is available in the installer environment (debug mode)
+and on {pve}.
+
+For example, to fetch information for disks, the output will be a list of all
+the information for the disks present:
+
+----
+# proxmox-installer-filter info -t disk
+[…]
+ "nvme3n1": {
+ "CURRENT_TAGS": ":systemd:",
+ "DEVLINKS": "/dev/disk/by-id/nvme-Micron_9300_MTFDHAL3T2TDR_194525XXXXXX_1 /dev/disk/by-diskseq/16 /dev/disk/by-id/nvme-Micron_9300_MTFDHAL3T2TDR_194525XXXXXX /dev/disk/by-path/pci-0000:04:00.0-nvme-1 /dev/disk/by-id/nvme-eui.000000000000001500a0750125xxxxxx",
+ "DEVNAME": "/dev/nvme3n1",
+ "DEVPATH": "/devices/pci0000:00/0000:00:01.4/0000:04:00.0/nvme/nvme3/nvme3n1",
+ "DEVTYPE": "disk",
+ "DISKSEQ": "16",
+ "ID_MODEL": "Micron_9300_MTFDHAL3T2TDR",
+ "ID_NSID": "1",
+ "ID_PATH": "pci-0000:04:00.0-nvme-1",
+ "ID_PATH_TAG": "pci-0000_04_00_0-nvme-1",
+ "ID_REVISION": "11300DN0",
+ "ID_SERIAL": "Micron_9300_MTFDHAL3T2TDR_194525XXXXXX_1",
+ "ID_SERIAL_SHORT": "1945250F1E8C",
+ "ID_WWN": "eui.000000000000001500a07501250f1e8c",
+ "MAJOR": "259",
+ "MINOR": "3",
+ "SUBSYSTEM": "block",
+ "SYSTEMD_READY": "1",
+ "TAGS": ":systemd:",
+ "USEC_INITIALIZED": "6371432"
+ }
+[…]
+----
+
+The key of the filter decides on which property it should be applied to. For
+example, to match against the vendor and model number of the disk, the filter
+in the answer file could look like this:
+
+----
+filter.ID_SERIAL = "Micron_9300*"
+----
+
+This will match for all Micron 9300 disks in the server. By running the
+following command we can verify which disks will be found:
+
+----
+# proxmox-installer-filter match disk 'ID_MODEL=Micron_9300*'
+[
+ "nvme0n1",
+ "nvme1n1",
+ "nvme2n1",
+ "nvme3n1"
+]
+----
+
+This filter would be enough if these four disks should be used for the {pve} installation.
+
+The `filter_match` parameter controls if all filters must apply, or if it is
+enough if any of the filters apply. This makes it possible to use different
+disk models for the installation.
+
+For example, if you want to use disks from different vendors, you could specify
+the following two filters to match against any Micron and Samsung disk:
+
+----
+filter.ID_SERIAL = "Micron*"
+filter.ID_MODEL = "Samsung*"
+----
+
+Two different keys are used as each key can only be used once. To test this
+with the `proxmox-install-filter` tool, the command would look like this:
+
+----
+proxmox-install-filter match disk 'ID_SERIAL=Micron*' 'ID_MODEL=Samsung*'
+----
+Since the CLI shell will most likely interpret the `*` globbing character
+itself, it is a good idea to put the filters inside single quotes `'`.
+
+NOTE: For network cards, only the first match will be used. The installer
+requires only one network card. More complex network setups can be configured
+after the installation. Using properties with unique identifiers will result in
+the most predictable behavior. For example, the MAC address.
+
+Filter Syntax
+^^^^^^^^^^^^^
+
+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
+
+
+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