[pve-devel] [PATCH docs 6/7] installer: revise installation steps and introduce sections

[Shannon Sterz]

On Tue Mar 4, 2025 at 4:41 PM CET, Alexander Zeidler wrote:
> * Introduce sections and subsections to enable better readability.
> * Move screenshots to their corresponding installation step and add
>   blank lines for proper formatting.
>
> Notable changes:
>
> Step 1:
> * Since the EULA is only available when mounting the ISO file or booting
>   the prepared installer medium, briefly describe the EULA and take the
>   opportunity to link to the subscription page, subscription agreement
>   and media kit. Do not add a screenshot, as this is not important and
>   the legal text could change.
>
> Step 2:
> * Mention that the same storage used for installation may also be usable
>   for guest disks, further storage can be added after installation.
> * Restructure the different file systems for a better overview.
> * The default selection of all disks is only true for file systems with
>   RAID modes, therefore move it to the "ZFS/BTRFS" segment.
> * Link to the ZFS performance tips, as they would otherwise be
>   overlooked much further down.
> * Add BTRFS (as technology preview) and link to its advanced options.
>
> Step 4:
> * Mention that root access to any node in the cluster enables root
>   access to all other nodes. Hence, the specified password could be the
>   same (strong) on all nodes.
> * Add a reminder of the importance of a monitoring system.
> * For example, to be more compatible with current NIST recommendations
>   (https://pages.nist.gov/800-63-4/sp800-63b.html#passwordver) for a
>   secure password, mention only the most important properties and the
>   possible use of passphrases.
>
> Step 5:
> * Mention the involvement of DHCP servers.
>
> Step 6:
> * Mention when the automatic reboot checkbox should be deselected.
>
> Signed-off-by: Alexander Zeidler <a.zeidler at proxmox.com>
> ---
>  pve-installation.adoc | 175 ++++++++++++++++++++++++++++++------------
>  1 file changed, 127 insertions(+), 48 deletions(-)
>
> diff --git a/pve-installation.adoc b/pve-installation.adoc
> index 3dee709..3b3dc5d 100644
> --- a/pve-installation.adoc
> +++ b/pve-installation.adoc
> @@ -165,95 +165,173 @@ of errors. Secure Boot must be turned off in the UEFI firmware setup utility to
>  run this option.
>
>
> +Installation Steps
> +~~~~~~~~~~~~~~~~~~
> +
> +Step 1: EULA
> +^^^^^^^^^^^^
> +
> +Start by reading our EULA (End User License Agreement). It mainly
> +consists of a description of the project's AGPLv3 license, that you
> +need to purchase a dedicated {pricing-url}[{pve} subscription] for any
> +commercial support guarantees according to the
> +{website}en/downloads/proxmox-virtual-environment/agreements/proxmox-ve-subscription-agreement[
> +subscription agreement], and that "Proxmox" and the
> +{website}en/about/company-details/media-kit[Proxmox logo] are
> +registered trademarks of {proxmoxGmbh}. The full EULA text is included
> +in the official installation ISO image.
> +
> +Step 2: Disk Setup
> +^^^^^^^^^^^^^^^^^^
>  [thumbnail="screenshot/pve-select-target-disk.png"]
>
> -The first step is to read our EULA (End User License Agreement). Following this,
> -you can select the target hard disk(s) for the installation.
> +Decide where {pve} should be installed on. Depending on the size,

imo: either lose the "on" at the end your re-phrase that to make it
clearer that this decides the boot disk setup, like so, maybe:

Configure the boot drive setup for {pve}. Depending...

> +performance and RAID level of your disk setup, the same storage may be
> +appropriate for storing guest disks. Further storages can be added
> +after installation.
>
> -CAUTION: By default, the whole server is used and all existing data is removed.
> -Make sure there is no important data on the server before proceeding with the
> -installation.
> +CAUTION: Any existing data on the selected drives will be overwritten!
> +Therefore, make sure that they do not contain any still needed data
> +before proceeding.

see my previous comment on "still needed data".

>
> -The `Options` button lets you select the target file system, which
> -defaults to `ext4`. The installer uses LVM if you select
> -`ext4` or `xfs` as a file system, and offers additional options to
> -restrict LVM space (see xref:advanced_lvm_options[below]).
> +The **Options** button lets you select the target file system, which
> +defaults to `ext4`.
>
> -{pve} can also be installed on ZFS. As ZFS offers several software RAID levels,
> -this is an option for systems that don't have a hardware RAID controller. The
> -target disks must be selected in the `Options` dialog. More ZFS specific
> -settings can be changed under xref:advanced_zfs_options[`Advanced Options`].
> +ext4/xfs::
>
> -WARNING: ZFS on top of any hardware RAID is not supported and can result in data
> -loss.
> +If you choose `ext4` or `xfs`, they are put on top
> +of LVM. To adapt the logical volume sizes to your needs, see the
> +options xref:advanced_lvm_options[below].
>
> +ZFS/BTRFS::
> +
> +File systems with a software RAID level are especially interesting if
> +redundancy is not provided by a hardware RAID controller.
> ++
> +WARNING: xref:chapter_zfs[ZFS] on top of any hardware RAID is not
> +supported and can result in data loss.
> ++
> +WARNING: xref:chapter_btrfs[BTRFS] integration is currently a
> +**technology preview** in {pve}.
> ++
> +CAUTION: If you select a file system with a RAID level in the
> +installer, all disks will be used by default. If certain disks should
> +not be used, exclude them via drop down menu.

"via the drop down menu" reads better to me

> ++
> +When deciding on ZFS, please note the
> +xref:zfs_performance_tips[performance tips].
> ++
> +The **Advanced Options** for ZFS are decribed

described not decribed

> +xref:advanced_zfs_options[here] and for BTRFS

imo "and for BTRFS you can find them here" would sound better

> +xref:advanced_btrfs_options[here].
> +
> +
> +Step 3: Basic Settings
> +^^^^^^^^^^^^^^^^^^^^^^
>  [thumbnail="screenshot/pve-select-location.png"]
>
> -The next page asks for basic configuration options like your location, time
> +This page asks for basic configuration options like your location, time
>  zone, and keyboard layout. The location is used to select a nearby download
>  server, in order to increase the speed of updates. The installer is usually able
>  to auto-detect these settings, so you only need to change them in rare
>  situations when auto-detection fails, or when you want to use a keyboard layout
>  not commonly used in your country.
> + +
> + +
> + +
> + +
> + +
>
> -[thumbnail="screenshot/pve-set-password.png", float="left"]
>
> -Next the password of the superuser (`root`) and an email address needs to be
> -specified. The password must consist of at least 8 characters. It's highly
> -recommended to use a stronger password. Some guidelines are:
> +Step 4: System Administrator
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +[thumbnail="screenshot/pve-set-password.png"]
>
> -- Use a minimum password length of at least 12 characters.
> +.Password
> +Specify the password for `root` (superuser). Successful login as root
> +on any cluster node is sufficient to also have root access to all
> +other nodes.
>
> -- Include lowercase and uppercase alphabetic characters, numbers, and symbols.
> +NOTE: Make sure that your monitoring system notifies you of failed
> +login attempts at an early stage.
>
> -- Avoid character repetition, keyboard patterns, common dictionary words,
> -  letter or number sequences, usernames, relative or pet names, romantic links
> -  (current or past), and biographical information (for example ID numbers,
> -  ancestors' names or dates).
> +It is highly recommended to use a strong password, some guidelines
> +are:
>
> -The email address is used to send notifications to the system administrator.
> -For example:
> +- Specify a globally unique password, no keyboard patterns, names or
> +  words from a dictionary.
> +
> +- The shorter the password, the more complex it needs to be. We
> +  recommend a minimum length of 12 characters.

well... yes and no, trading of complexity for length is an option, but
length increases the time it takes to brute-force a password
exponentially. increasing the complexity only yields polynomial
increases. please make sure that this is clear here.

longer less complex passwords > shorter more complex ones

also since we upped the minimum from 5 to 8, you could also follow nist
here and go to 15 [1]. might want to link to the nist recommendations
here too

[1]: https://pages.nist.gov/800-63-4/sp800-63b.html#passwordver

> +
> +- To avoid complexity, a passphrase can be used. When using the
> +  diceware method, the security increases with the number of
> +  concatenated words.
> +
> +.E-Mail
> +Enter the email address of the system administrator, to whom
> +notifications will then be sent, such as:

you can lose the "then" here

>
>  - Information about available package updates.
>
>  - Error messages from periodic 'cron' jobs.
>
> -[thumbnail="screenshot/pve-setup-network.png"]
>
> -All those notification mails will be sent to the specified email address.
> +Step 5: Network Settings
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +[thumbnail="screenshot/pve-setup-network.png"]
>
> -The last step is the network configuration. Network interfaces that are 'UP'
> -show a filled circle in front of their name in the drop down menu. Please note
> -that during installation you can either specify an IPv4 or IPv6 address, but not
> -both. To configure a dual stack node, add additional IP addresses after the
> -installation.
> +While the installer may already have received some network settings
> +from your DHCP server, adapt them as needed.
>
> -[thumbnail="screenshot/pve-installation.png", float="left"]
> +Network interfaces that are 'UP' show a filled circle in front of
> +their name in the drop down menu.
>
> -The next step shows a summary of the previously selected options. Please
> -re-check every setting and use the `Previous` button if a setting needs to be
> -changed.
> +Please note that during installation you can either specify an IPv4 or
> +IPv6 address, but not both. To configure a dual stack node, add
> +additional IP addresses after the installation.
> + +
> + +
> + +
> + +
>
> -After clicking `Install`, the installer will begin to format the disks and copy
> -packages to the target disk(s). Please wait until this step has finished; then
> -remove the installation medium and restart your system.
>
> +Step 6: Configuration Summary
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  [thumbnail="screenshot/pve-install-summary.png"]
>
> -Copying the packages usually takes several minutes, mostly depending on the
> -speed of the installation medium and the target disk performance.
> +Please re-check every setting at the shown summary and use the
> +**Previous** button if a correction is needed.
> +
> +If your server has automatically booted from your installation medium,
> +untick the checkbox 'Automatically reboot after successful installation'.
> +Once the installation has finished, remove the installation medium
> +and click on **Reboot**.
> + +
> + +
> + +
> + +
> +
> +
> +Step 7: Installation Process
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +[thumbnail="screenshot/pve-installation.png"]
>
> -When copying and setting up the packages has finished, you can reboot the
> -server. This will be done automatically after a few seconds by default.
> +After clicking **Install**, the installer will format the selected
> +disks, copy packages to them and apply your specified settings. This
> +process will take a few minutes, depending on the performance of your
> +installation medium and the selected disks.
>
>  .Installation Failure
>
>  If the installation failed, check out specific errors on the second TTY
> -('CTRL + ALT + F2') and ensure that the systems meets the
> +('CTRL + ALT + F2') and ensure that the system meets the
>  xref:install_minimal_requirements[minimum requirements].
>
> -If the installation is still not working, look at the
> +If the installation still fails, look at the
>  xref:getting_help[how to get help chapter].
> + +
> + +
>
>
>  Accessing the Management Interface Post-Installation
> @@ -394,6 +472,7 @@ Defines the total hard disk size to be used. This is useful to save free space
>  on the hard disk(s) for further partitioning (for example, to create a
>  swap partition).
>
> +[[zfs_performance_tips]]
>  ZFS Performance Tips
>  ~~~~~~~~~~~~~~~~~~~~
>