[pve-devel] [PATCH v1 docs 0/7] Revise installation chapter

[pve-devel] [PATCH v1 docs 0/7] Revise installation chapter

[Alexander Zeidler]

Alexander Zeidler (7):
  system-requirements: revise subchapter and provide more details
  installation: prepare medium: revise subchapter
  installation: revise introduction
  installer: revise introduction
  installer: revise boot menu description and introduce sections
  installer: revise installation steps and introduce sections
  installer: revise intro of advanced ZFS/BTRFS configuration options

 pve-installation-media.adoc  | 127 +++++++++-----
 pve-installation.adoc        | 312 +++++++++++++++++++++++------------
 pve-system-requirements.adoc |  29 +++-
 3 files changed, 311 insertions(+), 157 deletions(-)

-- 
2.39.5



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH docs 1/7] system-requirements: revise subchapter and provide more details

[Alexander Zeidler]

Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
 pve-system-requirements.adoc | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/pve-system-requirements.adoc b/pve-system-requirements.adoc
index 8a982a8..82d9be5 100644
--- a/pve-system-requirements.adoc
+++ b/pve-system-requirements.adoc
@@ -1,3 +1,4 @@
+[[system_requirements]]
 System Requirements
 -------------------
 ifdef::wiki[]
@@ -6,7 +7,8 @@ endif::wiki[]
 
 We recommend using high quality server hardware, when running {pve} in
 production. To further decrease the impact of a failed host, you can run {pve} in
-a cluster with highly available (HA) virtual machines and containers.
+a cluster with xref:chapter_ha_manager[highly available (HA)] virtual
+machines and containers.
 
 {pve} can use local storage (DAS), SAN, NAS, and distributed storage like Ceph
 RBD. For details see xref:chapter_storage[chapter storage].
@@ -26,7 +28,9 @@ used in production.
 
 * Hard drive
 
-* One network card (NIC)
+* One network card (NIC), used for fetching system updates and access
+via xref:chapter_gui[web interface], `ssh` or
+link:api-viewer/index.html[{pve} API]
 
 
 [[install_recommended_requirements]]
@@ -39,15 +43,22 @@ Recommended System Requirements
   guests. For Ceph and ZFS, additional memory is required; approximately 1GB of
   memory for every TB of used storage.
 
-* Fast and redundant storage, best results are achieved with SSDs.
+* Fast and redundant storage, best results are achieved with SSDs. Do
+  not use SD cards or USB flash drives, as these have a lower
+  durability and performance.
 
-* OS storage: Use a hardware RAID with battery protected write cache (``BBU'')
-  or non-RAID with ZFS (optional SSD for ZIL).
+* OS storage:
+** An HBA with a redundant xref:chapter_zfs[ZFS] RAID level. If not
+   using fast enterprise SSDs with power-loss protection, optionally
+   add one for use as xref:sysadmin_zfs_add_cache_and_log_dev[SLOG].
+** Or a hardware RAID controller with battery-backed write cache (BBU)
+   and not ZFS, as the combination can lead to data loss.
 
 * VM storage:
-** For local storage, use either a hardware RAID with battery backed write cache
-  (BBU) or non-RAID for ZFS and Ceph. Neither ZFS nor Ceph are compatible with a
-  hardware RAID controller.
+** For local storage, the same recommendations apply as for OS
+   storage. However, if a hardware RAID controller is used, in
+   addition to ZFS, xref:chapter_pveceph[Ceph] is also incompatible
+   with it.
 ** Shared and distributed storage is possible.
 ** SSDs with Power-Loss-Protection (PLP) are recommended for good performance.
   Using consumer SSDs is discouraged.
@@ -75,7 +86,7 @@ browsers:
 
 * Firefox, a release from the current year, or the latest Extended Support Release
 * Chrome, a release from the current year
-* Microsoft's currently supported version of Edge
+* Edge, Microsoft's currently supported release
 * Safari, a release from the current year
 
 When accessed from a mobile device, {pve} will show a lightweight, touch-based
-- 
2.39.5



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH docs 2/7] installation: prepare medium: revise subchapter

[Alexander Zeidler]

* Consistently use "medium" (singular), as only one is needed for
  installation (filename "pve-installation-media.adoc" not renamed)

* Revise the introduction:
** Remove CD-ROM (too little storage space) but keep DVD
** Copy to it the installer attributes from subchapter "Using the {pve}
   Installer" (will get removed there in a follow-up patch)
** Rephrase slightly

* Revise "Prepare a USB Flash Drive as Installation Medium":
** Update minimum required flash drive storage space to 2 GB
** Mention explicitly that data get overwritten on installation media
** Rearrange the two admonitions according their importance and for
better reading flow

* Revise "Instructions for GNU/Linux":
** Rearrange the steps so that they correspond to the actual sequence
** Mention the likely required root privilege
** Use `cp` instead of `dd`, as it is used in the Debian docs nowadays
[0], the difference in speed appears to be negligible, and for beginners
it is also less complex and easier to understand/type

[0] https://www.debian.org/releases/bookworm/amd64/ch04s03.en.html

* Revise "Instructions for macOS", warn about overwriting the wrong disk
* Slightly rephrase "Instructions for Windows"
* Revise the wiki-only section "Boot your Server from the USB Flash
  Drive" and point to possible boot problems
* Add the `diskutil eject` command to safely unplug the USB device

Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
 pve-installation-media.adoc | 127 +++++++++++++++++++++++-------------
 pve-installation.adoc       |   2 +-
 2 files changed, 83 insertions(+), 46 deletions(-)

diff --git a/pve-installation-media.adoc b/pve-installation-media.adoc
index a1c9402..1a18ea6 100644
--- a/pve-installation-media.adoc
+++ b/pve-installation-media.adoc
@@ -1,74 +1,97 @@
 [[installation_prepare_media]]
-Prepare Installation Media
+Prepare Installation Medium
 --------------------------
 ifdef::wiki[]
 :pve-toplevel:
 endif::wiki[]
 
-Download the installer ISO image from: {website}en/downloads/proxmox-virtual-environment/iso
+To boot the recommended interactive installer, start by downloading
+the latest installer ISO from:
 
-The {pve} installation media is a hybrid ISO image. It works in two ways:
+{website}en/downloads/proxmox-virtual-environment/iso
 
-* An ISO image file ready to burn to a CD or DVD.
+It includes the following:
 
-* A raw sector (IMG) image file ready to copy to a USB flash drive (USB stick).
+* Complete operating system (Debian GNU/Linux, 64-bit)
+
+* {pve} Linux kernel with KVM and LXC support
+
+* Complete toolset for administering virtual machines, containers,
+the host system, clusters and all necessary resources
+
+* Web-based management interface
+
+Since the installer ISO is a hybrid image, it can be written directly
+to a USB flash drive (USB stick) or a DVD. Using a USB flash drive is
+the recommended way since it is the faster and more frequently
+available option these days.
 
-Using a USB flash drive to install {pve} is the recommended way because it is
-the faster option.
 
 Prepare a USB Flash Drive as Installation Medium
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The flash drive needs to have at least 1 GB of storage available.
+The flash drive needs to have at least 2 GB of storage space.
 
-NOTE: Do not use UNetbootin. It does not work with the {pve} installation image.
+IMPORTANT: Existing data on the USB flash drive will be overwritten.
+Therefore, make sure that it does not contain any still needed data
+and unmount it afterwards again before proceeding.
 
-IMPORTANT: Make sure that the USB flash drive is not mounted and does not
-contain any important data.
+NOTE: Using 'UNetbootin' may not work with the Proxmox installer ISO.
+Use instead one of the described methods below.
 
 
 Instructions for GNU/Linux
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-On Unix-like operating system use the `dd` command to copy the ISO image to the
-USB flash drive. First find the correct device name of the USB flash drive (see
-below). Then run the `dd` command.
+On Unix-like operating systems, the USB flash drive can usually be
+prepared as follows and requires `root` privileges.
 
-----
-# dd bs=1M conv=fdatasync if=./proxmox-ve_*.iso of=/dev/XYZ
-----
+Find the Correct USB Device Name
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-NOTE: Be sure to replace /dev/XYZ with the correct device name and adapt the
-input filename ('if') path.
+There are two ways to find out the current name (e.g., `sdX`) of the
+USB flash drive. The first one is to compare the last lines of the
+`dmesg` command output before and after plugging in the flash drive.
+The second way is to compare the output of the `lsblk` command:
 
-CAUTION: Be very careful, and do not overwrite the wrong disk!
+Detach the flash drive, then open a terminal and run:
 
+----
+# lsblk
+----
 
-Find the Correct USB Device Name
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-There are two ways to find out the name of the USB flash drive. The first one is
-to compare the last lines of the `dmesg` command output before and after
-plugging in the flash drive. The second way is to compare the output of the
-`lsblk` command. Open a terminal and run:
+Now plug in your USB flash drive and run the command again:
 
 ----
 # lsblk
 ----
 
-Then plug in your USB flash drive and run the command again:
+A new device (e.g., `sdX`) appeared. This is the one you want to use
+in the next step. To be on the extra safe side, check if the reported
+size matches your USB flash drive.
+
+Write Data to USB Device
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+CAUTION: Be especially careful with the `cp` command, as overwriting
+the wrong disk will lead to permanent data loss!
+
+Adapt the two paths, so that the downloaded ISO file is copied to the
+identified whole-disk device (e.g. `sdX`, not a partition like
+`sdX1`).
 
 ----
-# lsblk
+# cp /home/user/Downloads/proxmox-ve_*.iso /dev/sdX
 ----
 
-A new device will appear. This is the one you want to use. To be on the extra
-safe side check if the reported size matches your USB flash drive.
+Finally, run `sync` and wait until the command finished. The USB
+device can now be unplugged.
 
 
 Instructions for macOS
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Open the terminal (query Terminal in Spotlight).
+Open the terminal (query 'Terminal' in Spotlight).
 
 Convert the `.iso` file to `.dmg` format using the convert option of `hdiutil`,
 for example:
@@ -77,31 +100,40 @@ for example:
 # hdiutil convert proxmox-ve_*.iso -format UDRW -o proxmox-ve_*.dmg
 ----
 
-TIP: macOS tends to automatically add '.dmg' to the output file name.
+TIP: macOS tends to automatically add `.dmg` to the output file name.
 
-To get the current list of devices run the command:
+While the USB flash drive is detached, run the following command to
+get the current list of devices:
 
 ----
 # diskutil list
 ----
 
 Now insert the USB flash drive and run this command again to determine which
-device node has been assigned to it. (e.g., /dev/diskX).
+device node has been assigned to it (e.g., /dev/diskX).
 
 ----
 # diskutil list
 # diskutil unmountDisk /dev/diskX
 ----
 
-NOTE: replace X with the disk number from the last command.
+CAUTION: Be especially careful with the next command, as overwriting
+the wrong disk will lead to permanent data loss!
+
+Before writing data to disk with the `dd` command, replace the `X` of
+`rdiskX` with the previously determined disk number.
 
 ----
 # sudo dd if=proxmox-ve_*.dmg bs=1M of=/dev/rdiskX
 ----
 
-NOTE: 'rdiskX', instead of 'diskX', in the last command is intended. It will
+NOTE: Using `rdiskX` instead of `diskX` is intended, as it will
 increase the write speed.
 
+Finally, run `diskutil eject /dev/diskX` so that you can safely unplug
+the USB device.
+
+
 Instructions for Windows
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -116,17 +148,22 @@ Using Rufus
 
 Rufus is a more lightweight alternative, but you need to use the *DD mode* to
 make it work. Download Rufus from https://rufus.ie/. Either install it or use
-the portable version. Select the destination drive and the {pve} ISO file.
+the portable version. Select the destination drive and the downloaded
+{pve} ISO file.
 
-IMPORTANT: Once you 'Start' you have to click 'No' on the dialog asking to
-download a different version of GRUB. In the next dialog select the 'DD' mode.
+IMPORTANT: Once you click 'Start', you have to click 'No' on the
+dialog asking to download a different version of GRUB. In the next
+dialog, select the mode 'DD Image'.
 
-ifdef::wiki[]
-Boot your Server from the USB Flash Drive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Connect the USB flash drive to your server and make sure that booting from USB
-is enabled (check your servers firmware settings). Then follow the steps in the
-xref:chapter_installation[installation wizard].
+ifdef::wiki[]
+Boot from the Installation Medium
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Insert the created USB flash drive (or DVD) into your server and make
+sure that booting from it is enabled in the server's firmware
+settings. Then start using the
+xref:chapter_installation[interactive installer], possible boot
+problems are also described there.
 
 endif::wiki[]
diff --git a/pve-installation.adoc b/pve-installation.adoc
index 223bb71..d320cfc 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -467,7 +467,7 @@ https://www.youtube.com/proxmoxve[{pve} YouTube Channel]
 See Also
 --------
 
-* link:/wiki/Prepare_Installation_Media[Prepare Installation Media]
+* link:/wiki/Prepare_Installation_Media[Prepare Installation Medium]
 
 * link:/wiki/Install_Proxmox_VE_on_Debian_12_Bookworm[Install Proxmox VE on Debian 12 Bookworm]
 
-- 
2.39.5



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH docs 3/7] installation: revise introduction

[Alexander Zeidler]

* Mention all currently available install options and link to them
  (interactive installer, unattended, on top of Debian)
* Remove installer details and link to the installer, where the
  information will be included by a subsequent patch (
  "installer: revise introduction").

Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
 pve-installation.adoc | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/pve-installation.adoc b/pve-installation.adoc
index d320cfc..0065bca 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -8,22 +8,24 @@ ifdef::wiki[]
 :title: Installation
 endif::wiki[]
 
-{pve} is based on Debian. This is why the install disk images (ISO files)
-provided by Proxmox include a complete Debian system as well as all necessary
-{pve} packages.
+Since {pve} is based on Debian GNU/Linux, the installer ISO files
+provided by Proxmox include a complete Debian system as well as all
+necessary {pve} packages.
 
-TIP: See the xref:faq-support-table[support table in the FAQ] for the
-relationship between {pve} releases and Debian releases.
+{pve} can be installed via different methods:
 
-The installer will guide you through the setup, allowing you to partition the
-local disk(s), apply basic system configurations (for example, timezone,
-language, network) and install all required packages. This process should not
-take more than a few minutes. Installing with the provided ISO is the
-recommended method for new and existing users.
+* The recommended method is the creation of an
+xref:installation_prepare_media[installation medium], to boot the
+convenient xref:installation_installer[interactive installer].
 
-Alternatively, {pve} can be installed on top of an existing Debian system. This
-option is only recommended for advanced users because detailed knowledge about
-{pve} is required.
+* As an alternative to the interactive installer, advanced users may
+wish to xref:installation_unattended[install {pve} unattended].
+
+* With sufficient Debian and {pve} knowledge, you can also
+xref:installation_on_debian[install {pve} on top of Debian] manually.
+
+TIP: See the xref:faq-support-table[support table in the FAQ] for the
+relationship between {pve} releases and Debian releases.
 
 ifndef::wiki[]
 
@@ -427,6 +429,8 @@ after a 10-second timeout.
 https://pve.proxmox.com/wiki/Automated_Installation[Visit our wiki] for more
 details and information on the unattended installation.
 
+[[installation_on_debian]]
+
 ifndef::wiki[]
 
 Install {pve} on Debian
-- 
2.39.5



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH docs 4/7] installer: revise introduction

[Alexander Zeidler]

* Describe what the installer does, this was earlier included in the
  installation introduction
* Mention the importance of a redundant disk setup
* s/CD-ROM/DVD/
* Rephrase and expand the boot tip

Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
 pve-installation.adoc | 55 ++++++++++++++++++++++++++-----------------
 1 file changed, 34 insertions(+), 21 deletions(-)

diff --git a/pve-installation.adoc b/pve-installation.adoc
index 0065bca..404d66c 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -40,35 +40,48 @@ endif::wiki[]
 Using the {pve} Installer
 -------------------------
 
-The installer ISO image includes the following:
+The interactive installer guides you through the initial setup
+process. It will help you to partition your disks, apply basic
+settings such as the language, time zone and network configuration,
+and finally install all required packages within minutes.
+
+[IMPORTANT]
+====
+If your server does not yet meet the
+xref:system_requirements[recommended system requirements] in the best
+possible way, most points can also be improved at a later date.
+
+One exception is the installation of the hypervisor, which may not be
+easy to change to a redundant disk setup afterwards. To avoid
+reinstallation or data loss if a disk fails in the future, we
+recommend having two disks available for the OS installation and
+selecting them in the installer for a mirrored RAID level, for
+example, xref:chapter_zfs[ZFS RAID1].
+====
+
+CAUTION: Any existing data on the selected drives will be overwritten
+during the installation process. The installer does not add boot menu
+entries for other operating systems.
+
+Please insert the
+xref:installation_prepare_media[prepared installation medium] (for
+example, USB flash drive or DVD) and boot from it.
+
+TIP: You may need to go into your server's firmware settings, to
+enable booting from your installation medium (for example, USB) and
+set the desired boot order. When booting an installer prior to {pve}
+8.1, 'Secure Boot' needs to be disabled.
 
-* Complete operating system (Debian Linux, 64-bit)
-
-* The {pve} installer, which partitions the local disk(s) with ext4, XFS,
-  BTRFS (technology preview), or ZFS and installs the operating system
-
-* {pve} Linux kernel with KVM and LXC support
+[thumbnail="screenshot/pve-grub-menu.png"]
 
-* Complete toolset for administering virtual machines, containers, the host
-  system, clusters and all necessary resources
+After choosing the correct entry (for example, 'Boot from USB') the {pve} menu
+will be displayed.
 
-* Web-based management interface
 
-NOTE: All existing data on the selected drives will be removed during the
-installation process. The installer does not add boot menu entries for other
-operating systems.
 
-Please insert the xref:installation_prepare_media[prepared installation media]
-(for example, USB flash drive or CD-ROM) and boot from it.
 
-TIP: Make sure that booting from the installation medium (for example, USB) is
-enabled in your server's firmware settings. Secure boot needs to be disabled
-when booting an installer prior to {pve} version 8.1.
 
-[thumbnail="screenshot/pve-grub-menu.png"]
 
-After choosing the correct entry (for example, 'Boot from USB') the {pve} menu
-will be displayed, and one of the following options can be selected:
 
 Install {pve} (Graphical)::
 
-- 
2.39.5



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH docs 5/7] installer: revise boot menu description and introduce sections

[Alexander Zeidler]

* Introduce sections and subsections to enable proper readability
* Move existing information up to the introduction and rephrase it where
  appropriate
* Move the TUI screenshot so that it is placed next to both TUI modes

Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
 pve-installation.adoc | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/pve-installation.adoc b/pve-installation.adoc
index 404d66c..3dee709 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -72,27 +72,40 @@ enable booting from your installation medium (for example, USB) and
 set the desired boot order. When booting an installer prior to {pve}
 8.1, 'Secure Boot' needs to be disabled.
 
-[thumbnail="screenshot/pve-grub-menu.png"]
-
 After choosing the correct entry (for example, 'Boot from USB') the {pve} menu
 will be displayed.
 
 
+{pve} Boot Menu
+~~~~~~~~~~~~~~~
+[thumbnail="screenshot/pve-grub-menu.png"]
 
+There are various boot options available. For a normal installation,
+usually select *Install {pve} (Graphical)*.
 
+The graphical and terminal modes use the same code base for the actual
+installation process to benefit from more than a decade of bug fixes
+and ensure feature parity.
 
+TIP: The 'Terminal UI' options can be used if the 'Graphical'
+installer does not work correctly, e.g., due to driver issues. See
+also xref:nomodeset_kernel_param[adding the `nomodeset` kernel parameter].
 
+Interactive Installation
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Install {pve} (Graphical)::
 
-Starts the normal installation.
+Starts the normal installation. If there are any problems, try one of
+the other options instead.
 
 TIP: It's possible to use the installation wizard with a keyboard only. Buttons
 can be clicked by pressing the `ALT` key combined with the underlined character
 from the respective button. For example, `ALT + N` to press a `Next` button.
 
 Install {pve} (Terminal UI)::
-
++
+[thumbnail="screenshot/pve-tui-installer.png"]
 Starts the terminal-mode installation wizard. It provides the same overall
 installation experience as the graphical installer, but has generally better
 compatibility with very old and very new hardware.
@@ -104,15 +117,6 @@ kernel to use the (first) serial port of the machine for in- and output. This
 can be used if the machine is completely headless and only has a serial console
 available.
 
-[thumbnail="screenshot/pve-tui-installer.png"]
-
-Both modes use the same code base for the actual installation process to
-benefit from more than a decade of bug fixes and ensure feature parity.
-
-TIP: The 'Terminal UI' option can be used in case the graphical installer does
-not work correctly, due to e.g. driver issues. See also
-xref:nomodeset_kernel_param[adding the `nomodeset` kernel parameter].
-
 Advanced Options: Install {pve} (Graphical, Debug Mode)::
 
 Starts the installation in debug mode. A console will be opened at several
@@ -132,6 +136,9 @@ Advanced Options: Install {pve} (Serial Console Debug Mode)::
 Same the terminal-based debug mode, but additionally sets up the Linux kernel to
 use the (first) serial port of the machine for in- and output.
 
+Automated Installation
+^^^^^^^^^^^^^^^^^^^^^^
+
 Advanced Options: Install {pve} (Automated)::
 
 Starts the installer in unattended mode, even if the ISO has not been
@@ -140,6 +147,9 @@ gather hardware details or might be useful to debug an automated installation
 setup. See xref:installation_unattended[Unattended Installation] for more
 information.
 
+Other Options
+^^^^^^^^^^^^^
+
 Advanced Options: Rescue Boot::
 
 With this option you can boot an existing installation. It searches all attached
@@ -154,7 +164,6 @@ Runs `memtest86+`. This is useful to check if the memory is functional and free
 of errors. Secure Boot must be turned off in the UEFI firmware setup utility to
 run this option.
 
-You normally select *Install {pve} (Graphical)* to start the installation.
 
 [thumbnail="screenshot/pve-select-target-disk.png"]
 
-- 
2.39.5



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

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

[Alexander Zeidler]

* 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,
+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.
 
-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.
++
+When deciding on ZFS, please note the
+xref:zfs_performance_tips[performance tips].
++
+The **Advanced Options** for ZFS are decribed
+xref:advanced_zfs_options[here] and for BTRFS
+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.
+
+- 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:
 
 - 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
 ~~~~~~~~~~~~~~~~~~~~
 
-- 
2.39.5



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH docs 7/7] installer: revise intro of advanced ZFS/BTRFS configuration options

[Alexander Zeidler]

* ZFS: Restructure the sentence.
* BTRFS: Explain the swap configuration options in a little more detail.

Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
 pve-installation.adoc | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/pve-installation.adoc b/pve-installation.adoc
index 3b3dc5d..1c143e2 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -362,9 +362,9 @@ web interface for further configuration.
 Advanced LVM Configuration Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The installer creates a Volume Group (VG) called `pve`, and additional Logical
-Volumes (LVs) called `root`, `data`, and `swap`, if `ext4` or `xfs` is used. To
-control the size of these volumes use:
+If `ext4` or `xfs` is used, the installer creates a Volume Group (VG)
+called `pve`, and additional Logical Volumes (LVs) called `root`,
+`data`, and `swap`. To control the size of these volumes, use:
 
 `hdsize`::
 
@@ -455,10 +455,11 @@ first disk or mirror for RAID0, RAID1 or RAID10, and all disks in RAID-Z[123].
 Advanced BTRFS Configuration Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-No swap space is created when BTRFS is used but you can reserve some
-unpartitioned space on the install disks for swap. You can either create a
-separate partition, BTRFS subvolume or a swapfile using the `btrfs filesystem
-mkswapfile` command.
+While no swap space is created when BTRFS is used, you can reserve
+some unpartitioned space on the install disks to manually create a
+separate partition for swap later. A swapfile can also be created on a
+separate BTRFS subvolume by using the `btrfs filesystem mkswapfile`
+command.
 
 `compress`::
 
-- 
2.39.5



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH docs 1/7] system-requirements: revise subchapter and provide more details

[Shannon Sterz]

On Tue Mar 4, 2025 at 4:40 PM CET, Alexander Zeidler wrote:
> Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
> ---
>  pve-system-requirements.adoc | 29 ++++++++++++++++++++---------
>  1 file changed, 20 insertions(+), 9 deletions(-)
>
> diff --git a/pve-system-requirements.adoc b/pve-system-requirements.adoc
> index 8a982a8..82d9be5 100644
> --- a/pve-system-requirements.adoc
> +++ b/pve-system-requirements.adoc
> @@ -1,3 +1,4 @@
> +[[system_requirements]]
>  System Requirements
>  -------------------
>  ifdef::wiki[]
> @@ -6,7 +7,8 @@ endif::wiki[]
>
>  We recommend using high quality server hardware, when running {pve} in
>  production. To further decrease the impact of a failed host, you can run {pve} in
> -a cluster with highly available (HA) virtual machines and containers.
> +a cluster with xref:chapter_ha_manager[highly available (HA)] virtual
> +machines and containers.
>
>  {pve} can use local storage (DAS), SAN, NAS, and distributed storage like Ceph
>  RBD. For details see xref:chapter_storage[chapter storage].
> @@ -26,7 +28,9 @@ used in production.
>
>  * Hard drive
>
> -* One network card (NIC)
> +* One network card (NIC), used for fetching system updates and access
> +via xref:chapter_gui[web interface], `ssh` or
> +link:api-viewer/index.html[{pve} API]
>
>
>  [[install_recommended_requirements]]
> @@ -39,15 +43,22 @@ Recommended System Requirements
>    guests. For Ceph and ZFS, additional memory is required; approximately 1GB of
>    memory for every TB of used storage.
>
> -* Fast and redundant storage, best results are achieved with SSDs.
> +* Fast and redundant storage, best results are achieved with SSDs. Do
> +  not use SD cards or USB flash drives, as these have a lower
> +  durability and performance.
>
> -* OS storage: Use a hardware RAID with battery protected write cache (``BBU'')
> -  or non-RAID with ZFS (optional SSD for ZIL).
> +* OS storage:
> +** An HBA with a redundant xref:chapter_zfs[ZFS] RAID level. If not
> +   using fast enterprise SSDs with power-loss protection, optionally

i think this would read better if it said:

If you are not using fast..., you can optionally add one...

> +   add one for use as xref:sysadmin_zfs_add_cache_and_log_dev[SLOG].
> +** Or a hardware RAID controller with battery-backed write cache (BBU)
> +   and not ZFS, as the combination can lead to data loss.

yes, but there are RAID controllers that can be switched to HBA mode,
this would probably make this longer than it'd need to be

>
>  * VM storage:
> -** For local storage, use either a hardware RAID with battery backed write cache
> -  (BBU) or non-RAID for ZFS and Ceph. Neither ZFS nor Ceph are compatible with a
> -  hardware RAID controller.
> +** For local storage, the same recommendations apply as for OS
> +   storage. However, if a hardware RAID controller is used, in
> +   addition to ZFS, xref:chapter_pveceph[Ceph] is also incompatible
> +   with it.

a) this is mention before and b) this would probably read better:

However, using ZFS on top of a hardware RAID controller is not
compatible, unless the controller supports an HBA-mode or similar.

>  ** Shared and distributed storage is possible.
>  ** SSDs with Power-Loss-Protection (PLP) are recommended for good performance.
>    Using consumer SSDs is discouraged.
> @@ -75,7 +86,7 @@ browsers:
>
>  * Firefox, a release from the current year, or the latest Extended Support Release
>  * Chrome, a release from the current year
> -* Microsoft's currently supported version of Edge
> +* Edge, Microsoft's currently supported release

why keep the "Microsoft" here at all, could just be "the currently" or
similar

>  * Safari, a release from the current year
>
>  When accessed from a mobile device, {pve} will show a lightweight, touch-based



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH docs 2/7] installation: prepare medium: revise subchapter

[Shannon Sterz]

On Tue Mar 4, 2025 at 4:40 PM CET, Alexander Zeidler wrote:
> * Consistently use "medium" (singular), as only one is needed for
>   installation (filename "pve-installation-media.adoc" not renamed)
>
> * Revise the introduction:
> ** Remove CD-ROM (too little storage space) but keep DVD
> ** Copy to it the installer attributes from subchapter "Using the {pve}
>    Installer" (will get removed there in a follow-up patch)
> ** Rephrase slightly
>
> * Revise "Prepare a USB Flash Drive as Installation Medium":
> ** Update minimum required flash drive storage space to 2 GB
> ** Mention explicitly that data get overwritten on installation media
> ** Rearrange the two admonitions according their importance and for
> better reading flow
>
> * Revise "Instructions for GNU/Linux":
> ** Rearrange the steps so that they correspond to the actual sequence
> ** Mention the likely required root privilege
> ** Use `cp` instead of `dd`, as it is used in the Debian docs nowadays
> [0], the difference in speed appears to be negligible, and for beginners
> it is also less complex and easier to understand/type
>
> [0] https://www.debian.org/releases/bookworm/amd64/ch04s03.en.html
>
> * Revise "Instructions for macOS", warn about overwriting the wrong disk
> * Slightly rephrase "Instructions for Windows"
> * Revise the wiki-only section "Boot your Server from the USB Flash
>   Drive" and point to possible boot problems
> * Add the `diskutil eject` command to safely unplug the USB device
>
> Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
> ---
>  pve-installation-media.adoc | 127 +++++++++++++++++++++++-------------
>  pve-installation.adoc       |   2 +-
>  2 files changed, 83 insertions(+), 46 deletions(-)
>
> diff --git a/pve-installation-media.adoc b/pve-installation-media.adoc
> index a1c9402..1a18ea6 100644
> --- a/pve-installation-media.adoc
> +++ b/pve-installation-media.adoc
> @@ -1,74 +1,97 @@
>  [[installation_prepare_media]]
> -Prepare Installation Media
> +Prepare Installation Medium
>  --------------------------
>  ifdef::wiki[]
>  :pve-toplevel:
>  endif::wiki[]
>
> -Download the installer ISO image from: {website}en/downloads/proxmox-virtual-environment/iso
> +To boot the recommended interactive installer, start by downloading
> +the latest installer ISO from:
>
> -The {pve} installation media is a hybrid ISO image. It works in two ways:
> +{website}en/downloads/proxmox-virtual-environment/iso
>
> -* An ISO image file ready to burn to a CD or DVD.
> +It includes the following:
>
> -* A raw sector (IMG) image file ready to copy to a USB flash drive (USB stick).
> +* Complete operating system (Debian GNU/Linux, 64-bit)
> +
> +* {pve} Linux kernel with KVM and LXC support
> +
> +* Complete toolset for administering virtual machines, containers,

this should be "administrating", administering is equivalent to
"verabreichen" in German, not "verwalten"

> +the host system, clusters and all necessary resources
> +
> +* Web-based management interface
> +
> +Since the installer ISO is a hybrid image, it can be written directly
> +to a USB flash drive (USB stick) or a DVD. Using a USB flash drive is
> +the recommended way since it is the faster and more frequently

i'd say "more easily available" is the more common phrasing

> +available option these days.
>
> -Using a USB flash drive to install {pve} is the recommended way because it is
> -the faster option.
>
>  Prepare a USB Flash Drive as Installation Medium
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> -The flash drive needs to have at least 1 GB of storage available.
> +The flash drive needs to have at least 2 GB of storage space.
>
> -NOTE: Do not use UNetbootin. It does not work with the {pve} installation image.
> +IMPORTANT: Existing data on the USB flash drive will be overwritten.
> +Therefore, make sure that it does not contain any still needed data

i feel like the original phrasing here was neater, "still needed data"
reads very... German. maybe, "any data that is still needed"

> +and unmount it afterwards again before proceeding.
>
> -IMPORTANT: Make sure that the USB flash drive is not mounted and does not
> -contain any important data.
> +NOTE: Using 'UNetbootin' may not work with the Proxmox installer ISO.
> +Use instead one of the described methods below.

Use one of the methods described below instead.

>
>
>  Instructions for GNU/Linux
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> -On Unix-like operating system use the `dd` command to copy the ISO image to the
> -USB flash drive. First find the correct device name of the USB flash drive (see
> -below). Then run the `dd` command.
> +On Unix-like operating systems, the USB flash drive can usually be
> +prepared as follows and requires `root` privileges.
>
> -----
> -# dd bs=1M conv=fdatasync if=./proxmox-ve_*.iso of=/dev/XYZ
> -----
> +Find the Correct USB Device Name
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> -NOTE: Be sure to replace /dev/XYZ with the correct device name and adapt the
> -input filename ('if') path.
> +There are two ways to find out the current name (e.g., `sdX`) of the
> +USB flash drive. The first one is to compare the last lines of the
> +`dmesg` command output before and after plugging in the flash drive.
> +The second way is to compare the output of the `lsblk` command:
>
> -CAUTION: Be very careful, and do not overwrite the wrong disk!
> +Detach the flash drive, then open a terminal and run:
>
> +----
> +# lsblk
> +----
>
> -Find the Correct USB Device Name
> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> -There are two ways to find out the name of the USB flash drive. The first one is
> -to compare the last lines of the `dmesg` command output before and after
> -plugging in the flash drive. The second way is to compare the output of the
> -`lsblk` command. Open a terminal and run:
> +Now plug in your USB flash drive and run the command again:
>
>  ----
>  # lsblk
>  ----
>
> -Then plug in your USB flash drive and run the command again:
> +A new device (e.g., `sdX`) appeared. This is the one you want to use
> +in the next step. To be on the extra safe side, check if the reported
> +size matches your USB flash drive.
> +
> +Write Data to USB Device
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +CAUTION: Be especially careful with the `cp` command, as overwriting
> +the wrong disk will lead to permanent data loss!
> +
> +Adapt the two paths, so that the downloaded ISO file is copied to the
> +identified whole-disk device (e.g. `sdX`, not a partition like
> +`sdX1`).
>
>  ----
> -# lsblk
> +# cp /home/user/Downloads/proxmox-ve_*.iso /dev/sdX
>  ----
>
> -A new device will appear. This is the one you want to use. To be on the extra
> -safe side check if the reported size matches your USB flash drive.
> +Finally, run `sync` and wait until the command finished. The USB
> +device can now be unplugged.

hm is this really preferable to the `dd` command?

>
>
>  Instructions for macOS
>  ~~~~~~~~~~~~~~~~~~~~~~
>
> -Open the terminal (query Terminal in Spotlight).
> +Open the terminal (query 'Terminal' in Spotlight).
>
>  Convert the `.iso` file to `.dmg` format using the convert option of `hdiutil`,
>  for example:
> @@ -77,31 +100,40 @@ for example:
>  # hdiutil convert proxmox-ve_*.iso -format UDRW -o proxmox-ve_*.dmg
>  ----
>
> -TIP: macOS tends to automatically add '.dmg' to the output file name.
> +TIP: macOS tends to automatically add `.dmg` to the output file name.
>
> -To get the current list of devices run the command:
> +While the USB flash drive is detached, run the following command to
> +get the current list of devices:
>
>  ----
>  # diskutil list
>  ----
>
>  Now insert the USB flash drive and run this command again to determine which
> -device node has been assigned to it. (e.g., /dev/diskX).
> +device node has been assigned to it (e.g., /dev/diskX).
>
>  ----
>  # diskutil list
>  # diskutil unmountDisk /dev/diskX
>  ----
>
> -NOTE: replace X with the disk number from the last command.
> +CAUTION: Be especially careful with the next command, as overwriting
> +the wrong disk will lead to permanent data loss!
> +
> +Before writing data to disk with the `dd` command, replace the `X` of
> +`rdiskX` with the previously determined disk number.
>
>  ----
>  # sudo dd if=proxmox-ve_*.dmg bs=1M of=/dev/rdiskX
>  ----
>
> -NOTE: 'rdiskX', instead of 'diskX', in the last command is intended. It will
> +NOTE: Using `rdiskX` instead of `diskX` is intended, as it will
>  increase the write speed.
>
> +Finally, run `diskutil eject /dev/diskX` so that you can safely unplug
> +the USB device.
> +
> +
>  Instructions for Windows
>  ~~~~~~~~~~~~~~~~~~~~~~~~
>
> @@ -116,17 +148,22 @@ Using Rufus
>
>  Rufus is a more lightweight alternative, but you need to use the *DD mode* to
>  make it work. Download Rufus from https://rufus.ie/. Either install it or use
> -the portable version. Select the destination drive and the {pve} ISO file.
> +the portable version. Select the destination drive and the downloaded
> +{pve} ISO file.
>
> -IMPORTANT: Once you 'Start' you have to click 'No' on the dialog asking to
> -download a different version of GRUB. In the next dialog select the 'DD' mode.
> +IMPORTANT: Once you click 'Start', you have to click 'No' on the
> +dialog asking to download a different version of GRUB. In the next
> +dialog, select the mode 'DD Image'.
>
> -ifdef::wiki[]
> -Boot your Server from the USB Flash Drive
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> -Connect the USB flash drive to your server and make sure that booting from USB
> -is enabled (check your servers firmware settings). Then follow the steps in the
> -xref:chapter_installation[installation wizard].
> +ifdef::wiki[]
> +Boot from the Installation Medium
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Insert the created USB flash drive (or DVD) into your server and make
> +sure that booting from it is enabled in the server's firmware
> +settings. Then start using the
> +xref:chapter_installation[interactive installer], possible boot
> +problems are also described there.
>
>  endif::wiki[]
> diff --git a/pve-installation.adoc b/pve-installation.adoc
> index 223bb71..d320cfc 100644
> --- a/pve-installation.adoc
> +++ b/pve-installation.adoc
> @@ -467,7 +467,7 @@ https://www.youtube.com/proxmoxve[{pve} YouTube Channel]
>  See Also
>  --------
>
> -* link:/wiki/Prepare_Installation_Media[Prepare Installation Media]
> +* link:/wiki/Prepare_Installation_Media[Prepare Installation Medium]
>
>  * link:/wiki/Install_Proxmox_VE_on_Debian_12_Bookworm[Install Proxmox VE on Debian 12 Bookworm]
>



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH docs 3/7] installation: revise introduction

[Shannon Sterz]

On Tue Mar 4, 2025 at 4:40 PM CET, Alexander Zeidler wrote:
> * Mention all currently available install options and link to them
>   (interactive installer, unattended, on top of Debian)
> * Remove installer details and link to the installer, where the
>   information will be included by a subsequent patch (
>   "installer: revise introduction").
>
> Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
> ---
>  pve-installation.adoc | 30 +++++++++++++++++-------------
>  1 file changed, 17 insertions(+), 13 deletions(-)
>
> diff --git a/pve-installation.adoc b/pve-installation.adoc
> index d320cfc..0065bca 100644
> --- a/pve-installation.adoc
> +++ b/pve-installation.adoc
> @@ -8,22 +8,24 @@ ifdef::wiki[]
>  :title: Installation
>  endif::wiki[]
>
> -{pve} is based on Debian. This is why the install disk images (ISO files)
> -provided by Proxmox include a complete Debian system as well as all necessary
> -{pve} packages.
> +Since {pve} is based on Debian GNU/Linux, the installer ISO files
> +provided by Proxmox include a complete Debian system as well as all
> +necessary {pve} packages.
>
> -TIP: See the xref:faq-support-table[support table in the FAQ] for the
> -relationship between {pve} releases and Debian releases.
> +{pve} can be installed via different methods:
>
> -The installer will guide you through the setup, allowing you to partition the
> -local disk(s), apply basic system configurations (for example, timezone,
> -language, network) and install all required packages. This process should not
> -take more than a few minutes. Installing with the provided ISO is the
> -recommended method for new and existing users.
> +* The recommended method is the creation of an

The recommended method is to create an..

would sound a bit less "biblical" to me ;)

> +xref:installation_prepare_media[installation medium], to boot the
> +convenient xref:installation_installer[interactive installer].
>
> -Alternatively, {pve} can be installed on top of an existing Debian system. This
> -option is only recommended for advanced users because detailed knowledge about
> -{pve} is required.
> +* As an alternative to the interactive installer, advanced users may
> +wish to xref:installation_unattended[install {pve} unattended].
> +
> +* With sufficient Debian and {pve} knowledge, you can also
> +xref:installation_on_debian[install {pve} on top of Debian] manually.
> +
> +TIP: See the xref:faq-support-table[support table in the FAQ] for the
> +relationship between {pve} releases and Debian releases.
>
>  ifndef::wiki[]
>
> @@ -427,6 +429,8 @@ after a 10-second timeout.
>  https://pve.proxmox.com/wiki/Automated_Installation[Visit our wiki] for more
>  details and information on the unattended installation.
>
> +[[installation_on_debian]]
> +
>  ifndef::wiki[]
>
>  Install {pve} on Debian



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH docs 4/7] installer: revise introduction

[Shannon Sterz]

On Tue Mar 4, 2025 at 4:40 PM CET, Alexander Zeidler wrote:
> * Describe what the installer does, this was earlier included in the
>   installation introduction
> * Mention the importance of a redundant disk setup
> * s/CD-ROM/DVD/
> * Rephrase and expand the boot tip
>
> Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
> ---
>  pve-installation.adoc | 55 ++++++++++++++++++++++++++-----------------
>  1 file changed, 34 insertions(+), 21 deletions(-)
>
> diff --git a/pve-installation.adoc b/pve-installation.adoc
> index 0065bca..404d66c 100644
> --- a/pve-installation.adoc
> +++ b/pve-installation.adoc
> @@ -40,35 +40,48 @@ endif::wiki[]
>  Using the {pve} Installer
>  -------------------------
>
> -The installer ISO image includes the following:
> +The interactive installer guides you through the initial setup
> +process. It will help you to partition your disks, apply basic

you can lose the "to" here, "It will help you partition your disks" is
more concise

> +settings such as the language, time zone and network configuration,
> +and finally install all required packages within minutes.
> +
> +[IMPORTANT]
> +====
> +If your server does not yet meet the
> +xref:system_requirements[recommended system requirements] in the best
> +possible way, most points can also be improved at a later date.
> +
> +One exception is the installation of the hypervisor, which may not be
> +easy to change to a redundant disk setup afterwards. To avoid
> +reinstallation or data loss if a disk fails in the future, we
> +recommend having two disks available for the OS installation and

this should probably be split into two sentences "...for the OS
installation. Then make sure to select them in..."

> +selecting them in the installer for a mirrored RAID level, for
> +example, xref:chapter_zfs[ZFS RAID1].
> +====
> +
> +CAUTION: Any existing data on the selected drives will be overwritten
> +during the installation process. The installer does not add boot menu
> +entries for other operating systems.
> +
> +Please insert the
> +xref:installation_prepare_media[prepared installation medium] (for
> +example, USB flash drive or DVD) and boot from it.
> +
> +TIP: You may need to go into your server's firmware settings, to
> +enable booting from your installation medium (for example, USB) and
> +set the desired boot order. When booting an installer prior to {pve}
> +8.1, 'Secure Boot' needs to be disabled.
>
> -* Complete operating system (Debian Linux, 64-bit)
> -
> -* The {pve} installer, which partitions the local disk(s) with ext4, XFS,
> -  BTRFS (technology preview), or ZFS and installs the operating system
> -
> -* {pve} Linux kernel with KVM and LXC support
> +[thumbnail="screenshot/pve-grub-menu.png"]
>
> -* Complete toolset for administering virtual machines, containers, the host
> -  system, clusters and all necessary resources
> +After choosing the correct entry (for example, 'Boot from USB') the {pve} menu
> +will be displayed.

the installer's GRUB boot menu will be displayed.

or something like that would be more descriptive to me than "the Proxmox
VE menu". not sure what that would be if there wasn't a screenshot here
(which may be relevant to users that can't look at it, such as blind
people).

>
> -* Web-based management interface
>
> -NOTE: All existing data on the selected drives will be removed during the
> -installation process. The installer does not add boot menu entries for other
> -operating systems.
>
> -Please insert the xref:installation_prepare_media[prepared installation media]
> -(for example, USB flash drive or CD-ROM) and boot from it.
>
> -TIP: Make sure that booting from the installation medium (for example, USB) is
> -enabled in your server's firmware settings. Secure boot needs to be disabled
> -when booting an installer prior to {pve} version 8.1.
>
> -[thumbnail="screenshot/pve-grub-menu.png"]
>
> -After choosing the correct entry (for example, 'Boot from USB') the {pve} menu
> -will be displayed, and one of the following options can be selected:
>
>  Install {pve} (Graphical)::
>



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [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@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

Re: [pve-devel] [PATCH docs 7/7] installer: revise intro of advanced ZFS/BTRFS configuration options

[Shannon Sterz]

On Tue Mar 4, 2025 at 4:41 PM CET, Alexander Zeidler wrote:
> * ZFS: Restructure the sentence.

should this be XFS? you restructure a sentence about XFS/ext4 below, but
not ZFS

> * BTRFS: Explain the swap configuration options in a little more detail.
>
> Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
> ---
>  pve-installation.adoc | 15 ++++++++-------
>  1 file changed, 8 insertions(+), 7 deletions(-)
>
> diff --git a/pve-installation.adoc b/pve-installation.adoc
> index 3b3dc5d..1c143e2 100644
> --- a/pve-installation.adoc
> +++ b/pve-installation.adoc
> @@ -362,9 +362,9 @@ web interface for further configuration.
>  Advanced LVM Configuration Options
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> -The installer creates a Volume Group (VG) called `pve`, and additional Logical
> -Volumes (LVs) called `root`, `data`, and `swap`, if `ext4` or `xfs` is used. To
> -control the size of these volumes use:
> +If `ext4` or `xfs` is used, the installer creates a Volume Group (VG)
> +called `pve`, and additional Logical Volumes (LVs) called `root`,
> +`data`, and `swap`. To control the size of these volumes, use:
>
>  `hdsize`::
>
> @@ -455,10 +455,11 @@ first disk or mirror for RAID0, RAID1 or RAID10, and all disks in RAID-Z[123].
>  Advanced BTRFS Configuration Options
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> -No swap space is created when BTRFS is used but you can reserve some
> -unpartitioned space on the install disks for swap. You can either create a
> -separate partition, BTRFS subvolume or a swapfile using the `btrfs filesystem
> -mkswapfile` command.
> +While no swap space is created when BTRFS is used, you can reserve
> +some unpartitioned space on the install disks to manually create a
> +separate partition for swap later. A swapfile can also be created on a
> +separate BTRFS subvolume by using the `btrfs filesystem mkswapfile`
> +command.
>
>  `compress`::
>



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel