1 .\" Copyright (c) 2013 Warren Block All rights reserved.
2 .\" Copyright (c) 2021 Warner Losh
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd GPT bootcode for UFS on UEFI computers
35 is used on UEFI computers to boot from a UFS partition on a
38 is installed in the EFI System Partition (ESP).
39 For BIOS-based computers,
43 While conceptually similar, the details differ.
45 works only with UFS root file systems.
46 Users with ZFS partitions should use
50 to control what dataset is used for root.
52 What UEFI computers boot is usually controlled via the mechanisms explained in
58 However, some setups cannot use those mechanisms.
59 When the users cannot rely on host-supplied UEFI variables
60 or they want the contents of the media alone to decide root,
62 accomplishes these goals.
66 first reads the GPT and determines which drive and partition to
67 boot from, as described under
70 If it does not find an eligible partition, it returns to the UEFI
72 The firmware will then try the next bootable item in the UEFI Boot Manager's
73 list, if any, usually a different disk.
74 .Sh IMPLEMENTATION NOTES
75 The GPT standard allows a variable number of partitions, but
77 only boots from tables with 128 partitions or less.
78 .Sh PARTITION ATTRIBUTES
80 checks and manages several attributes of GPT UFS partitions.
83 specific and non-standard.
84 .Bl -tag -width ".Cm bootfailed"
86 Attempt to boot from this partition.
87 If more than one partition has the
91 will attempt to boot each one until successful.
93 Attempt to boot from this partition only one time.
94 Setting this attribute with
96 automatically also sets the
99 Multiple partitions may have the
107 attribute marks partitions that had the
109 attribute set, but failed to boot.
110 This attribute is managed by the system.
114 .Sx "POST-BOOT ACTIONS"
118 For normal usage, the user does not have to set or manage any of the
119 partition attributes.
121 will boot from the first UFS partition found on the device.
125 attribute can be used for testing an upgraded operating system on
126 an already-working computer.
127 The existing system partition is left untouched, and the new version
128 of the operating system to be tested is installed on another partition.
131 attribute is set on that new test partition.
132 The next boot is attempted from the test partition.
133 Success or failure will be shown in the system log files.
134 After a successful boot of the test partition, a user script can check
135 the logs and change the
137 attributes so the test partition becomes the new system partition.
140 attribute is cleared after an attempted boot, a failed boot will not
141 leave the system attempting to boot from a partition that will never
143 Instead, the system will boot from the older, known-working operating
144 system that has not been modified.
147 attribute is set on any partitions, booting will be attempted from them
149 If no partitions with
151 attributes are found, booting will be attempted from the first UFS
155 first reads the partition table.
158 partitions with only the
160 attribute set, indicating a failed boot, are set to
163 then scans through all of the
166 Boot behavior depends on the combination of
170 attributes set on those partitions.
171 .Bl -tag -width ".Cm bootonce + .Cm bootme"
172 .It Cm bootonce + Cm bootme
173 Highest priority: booting is attempted from each of the
175 partitions with both of these attributes.
176 On each partition, the
178 attribute is removed and the boot attempted.
180 Middle priority: booting is attempted from each of the
191 attributes are found on any partitions, booting is attempted from the
194 partition on the disk.
195 .Sh POST-BOOT ACTIONS
197 .Pa /etc/rc.d/gptboot
198 checks the attributes of
200 partitions on all GPT disks.
204 .Dq boot from X failed
206 Partitions with only the
208 attribute, indicating a partition that successfully booted, generate a
209 .Dq boot from X succeeded
213 attributes are cleared from all the partitions.
216 attribute is cleared from the partition that successfully booted.
217 There is normally only one of these.
219 .Bl -tag -width /boot/gptboot.efi -compact
220 .It Pa /boot/gptboot.efi
222 .It Pa /boot/efi/efi/boot/bootx64.efi
223 Default boot loader for amd64 systems.
224 .It Pa /boot/efi/efi/boot/bootaa64.efi
225 Default boot loader for arm64 systems.
226 .It Pa /boot/efi/efi/boot/bootarm.efi
227 Default boot loader for arm systems.
228 .It Pa /boot/efi/efi/boot/bootriscv64.efi
229 Default boot loader for riscv systems.
233 is installed in the ESP with
238 into the ESP for the system.
239 This assumes the ESP is mounted in the standard
242 For amd64, use the following
243 .Bd -literal -offset indent -compact
244 cp /boot/gptboot.efi /boot/efi/efi/boot/bootx64.efi
246 For other systems, use the file listed in the
252 attribute for partition 2:
253 .Bd -literal -offset indent
254 gpart set -a bootme -i 2 ada0
259 attribute for partition 2, automatically also setting the
262 .Bd -literal -offset indent
263 gpart set -a bootonce -i 2 ada0
277 This manual page written by
278 .An Warner Losh Aq imp@FreeBSD.org .
279 It is based heavily on the
282 .An Warren Block Aq wblock@FreeBSD.org .