From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <pve-devel-bounces@lists.proxmox.com>
Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68])
by lore.proxmox.com (Postfix) with ESMTPS id 8B2CB1FF15C
for <inbox@lore.proxmox.com>; Wed, 5 Mar 2025 10:25:59 +0100 (CET)
Received: from firstgate.proxmox.com (localhost [127.0.0.1])
by firstgate.proxmox.com (Proxmox) with ESMTP id 937501096B;
Wed, 5 Mar 2025 10:25:53 +0100 (CET)
Mime-Version: 1.0
Date: Wed, 05 Mar 2025 10:25:19 +0100
Message-Id: <D88838AD1NYP.2F8AFY2DDINYC@proxmox.com>
From: "Shannon Sterz" <s.sterz@proxmox.com>
To: "Proxmox VE development discussion" <pve-devel@lists.proxmox.com>
Cc: "pve-devel" <pve-devel-bounces@lists.proxmox.com>
X-Mailer: aerc 0.20.1-0-g2ecb8770224a-dirty
References: <20250304154101.3-1-a.zeidler@proxmox.com>
<20250304154101.3-7-a.zeidler@proxmox.com>
In-Reply-To: <20250304154101.3-7-a.zeidler@proxmox.com>
X-SPAM-LEVEL: Spam detection results: 0
AWL -0.012 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
SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record
SPF_PASS -0.001 SPF: sender matches SPF record
Subject: Re: [pve-devel] [PATCH docs 6/7] installer: revise installation
steps and introduce sections
X-BeenThere: pve-devel@lists.proxmox.com
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Proxmox VE development discussion <pve-devel.lists.proxmox.com>
List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pve-devel>,
<mailto:pve-devel-request@lists.proxmox.com?subject=unsubscribe>
List-Archive: <http://lists.proxmox.com/pipermail/pve-devel/>
List-Post: <mailto:pve-devel@lists.proxmox.com>
List-Help: <mailto:pve-devel-request@lists.proxmox.com?subject=help>
List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel>,
<mailto:pve-devel-request@lists.proxmox.com?subject=subscribe>
Reply-To: Proxmox VE development discussion <pve-devel@lists.proxmox.com>
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Errors-To: pve-devel-bounces@lists.proxmox.com
Sender: "pve-devel" <pve-devel-bounces@lists.proxmox.com>
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@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
> ~~~~~~~~~~~~~~~~~~~~
>
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel