[pve-devel] [PATCH docs v2 0/5] installation and system improvements

[pve-devel] [PATCH docs v2 0/5] installation and system improvements

[Christoph Heiss]

This mainly updates the installation section, to bring it up-to-date
with the latest available installer ISO.

v1: https://lists.proxmox.com/pipermail/pve-devel/2023-November/060814.html

Changes v1 -> v2:
  * rebased on lastest master
  * dropped two obsolete patches

Christoph Heiss (5):
  screenshots: update grub menu screenshot
  installation: update installer option wording & description
  installation: add note about memtest86+ incompatibility with
    secureboot
  installation: add section about booting with `nomodeset`
  tree-wide: unify spelling of GRUB and systemd-boot

 images/screenshot/pve-grub-menu.png | Bin 66997 -> 66784 bytes
 images/screenshot/pve-grub-menu.ppm | Bin 2362384 -> 2359312 bytes
 local-zfs.adoc                      |  23 +++++++--------
 pve-installation.adoc               |  41 ++++++++++++++++++--------
 system-booting.adoc                 |  44 ++++++++++++++--------------
 5 files changed, 62 insertions(+), 46 deletions(-)

--
2.42.0

[pve-devel] [PATCH docs v2 1/5] screenshots: update grub menu screenshot

[Christoph Heiss]

The 8.1 release changed some things, so update to keep in sync with the
latest ISO.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
Changes v1 -> v2:
  * no changes

Not resending the full patch due to it's size and nothing having changed
since v1. For the original patch, see [0].

[0] https://lists.proxmox.com/pipermail/pve-devel/2023-November/060856.html

 images/screenshot/pve-grub-menu.png | Bin 66997 -> 66784 bytes
 images/screenshot/pve-grub-menu.ppm | Bin 2362384 -> 2359312 bytes
 2 files changed, 0 insertions(+), 0 deletions(-)

diff --git a/images/screenshot/pve-grub-menu.png b/images/screenshot/pve-grub-menu.png
index f3eb10f..c98b54a 100644
Binary files a/images/screenshot/pve-grub-menu.png and b/images/screenshot/pve-grub-menu.png differ
diff --git a/images/screenshot/pve-grub-menu.ppm b/images/screenshot/pve-grub-menu.ppm
index 097ac94..c7c9535 100644
Binary files a/images/screenshot/pve-grub-menu.ppm and b/images/screenshot/pve-grub-menu.ppm differ
--
2.42.0

[pve-devel] [PATCH docs v2 2/5] installation: update installer option wording & description

[Christoph Heiss]

Some things changed with the 8.1 release, so update all the relevant
things here too.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
Changes v1 -> v2:
  * no changes

 pve-installation.adoc | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/pve-installation.adoc b/pve-installation.adoc
index 1e909e2..ccb32be 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -76,7 +76,7 @@ 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} (Console)::
+Install {pve} (Terminal UI)::

 Starts the console-mode installation wizard. It provides the same overall
 installation experience as the graphical installer, but has generally better
@@ -87,10 +87,10 @@ compatibility with very old and very new hardware.
 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 'Console Mode' option can be used in case the graphical installer does
+TIP: The 'Terminal UI' option can be used in case the graphical installer does
 not work correctly, due to e.g. driver issues.

-Advanced Options: Install {pve} (Graphical Debug Mode)::
+Advanced Options: Install {pve} (Graphical, Debug Mode)::

 Starts the installation in debug mode. A console will be opened at several
 installation steps. This helps to debug the situation if something goes wrong.
@@ -99,16 +99,15 @@ system with all basic tools available. You can use it, for example, to
 xref:chapter_zfs[repair a degraded ZFS 'rpool'] or fix the
 xref:sysboot[bootloader] for an existing {pve} setup.

-Advanced Options: Install {pve} (Console Debug Mode)::
+Advanced Options: Install {pve} (Terminal UI, Debug Mode)::

 Same as the graphical debug mode, but preparing the system to run the
-console-mode installer instead.
+terminal-based installer instead.

-Advanced Options: Install {pve} (Console Debug - nomodeset)::
+Advanced Options: Install {pve} (Serial Console Debug Mode)::

-Starts the normal console-mode installation, but prevents the Linux kernel from
-loading any graphics driver. Can be used as a last-resort option, if e.g. an
-incompatible driver is automatically loaded on boot.
+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.

 Advanced Options: Rescue Boot::

--
2.42.0

[pve-devel] [PATCH docs v2 3/5] installation: add note about memtest86+ incompatibility with secureboot

[Christoph Heiss]

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
Changes v1 -> v2:
  * no changes

 pve-installation.adoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/pve-installation.adoc b/pve-installation.adoc
index ccb32be..6e011fa 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -120,7 +120,8 @@ from the disk.
 Advanced Options: Test Memory (memtest86+)::

 Runs `memtest86+`. This is useful to check if the memory is functional and free
-of errors.
+of errors. Secure Boot must be turned off in the UEFI firmware setup utility to
+run this option.

 [thumbnail="screenshot/pve-select-target-disk.png"]

--
2.42.0

[pve-devel] [PATCH docs v2 4/5] installation: add section about booting with `nomodeset`

[Christoph Heiss]

As the grub entry specific to this was removed with the 8.1 release, add
a separate section for this to link users too.

Unfortunaly it is relatively often needed, due to very old or very new
hardware, or when Nvidia cards are installed.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
Changes v1 -> v2:
  * no changes

 pve-installation.adoc | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/pve-installation.adoc b/pve-installation.adoc
index 6e011fa..56b18c8 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -300,6 +300,23 @@ following command:
 # zpool add <pool-name> log </dev/path_to_fast_ssd>
 ----

+Adding the `nomodeset` Kernel Parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Problems may arise on very old or very new hardware due to graphics drivers. If
+the installation hangs during the boot. In that case, you can try adding the
+`nomodeset` parameter. This prevents the Linux kernel from loading any
+graphics drivers and forces it to continue using the BIOS/UEFI-provided
+framebuffer.
+
+On the {pve} bootloader menu, navigate to 'Install {pve} (Terminal UI)' and
+press `e` to edit the entry. Using the arrow keys, navigate to the line starting
+with `linux`, move the cursor to the end of that line and add the
+parameter `nomodeset`, separated by a space from the pre-existing last
+parameter.
+
+Then press `Ctrl-X` or `F10` to boot the configuration.
+
 ifndef::wiki[]

 Install {pve} on Debian
--
2.42.0

[pve-devel] [PATCH docs v2 5/5] tree-wide: unify spelling of GRUB and systemd-boot

[Christoph Heiss]

Especially for GRUB there were a myriad of different casing variants
(e.g. grub, Grub, GRUB), so unify them, with GRUB being the official
casing.

For systemd-boot, fix an instance where it was not typeset as
monospace, like everywhere else.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
Changes v1 -> v2:
  * rebased to include new occurences

 local-zfs.adoc        | 23 +++++++++++-----------
 pve-installation.adoc |  4 ++--
 system-booting.adoc   | 44 +++++++++++++++++++++----------------------
 3 files changed, 35 insertions(+), 36 deletions(-)

diff --git a/local-zfs.adoc b/local-zfs.adoc
index 58726a7..a1a14e4 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -497,10 +497,9 @@ Changing a failed device

 .Changing a failed bootable device

-Depending on how {pve} was installed it is either using `systemd-boot` or `grub`
-through `proxmox-boot-tool`
-footnote:[Systems installed with {pve} 6.4 or later, EFI systems installed with
-{pve} 5.4 or later] or plain `grub` as bootloader (see
+Depending on how {pve} was installed it is either using `systemd-boot` or GRUB
+through `proxmox-boot-tool` footnote:[Systems installed with {pve} 6.4 or later,
+EFI systems installed with {pve} 5.4 or later] or plain GRUB as bootloader (see
 xref:sysboot[Host Bootloader]). You can check by running:

 ----
@@ -531,16 +530,16 @@ NOTE: `ESP` stands for EFI System Partition, which is setup as partition #2 on
 bootable disks setup by the {pve} installer since version 5.4. For details, see
 xref:sysboot_proxmox_boot_setup[Setting up a new partition for use as synced ESP].

-NOTE: make sure to pass 'grub' as mode to `proxmox-boot-tool init` if
-`proxmox-boot-tool status` indicates your current disks are using Grub,
+NOTE: Make sure to pass 'grub' as mode to `proxmox-boot-tool init` if
+`proxmox-boot-tool status` indicates your current disks are using GRUB,
 especially if Secure Boot is enabled!

-.With plain `grub`:
+.With plain GRUB:

 ----
 # grub-install <new disk>
 ----
-NOTE: plain `grub` is only used on systems installed with {pve} 6.3 or earlier,
+NOTE: Plain GRUB is only used on systems installed with {pve} 6.3 or earlier,
 which have not been manually migrated to using `proxmox-boot-tool` yet.


@@ -684,7 +683,7 @@ tank  feature@encryption  enabled         local
 ----

 WARNING: There is currently no support for booting from pools with encrypted
-datasets using Grub, and only limited support for automatically unlocking
+datasets using GRUB, and only limited support for automatically unlocking
 encrypted datasets on boot. Older versions of ZFS without encryption support
 will not be able to decrypt stored data.

@@ -854,16 +853,16 @@ them.

 In fact, there are some downsides to enabling new features:

-* A system with root on ZFS, that still boots using `grub` will become
+* A system with root on ZFS, that still boots using GRUB will become
   unbootable if a new feature is active on the rpool, due to the incompatible
-  implementation of ZFS in grub.
+  implementation of ZFS in GRUB.
 * The system will not be able to import any upgraded pool when booted with an
   older kernel, which still ships with the old ZFS modules.
 * Booting an older {pve} ISO to repair a non-booting system will likewise not
   work.

 IMPORTANT: Do *not* upgrade your rpool if your system is still booted with
-`grub`, as this will render your system unbootable. This includes systems
+GRUB, as this will render your system unbootable. This includes systems
 installed before {pve} 5.4, and systems booting with legacy BIOS boot (see
 xref:sysboot_determine_bootloader_used[how to determine the bootloader]).

diff --git a/pve-installation.adoc b/pve-installation.adoc
index 56b18c8..6b44fc0 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -114,8 +114,8 @@ Advanced Options: Rescue Boot::
 With this option you can boot an existing installation. It searches all attached
 hard disks. If it finds an existing installation, it boots directly into that
 disk using the Linux kernel from the ISO. This can be useful if there are
-problems with the boot block (grub) or the BIOS is unable to read the boot block
-from the disk.
+problems with the bootloader (GRUB/`systemd-boot`) or the BIOS/UEFI is unable to
+read the boot block from the disk.

 Advanced Options: Test Memory (memtest86+)::

diff --git a/system-booting.adoc b/system-booting.adoc
index af56225..9603fc0 100644
--- a/system-booting.adoc
+++ b/system-booting.adoc
@@ -10,7 +10,7 @@ selected in the installer.

 For EFI Systems installed with ZFS as the root filesystem `systemd-boot` is
 used, unless Secure Boot is enabled. All other deployments use the standard
-`grub` bootloader (this usually also applies to systems which are installed on
+GRUB bootloader (this usually also applies to systems which are installed on
 top of Debian).


@@ -32,12 +32,12 @@ The created partitions are:

 Systems using ZFS as root filesystem are booted with a kernel and initrd image
 stored on the 512 MB EFI System Partition. For legacy BIOS systems, and EFI
-systems with Secure Boot enabled, `grub` is used, for EFI systems without
+systems with Secure Boot enabled, GRUB is used, for EFI systems without
 Secure Boot, `systemd-boot` is used. Both are installed and configured to point
 to the ESPs.

-`grub` in BIOS mode (`--target i386-pc`) is installed onto the BIOS Boot
-Partition of all selected disks on all systems booted with `grub`
+GRUB in BIOS mode (`--target i386-pc`) is installed onto the BIOS Boot
+Partition of all selected disks on all systems booted with GRUB
 footnote:[These are all installs with root on `ext4` or `xfs` and installs
 with root on ZFS on non-EFI systems].

@@ -51,8 +51,8 @@ Partitions properly configured and synchronized. It copies certain kernel
 versions to all ESPs and configures the respective bootloader to boot from
 the `vfat` formatted ESPs. In the context of ZFS as root filesystem this means
 that you can use all optional features on your root pool instead of the subset
-which is also present in the ZFS implementation in `grub` or having to create a
-separate small boot-pool footnote:[Booting ZFS on root with grub
+which is also present in the ZFS implementation in GRUB or having to create a
+separate small boot-pool footnote:[Booting ZFS on root with GRUB
 https://github.com/zfsonlinux/zfs/wiki/Debian-Stretch-Root-on-ZFS].

 In setups with redundancy all disks are partitioned with an ESP, by the
@@ -108,7 +108,7 @@ or
 # proxmox-boot-tool init /dev/sda2 grub
 ----

-to force initialization with Grub instead of systemd-boot, for example for
+to force initialization with GRUB instead of `systemd-boot`, for example for
 Secure Boot support.

 Afterwards `/etc/kernel/proxmox-boot-uuids` should contain a new line with the
@@ -186,7 +186,7 @@ Determine which Bootloader is Used
 The simplest and most reliable way to determine which bootloader is used, is to
 watch the boot process of the {pve} node.

-You will either see the blue box of `grub` or the simple black on white
+You will either see the blue box of GRUB or the simple black on white
 `systemd-boot`.

 [thumbnail="screenshot/boot-systemdboot.png"]
@@ -199,10 +199,10 @@ safest way is to run the following command:
 # efibootmgr -v
 ----

-If it returns a message that EFI variables are not supported, `grub` is used in
+If it returns a message that EFI variables are not supported, GRUB is used in
 BIOS/Legacy mode.

-If the output contains a line that looks similar to the following, `grub` is
+If the output contains a line that looks similar to the following, GRUB is
 used in UEFI mode.

 ----
@@ -226,16 +226,16 @@ indication of how the system is booted.


 [[sysboot_grub]]
-Grub
+GRUB
 ~~~~

-`grub` has been the de-facto standard for booting Linux systems for many years
+GRUB has been the de-facto standard for booting Linux systems for many years
 and is quite well documented
-footnote:[Grub Manual https://www.gnu.org/software/grub/manual/grub/grub.html].
+footnote:[GRUB Manual https://www.gnu.org/software/grub/manual/grub/grub.html].

 Configuration
 ^^^^^^^^^^^^^
-Changes to the `grub` configuration are done via the defaults file
+Changes to the GRUB configuration are done via the defaults file
 `/etc/default/grub` or config snippets in `/etc/default/grub.d`. To regenerate
 the configuration file after a change to the configuration run:
 footnote:[Systems using `proxmox-boot-tool` will call `proxmox-boot-tool
@@ -286,7 +286,7 @@ Editing the Kernel Commandline
 You can modify the kernel commandline in the following places, depending on the
 bootloader used:

-.Grub
+.GRUB

 The kernel commandline needs to be placed in the variable
 `GRUB_CMDLINE_LINUX_DEFAULT` in the file `/etc/default/grub`. Running
@@ -383,10 +383,10 @@ The following packages need to be installed for Secure Boot to be enabled:
 - `shim-signed` (shim bootloader signed by Microsoft)
 - `shim-helpers-amd64-signed` (fallback bootloader and MOKManager, signed by
   Proxmox)
-- `grub-efi-amd64-signed` (Grub EFI bootloader, signed by Proxmox)
+- `grub-efi-amd64-signed` (GRUB EFI bootloader, signed by Proxmox)
 - `proxmox-kernel-6.X.Y-Z-pve-signed` (Kernel image, signed by Proxmox)

-Only Grub as bootloader is supported out of the box, since there are no other
+Only GRUB as bootloader is supported out of the box, since there are no other
 pre-signed bootloader packages available. Any new installation of {pve} will
 automatically have all of the above packages included.

@@ -405,7 +405,7 @@ An existing UEFI installation can be switched over to Secure Boot if desired,
 without having to reinstall {pve} from scratch.

 First, ensure all your system is up-to-date. Next, install all the required
-pre-signed packages as listed above. Grub automatically creates the needed EFI
+pre-signed packages as listed above. GRUB automatically creates the needed EFI
 boot entry for booting via the default shim.

 .systemd-boot
@@ -450,7 +450,7 @@ In this case, the partitions `sda2` and `sdb2` are the targets. They can be
 identified by the their size of 512M and their `FSTYPE` being `vfat`, in this
 case on a ZFS RAID-1 installation.

-These partitions must be properly set up for booting through Grub using
+These partitions must be properly set up for booting through GRUB using
 `proxmox-boot-tool`. This command (using `sda2` as an example) must be run
 separately for each individual ESP:
 ----
@@ -469,8 +469,8 @@ Boot0009* proxmox       HD(2,GPT,..,0x800,0x100000)/File(\EFI\proxmox\shimx64.ef
 [..]
 ----

-NOTE: The old `systemd-boot` bootloader will be kept, but Grub will be
-preferred. This way, if booting using Grub in Secure Boot mode does not work for
+NOTE: The old `systemd-boot` bootloader will be kept, but GRUB will be
+preferred. This way, if booting using GRUB in Secure Boot mode does not work for
 any reason, the system can still be booted using `systemd-boot` with Secure Boot
 turned off.

@@ -485,7 +485,7 @@ can try adding it manually (if supported by the firmware), by adding the file
 `\EFI\proxmox\shimx64.efi` as a custom boot entry.

 NOTE: Some UEFI firmwares are known to drop the `proxmox` boot option on reboot.
-This can happen if the `proxmox` boot entry is pointing to a Grub installation
+This can happen if the `proxmox` boot entry is pointing to a GRUB installation
 on a disk, where the disk itself is not a boot option. If possible, try adding
 the disk as a boot option in the UEFI firmware setup utility and run
 `proxmox-boot-tool` again.
--
2.42.0

[pve-devel] applied-series: [PATCH docs v2 0/5] installation and system improvements

[Thomas Lamprecht]

Am 25/01/2024 um 12:06 schrieb Christoph Heiss:
> This mainly updates the installation section, to bring it up-to-date
> with the latest available installer ISO.
> 
> v1: https://lists.proxmox.com/pipermail/pve-devel/2023-November/060814.html
> 
> Changes v1 -> v2:
>   * rebased on lastest master
>   * dropped two obsolete patches
> 
> Christoph Heiss (5):
>   screenshots: update grub menu screenshot
>   installation: update installer option wording & description
>   installation: add note about memtest86+ incompatibility with
>     secureboot
>   installation: add section about booting with `nomodeset`
>   tree-wide: unify spelling of GRUB and systemd-boot
> 
>  images/screenshot/pve-grub-menu.png | Bin 66997 -> 66784 bytes
>  images/screenshot/pve-grub-menu.ppm | Bin 2362384 -> 2359312 bytes
>  local-zfs.adoc                      |  23 +++++++--------
>  pve-installation.adoc               |  41 ++++++++++++++++++--------
>  system-booting.adoc                 |  44 ++++++++++++++--------------
>  5 files changed, 62 insertions(+), 46 deletions(-)

applied series with screenshot patch from v1, thanks!