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