You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

system-booting.adoc 7.3KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217
  1. [[sysboot]]
  2. Host Bootloader
  3. ---------------
  4. ifdef::wiki[]
  5. :pve-toplevel:
  6. endif::wiki[]
  7. {pve} currently uses one of two bootloaders depending on the disk setup
  8. selected in the installer.
  9. For EFI Systems installed with ZFS as the root filesystem `systemd-boot` is
  10. used. All other deployments use the standard `grub` bootloader (this usually
  11. also applies to systems which are installed on top of Debian).
  12. [[sysboot_installer_part_scheme]]
  13. Partitioning scheme used by the installer
  14. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. The {pve} installer creates 3 partitions on the bootable disks selected for
  16. installation. The bootable disks are:
  17. * For Installations with `ext4` or `xfs` the selected disk
  18. * For ZFS installations all disks belonging to the first `vdev`:
  19. ** The first disk for RAID0
  20. ** All disks for RAID1, RAIDZ1, RAIDZ2, RAIDZ3
  21. ** The first two disks for RAID10
  22. The created partitions are:
  23. * a 1 MB BIOS Boot Partition (gdisk type EF02)
  24. * a 512 MB EFI System Partition (ESP, gdisk type EF00)
  25. * a third partition spanning the set `hdsize` parameter or the remaining space
  26. used for the chosen storage type
  27. `grub` in BIOS mode (`--target i386-pc`) is installed onto the BIOS Boot
  28. Partition of all bootable disks for supporting older systems.
  29. [[sysboot_grub]]
  30. Grub
  31. ~~~~
  32. `grub` has been the de-facto standard for booting Linux systems for many years
  33. and is quite well documented
  34. footnote:[Grub Manual https://www.gnu.org/software/grub/manual/grub/grub.html].
  35. The kernel and initrd images are taken from `/boot` and its configuration file
  36. `/boot/grub/grub.cfg` gets updated by the kernel installation process.
  37. Configuration
  38. ^^^^^^^^^^^^^
  39. Changes to the `grub` configuration are done via the defaults file
  40. `/etc/default/grub` or config snippets in `/etc/default/grub.d`. To regenerate
  41. the `/boot/grub/grub.cfg` after a change to the configuration run:
  42. ----
  43. `update-grub`.
  44. ----
  45. [[sysboot_systemd_boot]]
  46. Systemd-boot
  47. ~~~~~~~~~~~~
  48. `systemd-boot` is a lightweight EFI bootloader. It reads the kernel and initrd
  49. images directly from the EFI Service Partition (ESP) where it is installed.
  50. The main advantage of directly loading the kernel from the ESP is that it does
  51. not need to reimplement the drivers for accessing the storage. In the context
  52. of ZFS as root filesystem this means that you can use all optional features on
  53. your root pool instead of the subset which is also present in the ZFS
  54. implementation in `grub` or having to create a separate small boot-pool
  55. footnote:[Booting ZFS on root with grub https://github.com/zfsonlinux/zfs/wiki/Debian-Stretch-Root-on-ZFS].
  56. In setups with redundancy (RAID1, RAID10, RAIDZ*) all bootable disks (those
  57. being part of the first `vdev`) are partitioned with an ESP. This ensures the
  58. system boots even if the first boot device fails. The ESPs are kept in sync by
  59. a kernel postinstall hook script `/etc/kernel/postinst.d/zz-pve-efiboot`. The
  60. script copies certain kernel versions and the initrd images to `EFI/proxmox/`
  61. on the root of each ESP and creates the appropriate config files in
  62. `loader/entries/proxmox-*.conf`. The `pve-efiboot-tool` script assists in
  63. managing both the synced ESPs themselves and their contents.
  64. The following kernel versions are configured by default:
  65. * the currently running kernel
  66. * the version being newly installed on package updates
  67. * the two latest already installed kernels
  68. * the latest version of the second-to-last kernel series (e.g. 4.15, 5.0), if applicable
  69. * any manually selected kernels (see below)
  70. The ESPs are not kept mounted during regular operation, in contrast to `grub`,
  71. which keeps an ESP mounted on `/boot/efi`. This helps to prevent filesystem
  72. corruption to the `vfat` formatted ESPs in case of a system crash, and removes
  73. the need to manually adapt `/etc/fstab` in case the primary boot device fails.
  74. [[sysboot_systemd_boot_config]]
  75. Configuration
  76. ^^^^^^^^^^^^^
  77. `systemd-boot` is configured via the file `loader/loader.conf` in the root
  78. directory of an EFI System Partition (ESP). See the `loader.conf(5)` manpage
  79. for details.
  80. Each bootloader entry is placed in a file of its own in the directory
  81. `loader/entries/`
  82. An example entry.conf looks like this (`/` refers to the root of the ESP):
  83. ----
  84. title Proxmox
  85. version 5.0.15-1-pve
  86. options root=ZFS=rpool/ROOT/pve-1 boot=zfs
  87. linux /EFI/proxmox/5.0.15-1-pve/vmlinuz-5.0.15-1-pve
  88. initrd /EFI/proxmox/5.0.15-1-pve/initrd.img-5.0.15-1-pve
  89. ----
  90. .Manually keeping a kernel bootable
  91. Should you wish to add a certain kernel and initrd image to the list of
  92. bootable kernels use `pve-efiboot-tool kernel add`.
  93. For example run the following to add the kernel with ABI version `5.0.15-1-pve`
  94. to the list of kernels to keep installed and synced to all ESPs:
  95. ----
  96. pve-efiboot-tool kernel add 5.0.15-1-pve
  97. ----
  98. `pve-efiboot-tool kernel list` will list all kernel versions currently selected
  99. for booting:
  100. ----
  101. # pve-efiboot-tool kernel list
  102. Manually selected kernels:
  103. 5.0.15-1-pve
  104. Automatically selected kernels:
  105. 5.0.12-1-pve
  106. 4.15.18-18-pve
  107. ----
  108. Run `pve-efiboot-tool remove` to remove a kernel from the list of manually
  109. selected kernels, for example:
  110. ----
  111. pve-efiboot-tool kernel remove 5.0.15-1-pve
  112. ----
  113. NOTE: It's required to run `pve-efiboot-tool refresh` to update all EFI System
  114. Partitions (ESPs) after a manual kernel addition or removal from above.
  115. [[sysboot_systemd_boot_setup]]
  116. .Setting up a new partition for use as synced ESP
  117. To format and initialize a partition as synced ESP, e.g., after replacing a
  118. failed vdev in an rpool, or when converting an existing system that pre-dates
  119. the sync mechanism, `pve-efiboot-tool` from `pve-kernel-helpers` can be used.
  120. WARNING: the `format` command will format the `<partition>`, make sure to pass
  121. in the right device/partition!
  122. For example, to format an empty partition `/dev/sda2` as ESP, run the following:
  123. ----
  124. pve-efiboot-tool format /dev/sda2
  125. ----
  126. To setup an existing, unmounted ESP located on `/dev/sda2` for inclusion in
  127. {pve}'s kernel update synchronization mechanism, use the following:
  128. ----
  129. pve-efiboot-tool init /dev/sda2
  130. ----
  131. Afterwards `/etc/kernel/pve-efiboot-uuids` should contain a new line with the
  132. UUID of the newly added partition. The `init` command will also automatically
  133. trigger a refresh of all configured ESPs.
  134. [[sysboot_systemd_boot_refresh]]
  135. .Updating the configuration on all ESPs
  136. To copy and configure all bootable kernels and keep all ESPs listed in
  137. `/etc/kernel/pve-efiboot-uuids` in sync you just need to run:
  138. ----
  139. pve-efiboot-tool refresh
  140. ----
  141. (The equivalent to running `update-grub` on systems being booted with `grub`).
  142. This is necessary should you make changes to the kernel commandline, or want to
  143. sync all kernels and initrds.
  144. NOTE: Both `update-initramfs` and `apt` (when necessary) will automatically
  145. trigger a refresh.
  146. [[sysboot_edit_kernel_cmdline]]
  147. Editing the kernel commandline
  148. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  149. You can modify the kernel commandline in the following places, depending on the
  150. bootloader used:
  151. .Grub
  152. The kernel commandline needs to be placed in the variable
  153. `GRUB_CMDLINE_LINUX_DEFAULT` in the file `/etc/default/grub`. Running
  154. `update-grub` appends its content to all `linux` entries in
  155. `/boot/grub/grub.cfg`.
  156. .Systemd-boot
  157. The kernel commandline needs to be placed as one line in `/etc/kernel/cmdline`.
  158. To apply your changes, run `pve-efiboot-tool refresh`, which sets it as the
  159. `option` line for all config files in `loader/entries/proxmox-*.conf`.