Re: [pve-devel] [PATCH docs 1/2] Add documentation on bootloaders (systemd-boot)
On Mon, 8 Jul 2019 11:09:38 +0200
Aaron Lauterer wrote:
> Some things that I have seen, mostly regarding style and readability.
Thanks big time - incorporated and will be included in my v2
>
> On 7/5/19 6:31 PM, Stoiko Ivanov wrote:
> > With the recently added support for booting ZFS on root on EFI
> > systems via `systemd-boot` the documentation needs adapting (mostly
> > related to editing the kernel commandline).
> >
> > This patch adds a short section on Bootloaders to the sysadmin
> > chapter describing both `grub` and PVE's use of `systemd-boot`
> >
> > Signed-off-by: Stoiko Ivanov
> > ---
> > sysadmin.adoc | 2 +
> > system-booting.adoc | 144
> > 2 files changed, 146
> > insertions(+) create mode 100644 system-booting.adoc
> >
> > diff --git a/sysadmin.adoc b/sysadmin.adoc
> > index 21537f1..e045610 100644
> > --- a/sysadmin.adoc
> > +++ b/sysadmin.adoc
> > @@ -74,6 +74,8 @@ include::local-zfs.adoc[]
> >
> > include::certificate-management.adoc[]
> >
> > +include::system-booting.adoc[]
> > +
> > endif::wiki[]
> >
> >
> > diff --git a/system-booting.adoc b/system-booting.adoc
> > new file mode 100644
> > index 000..389a0e9
> > --- /dev/null
> > +++ b/system-booting.adoc
> > @@ -0,0 +1,144 @@
> > +[[system_booting]]
> > +Bootloaders
> > +---
> > +ifdef::wiki[]
> > +:pve-toplevel:
> > +endif::wiki[]
> > +
> > +Depending on the disk setup chosen in the installer {pve} uses two
> > bootloaders +for bootstrapping the system.
>
> {pve} is using one of two bootloaders, depending on the disk setup
> selected in the installer.
>
> (Putting the most important info at the beginning of the sentence)
>
> > +
> > +For EFI Systems installed with ZFS as the root filesystem
> > `systemd-boot` is +used. All other deployments use the standard
> > `grub` bootloader (this usually +also applies to systems which are
> > installed on top of Debian). +
> > +[[installer_partitioning_scheme]]
> > +Partitioning scheme used by the installer
> > +~
> > +
> > +The {pve} installer creates 3 partitions on disks:
> > +
> > +* a 1M BIOS Boot Partition (gdisk type EF02)
> > +
> > +* a 512M EFI System Partition (ESP, gdisk type EF00)
>
> Besides what Thomas already mentioned; what about using MB (with a
> space) instead of M? "512 MB" instead of "512M"?
> > +
> > +* a third partition spanning the remaining space used for the
> > chosen storage
> > + type
> > +
> > +`grub` in BIOS mode (`--target i386-pc`) is installed onto the
> > BIOS Boot +Partition of all bootable disks for supporting older
> > systems. +
> > +
> > +Grub
> > +
> > +
> > +`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]. +
> > +The kernel and initrd images are taken from `/boot` and its
> > configuration file +`/boot/grub/grub.cfg` gets updated by the
> > kernel installation process. +
> > +Configuration
> > +^
> > +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 `/boot/grub/grub.cfg` after a change to the
> > configuration +run `update-grub`.
> > +
> > +Systemd-boot
> > +
> > +
> > +`systemd-boot` is a lightweight EFI bootloader, which reads the
> > kernel and
>
> "...EFI bootloader. It reads the kernel and "
> Splitting the sentence will produce two shorter sentences that are
> easier to grasp.
>
> > +initrd images directly from the EFI Service Partition (ESP) where
> > it is +installed. The main advantage of directly loading the
> > +kernel from the ESP is that it does not need to reimplement the
> > drivers for +accessing the storage. 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
> > https://github.com/zfsonlinux/zfs/wiki/Debian-Stretch-Root-on-ZFS].
> > + +In setups with redundancy (RAID1, RAID10, RAIDZ*) all bootable
> > disks (those +being part of the first `vdev`) are partitioned with
> > an ESP, ensuring the
>
> "with an ESP. This ensure that the system can boot even..."
>
> > +system boots even if the first boot device fails. The ESPs are
> > kept in sync by +a kernel postinstall hook script
> > `/etc/kernel/postinst.d/zz-pve-efiboot`. The +script copies certain
> > kernel versions and the initrd images to `EFI/proxmox/` +on the
> > root of each ESP and creates the appropriate config files in
> > +`loader/entries/proxmox-*.conf`. +
> > +The following kernel versions are configured by default:
> > +
> > +* the currently booted kernel
> > +* the version being installed
>
Re: [pve-devel] [PATCH docs 1/2] Add documentation on bootloaders (systemd-boot)
Some things that I have seen, mostly regarding style and readability.
On 7/5/19 6:31 PM, Stoiko Ivanov wrote:
With the recently added support for booting ZFS on root on EFI systems via
`systemd-boot` the documentation needs adapting (mostly related to editing
the kernel commandline).
This patch adds a short section on Bootloaders to the sysadmin chapter
describing both `grub` and PVE's use of `systemd-boot`
Signed-off-by: Stoiko Ivanov
---
sysadmin.adoc | 2 +
system-booting.adoc | 144
2 files changed, 146 insertions(+)
create mode 100644 system-booting.adoc
diff --git a/sysadmin.adoc b/sysadmin.adoc
index 21537f1..e045610 100644
--- a/sysadmin.adoc
+++ b/sysadmin.adoc
@@ -74,6 +74,8 @@ include::local-zfs.adoc[]
include::certificate-management.adoc[]
+include::system-booting.adoc[]
+
endif::wiki[]
diff --git a/system-booting.adoc b/system-booting.adoc
new file mode 100644
index 000..389a0e9
--- /dev/null
+++ b/system-booting.adoc
@@ -0,0 +1,144 @@
+[[system_booting]]
+Bootloaders
+---
+ifdef::wiki[]
+:pve-toplevel:
+endif::wiki[]
+
+Depending on the disk setup chosen in the installer {pve} uses two bootloaders
+for bootstrapping the system.
{pve} is using one of two bootloaders, depending on the disk setup
selected in the installer.
(Putting the most important info at the beginning of the sentence)
+
+For EFI Systems installed with ZFS as the root filesystem `systemd-boot` is
+used. All other deployments use the standard `grub` bootloader (this usually
+also applies to systems which are installed on top of Debian).
+
+[[installer_partitioning_scheme]]
+Partitioning scheme used by the installer
+~
+
+The {pve} installer creates 3 partitions on disks:
+
+* a 1M BIOS Boot Partition (gdisk type EF02)
+
+* a 512M EFI System Partition (ESP, gdisk type EF00)
Besides what Thomas already mentioned; what about using MB (with a
space) instead of M? "512 MB" instead of "512M"?
+
+* a third partition spanning the remaining space used for the chosen storage
+ type
+
+`grub` in BIOS mode (`--target i386-pc`) is installed onto the BIOS Boot
+Partition of all bootable disks for supporting older systems.
+
+
+Grub
+
+
+`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].
+
+The kernel and initrd images are taken from `/boot` and its configuration file
+`/boot/grub/grub.cfg` gets updated by the kernel installation process.
+
+Configuration
+^
+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 `/boot/grub/grub.cfg` after a change to the configuration
+run `update-grub`.
+
+Systemd-boot
+
+
+`systemd-boot` is a lightweight EFI bootloader, which reads the kernel and
"...EFI bootloader. It reads the kernel and "
Splitting the sentence will produce two shorter sentences that are
easier to grasp.
+initrd images directly from the EFI Service Partition (ESP) where it is
+installed. The main advantage of directly loading the
+kernel from the ESP is that it does not need to reimplement the drivers for
+accessing the storage. 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
https://github.com/zfsonlinux/zfs/wiki/Debian-Stretch-Root-on-ZFS].
+
+In setups with redundancy (RAID1, RAID10, RAIDZ*) all bootable disks (those
+being part of the first `vdev`) are partitioned with an ESP, ensuring the
"with an ESP. This ensure that the system can boot even..."
+system boots even if the first boot device fails. The ESPs are kept in sync by
+a kernel postinstall hook script `/etc/kernel/postinst.d/zz-pve-efiboot`. The
+script copies certain kernel versions and the initrd images to `EFI/proxmox/`
+on the root of each ESP and creates the appropriate config files in
+`loader/entries/proxmox-*.conf`.
+
+The following kernel versions are configured by default:
+
+* the currently booted kernel
+* the version being installed
+* the two latest kernels
+* the latest version of each kernel series (e.g. 4.15, 5.0).
+
+The ESPs are not kept mounted during regular operation, in contrast to `grub`,
+which keeps an ESP mounted on `/boot/efi`. This helps preventing filesystem
"This helps to prevent filesystem..."
+corruption to the `vfat` formatted ESPs in case of a system crash, and removes
+the need to manually adapt `/etc/fstab` in case the primary boot device fails.
+
+[[systemd_boot_config]]
+Configuration
+^
+
+`systemd-boot` itself is configured via the file `loader/loader.conf` in the
Re: [pve-devel] [PATCH docs 1/2] Add documentation on bootloaders (systemd-boot)
On Fri, 5 Jul 2019 19:21:52 +0200 Thomas Lamprecht wrote: > On 7/5/19 6:31 PM, Stoiko Ivanov wrote: > > With the recently added support for booting ZFS on root on EFI > > systems via `systemd-boot` the documentation needs adapting (mostly > > related to editing the kernel commandline). > > > > This patch adds a short section on Bootloaders to the sysadmin > > chapter describing both `grub` and PVE's use of `systemd-boot` > > > > while: > > I would be grateful for feedback if the phrasing makes sense to > > people who did not occupy themselves with the intricasies of > > bootloader recently > > is not fully true with me still some comments inline ;) Thanks - all make sense - all addressed! I'll send a v2 on Monday - maybe some more feedback comes in until then. >..snip.. ___ pve-devel mailing list pve-devel@pve.proxmox.com https://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
Re: [pve-devel] [PATCH docs 1/2] Add documentation on bootloaders (systemd-boot)
On 7/5/19 6:31 PM, Stoiko Ivanov wrote:
> With the recently added support for booting ZFS on root on EFI systems via
> `systemd-boot` the documentation needs adapting (mostly related to editing
> the kernel commandline).
>
> This patch adds a short section on Bootloaders to the sysadmin chapter
> describing both `grub` and PVE's use of `systemd-boot`
>
while:
> I would be grateful for feedback if the phrasing makes sense to people who did
> not occupy themselves with the intricasies of bootloader recently
is not fully true with me still some comments inline ;)
> Signed-off-by: Stoiko Ivanov
> ---
> sysadmin.adoc | 2 +
> system-booting.adoc | 144
> 2 files changed, 146 insertions(+)
> create mode 100644 system-booting.adoc
>
> diff --git a/sysadmin.adoc b/sysadmin.adoc
> index 21537f1..e045610 100644
> --- a/sysadmin.adoc
> +++ b/sysadmin.adoc
> @@ -74,6 +74,8 @@ include::local-zfs.adoc[]
>
> include::certificate-management.adoc[]
>
> +include::system-booting.adoc[]
> +
> endif::wiki[]
>
>
> diff --git a/system-booting.adoc b/system-booting.adoc
> new file mode 100644
> index 000..389a0e9
> --- /dev/null
> +++ b/system-booting.adoc
> @@ -0,0 +1,144 @@
> +[[system_booting]]
> +Bootloaders
> +---
> +ifdef::wiki[]
> +:pve-toplevel:
> +endif::wiki[]
> +
> +Depending on the disk setup chosen in the installer {pve} uses two
> bootloaders
> +for bootstrapping the system.
> +
> +For EFI Systems installed with ZFS as the root filesystem `systemd-boot` is
> +used. All other deployments use the standard `grub` bootloader (this usually
> +also applies to systems which are installed on top of Debian).
> +
> +[[installer_partitioning_scheme]]
> +Partitioning scheme used by the installer
> +~
> +
> +The {pve} installer creates 3 partitions on disks:
> +
> +* a 1M BIOS Boot Partition (gdisk type EF02)
> +
> +* a 512M EFI System Partition (ESP, gdisk type EF00)
phrasing feels a bit like it's meant for really all disks, but it's
* non-zfs: selected disk
* zfs: depends on mode, at least on one device and for each raid1 group and
on every raidz dev, IIRC?
> +
> +* a third partition spanning the remaining space used for the chosen storage
> + type
not always the remaining, $hdsize - which, yes, defaults to the remaining ;)
> +
> +`grub` in BIOS mode (`--target i386-pc`) is installed onto the BIOS Boot
> +Partition of all bootable disks for supporting older systems.
> +
> +
> +Grub
> +
> +
> +`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].
> +
> +The kernel and initrd images are taken from `/boot` and its configuration
> file
> +`/boot/grub/grub.cfg` gets updated by the kernel installation process.
> +
> +Configuration
> +^
> +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 `/boot/grub/grub.cfg` after a change to the configuration
> +run `update-grub`.
maybe put above in a
pre-formatted code section
to highlight it a bit more?
> +
> +Systemd-boot
> +
> +
> +`systemd-boot` is a lightweight EFI bootloader, which reads the kernel and
> +initrd images directly from the EFI Service Partition (ESP) where it is
> +installed. The main advantage of directly loading the
early linebreak above
> +kernel from the ESP is that it does not need to reimplement the drivers for
> +accessing the storage. 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
> https://github.com/zfsonlinux/zfs/wiki/Debian-Stretch-Root-on-ZFS].
> +
> +In setups with redundancy (RAID1, RAID10, RAIDZ*) all bootable disks (those
> +being part of the first `vdev`) are partitioned with an ESP, ensuring the
> +system boots even if the first boot device fails. The ESPs are kept in sync
> by
> +a kernel postinstall hook script `/etc/kernel/postinst.d/zz-pve-efiboot`. The
> +script copies certain kernel versions and the initrd images to `EFI/proxmox/`
> +on the root of each ESP and creates the appropriate config files in
> +`loader/entries/proxmox-*.conf`.
> +
> +The following kernel versions are configured by default:
> +
> +* the currently booted kernel
s/booted/running/ - while it's true and technically OK, we (and pveversion)
always
talks about running kernel.
> +* the version being installed
.. being newly installed on package updates
> +* the two latest kernels
> +* the latest version of each kernel series (e.g. 4.15, 5.0).
> +
> +The ESPs are not kept mounted during regular operation, in contr
[pve-devel] [PATCH docs 1/2] Add documentation on bootloaders (systemd-boot)
With the recently added support for booting ZFS on root on EFI systems via
`systemd-boot` the documentation needs adapting (mostly related to editing
the kernel commandline).
This patch adds a short section on Bootloaders to the sysadmin chapter
describing both `grub` and PVE's use of `systemd-boot`
Signed-off-by: Stoiko Ivanov
---
sysadmin.adoc | 2 +
system-booting.adoc | 144
2 files changed, 146 insertions(+)
create mode 100644 system-booting.adoc
diff --git a/sysadmin.adoc b/sysadmin.adoc
index 21537f1..e045610 100644
--- a/sysadmin.adoc
+++ b/sysadmin.adoc
@@ -74,6 +74,8 @@ include::local-zfs.adoc[]
include::certificate-management.adoc[]
+include::system-booting.adoc[]
+
endif::wiki[]
diff --git a/system-booting.adoc b/system-booting.adoc
new file mode 100644
index 000..389a0e9
--- /dev/null
+++ b/system-booting.adoc
@@ -0,0 +1,144 @@
+[[system_booting]]
+Bootloaders
+---
+ifdef::wiki[]
+:pve-toplevel:
+endif::wiki[]
+
+Depending on the disk setup chosen in the installer {pve} uses two bootloaders
+for bootstrapping the system.
+
+For EFI Systems installed with ZFS as the root filesystem `systemd-boot` is
+used. All other deployments use the standard `grub` bootloader (this usually
+also applies to systems which are installed on top of Debian).
+
+[[installer_partitioning_scheme]]
+Partitioning scheme used by the installer
+~
+
+The {pve} installer creates 3 partitions on disks:
+
+* a 1M BIOS Boot Partition (gdisk type EF02)
+
+* a 512M EFI System Partition (ESP, gdisk type EF00)
+
+* a third partition spanning the remaining space used for the chosen storage
+ type
+
+`grub` in BIOS mode (`--target i386-pc`) is installed onto the BIOS Boot
+Partition of all bootable disks for supporting older systems.
+
+
+Grub
+
+
+`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].
+
+The kernel and initrd images are taken from `/boot` and its configuration file
+`/boot/grub/grub.cfg` gets updated by the kernel installation process.
+
+Configuration
+^
+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 `/boot/grub/grub.cfg` after a change to the configuration
+run `update-grub`.
+
+Systemd-boot
+
+
+`systemd-boot` is a lightweight EFI bootloader, which reads the kernel and
+initrd images directly from the EFI Service Partition (ESP) where it is
+installed. The main advantage of directly loading the
+kernel from the ESP is that it does not need to reimplement the drivers for
+accessing the storage. 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
https://github.com/zfsonlinux/zfs/wiki/Debian-Stretch-Root-on-ZFS].
+
+In setups with redundancy (RAID1, RAID10, RAIDZ*) all bootable disks (those
+being part of the first `vdev`) are partitioned with an ESP, ensuring the
+system boots even if the first boot device fails. The ESPs are kept in sync by
+a kernel postinstall hook script `/etc/kernel/postinst.d/zz-pve-efiboot`. The
+script copies certain kernel versions and the initrd images to `EFI/proxmox/`
+on the root of each ESP and creates the appropriate config files in
+`loader/entries/proxmox-*.conf`.
+
+The following kernel versions are configured by default:
+
+* the currently booted kernel
+* the version being installed
+* the two latest kernels
+* the latest version of each kernel series (e.g. 4.15, 5.0).
+
+The ESPs are not kept mounted during regular operation, in contrast to `grub`,
+which keeps an ESP mounted on `/boot/efi`. This helps preventing filesystem
+corruption to the `vfat` formatted ESPs in case of a system crash, and removes
+the need to manually adapt `/etc/fstab` in case the primary boot device fails.
+
+[[systemd_boot_config]]
+Configuration
+^
+
+`systemd-boot` itself is configured via the file `loader/loader.conf` in the
+root directory of an ESP. See the `loader.conf(5)` manpage for details.
+
+Each bootloader entry is placed in a file of its own in the directory
+`loader/entries/`
+
+An example entry.conf looks like this (`/` refers to the root of the ESP):
+
+
+titleProxmox
+version 5.0.15-1-pve
+options root=ZFS=rpool/ROOT/pve-1 boot=zfs
+linux/EFI/proxmox/5.0.15-1-pve/vmlinuz-5.0.15-1-pve
+initrd /EFI/proxmox/5.0.15-1-pve/initrd.img-5.0.15-1-pve
+
+
+.Manually keeping a kernel bootable
+
+Should you wish to add a certain kernel and initrd image to the list of
+bootable kernels you need to:
+
+* create a directory on the ESP (e.g. `/EFI/persona
