xref: /freebsd/stand/efi/gptboot/gptboot.efi.8 (revision 6137b5f7b8c183ee8806d79b3f1d8e5e3ddb3df3)
1.\" Copyright (c) 2013 Warren Block All rights reserved.
2.\" Copyright (c) 2021 Warner Losh
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
12.\"
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
23.\" SUCH DAMAGE.
24.\"
25.Dd April 13, 2023
26.Dt GPTBOOT.EFI 8
27.Os
28.Sh NAME
29.Nm gptboot.efi
30.Nd GPT bootcode for UFS on UEFI computers
31.Sh DESCRIPTION
32.Nm
33is used on UEFI computers to boot from a UFS partition on a
34GPT-partitioned disk.
35.Nm
36is installed in the EFI System Partition (ESP).
37For BIOS-based computers,
38see
39.Xr gptboot 8
40for details.
41While conceptually similar, the details differ.
42.Nm
43works only with UFS root file systems.
44Users with ZFS partitions should use
45.Xr loader.efi 8
46with
47.Xr bectl 8
48to control what dataset is used for root.
49.Pp
50What UEFI computers boot is usually controlled via the mechanisms explained in
51.Xr efibootmgr 8
52using
53.Xr loader.efi 8
54or
55.Xr boot1.efi 8 .
56However, some setups cannot use those mechanisms.
57When the users cannot rely on host-supplied UEFI variables
58or they want the contents of the media alone to decide root,
59.Nm
60accomplishes these goals.
61.Pp
62When it starts,
63.Nm
64first reads the GPT and determines which drive and partition to
65boot from, as described under
66.Sx BOOTING ,
67below.
68If it does not find an eligible partition, it returns to the UEFI
69firmware.
70The firmware will then try the next bootable item in the UEFI Boot Manager's
71list, if any, usually a different disk.
72.Sh IMPLEMENTATION NOTES
73The GPT standard allows a variable number of partitions, but
74.Nm
75only boots from tables with 128 partitions or less.
76.Sh PARTITION ATTRIBUTES
77.Nm
78checks and manages several attributes of GPT UFS partitions.
79These flags are
80.Fx
81specific and non-standard.
82.Bl -tag -width ".Cm bootfailed"
83.It Cm bootme
84Attempt to boot from this partition.
85If more than one partition has the
86.Cm bootme
87attribute set,
88.Nm
89will attempt to boot each one until successful.
90.It Cm bootonce
91Attempt to boot from this partition only one time.
92Setting this attribute with
93.Xr gpart 8
94automatically also sets the
95.Cm bootme
96attribute.
97Multiple partitions may have the
98.Cm bootonce
99and
100.Cm bootme
101attributes set.
102.It Cm bootfailed
103The
104.Cm bootfailed
105attribute marks partitions that had the
106.Cm bootonce
107attribute set, but failed to boot.
108This attribute is managed by the system.
109See
110.Sx "BOOTING"
111and
112.Sx "POST-BOOT ACTIONS"
113below for details.
114.El
115.Sh USAGE
116For normal usage, the user does not have to set or manage any of the
117partition attributes.
118.Nm
119will boot from the first UFS partition found on the device.
120.Pp
121The
122.Cm bootonce
123attribute can be used for testing an upgraded operating system on
124an already-working computer.
125The existing system partition is left untouched, and the new version
126of the operating system to be tested is installed on another partition.
127The
128.Cm bootonce
129attribute is set on that new test partition.
130The next boot is attempted from the test partition.
131Success or failure will be shown in the system log files.
132After a successful boot of the test partition, a user script can check
133the logs and change the
134.Cm bootme
135attributes so the test partition becomes the new system partition.
136Because the
137.Cm bootonce
138attribute is cleared after an attempted boot, a failed boot will not
139leave the system attempting to boot from a partition that will never
140succeed.
141Instead, the system will boot from the older, known-working operating
142system that has not been modified.
143If the
144.Cm bootme
145attribute is set on any partitions, booting will be attempted from them
146first.
147If no partitions with
148.Cm bootme
149attributes are found, booting will be attempted from the first UFS
150partition found.
151.Sh BOOTING
152.Nm
153first reads the partition table.
154All
155.Cm freebsd-ufs
156partitions with only the
157.Cm bootonce
158attribute set, indicating a failed boot, are set to
159.Cm bootfailed .
160.Nm
161then scans through all of the
162.Cm freebsd-ufs
163partitions.
164Boot behavior depends on the combination of
165.Cm bootme
166and
167.Cm bootonce
168attributes set on those partitions.
169.Bl -tag -width ".Cm bootonce + .Cm bootme"
170.It Cm bootonce + Cm bootme
171Highest priority: booting is attempted from each of the
172.Cm freebsd-ufs
173partitions with both of these attributes.
174On each partition, the
175.Cm bootme
176attribute is removed and the boot attempted.
177.It Cm bootme
178Middle priority: booting is attempted from each of the
179.Cm freebsd-ufs
180partitions with the
181.Cm bootme
182attribute.
183.El
184.Pp
185If neither
186.Cm bootonce
187nor
188.Cm bootme
189attributes are found on any partitions, booting is attempted from the
190first
191.Cm freebsd-ufs
192partition on the disk.
193.Sh POST-BOOT ACTIONS
194The startup script
195.Pa /etc/rc.d/gptboot
196checks the attributes of
197.Cm freebsd-ufs
198partitions on all GPT disks.
199Partitions with the
200.Cm bootfailed
201attribute generate a
202.Dq boot from X failed
203system log message.
204Partitions with only the
205.Cm bootonce
206attribute, indicating a partition that successfully booted, generate a
207.Dq boot from X succeeded
208system log message.
209The
210.Cm bootfailed
211attributes are cleared from all the partitions.
212The
213.Cm bootonce
214attribute is cleared from the partition that successfully booted.
215There is normally only one of these.
216.Sh FILES
217.Bl -tag -width /boot/gptboot.efi -compact
218.It Pa /boot/gptboot.efi
219bootcode binary
220.It Pa /boot/efi/efi/boot/bootx64.efi
221Default boot loader for amd64 systems.
222.It Pa /boot/efi/efi/boot/bootaa64.efi
223Default boot loader for arm64 systems.
224.It Pa /boot/efi/efi/boot/bootarm.efi
225Default boot loader for arm systems.
226.It Pa /boot/efi/efi/boot/bootriscv64.efi
227Default boot loader for riscv systems.
228.El
229.Sh EXAMPLES
230.Nm
231is installed in the ESP with
232.Xr cp 1 .
233.Pp
234Install
235.Nm
236into the ESP for the system.
237This assumes the ESP is mounted in the standard
238.Pa /boot/efi
239directory.
240For amd64, use the following
241.Bd -literal -offset indent -compact
242cp /boot/gptboot.efi /boot/efi/efi/boot/bootx64.efi
243.Ed
244For other systems, use the file listed in the
245.Sx FILES
246section.
247.Pp
248Set the
249.Cm bootme
250attribute for partition 2:
251.Bd -literal -offset indent
252gpart set -a bootme -i 2 ada0
253.Ed
254.Pp
255Set the
256.Cm bootonce
257attribute for partition 2, automatically also setting the
258.Cm bootme
259attribute:
260.Bd -literal -offset indent
261gpart set -a bootonce -i 2 ada0
262.Ed
263.Sh SEE ALSO
264.Xr rc.conf 5 ,
265.Xr boot 8 ,
266.Xr efibootmgr 8 ,
267.Xr gpart 8 ,
268.Xr gptboot 8 ,
269.Xr loader.efi 8
270.Sh HISTORY
271.Nm
272appeared in
273.Fx 13.0
274.Sh AUTHORS
275This manual page was written by
276.An Warner Losh Aq imp@FreeBSD.org .
277It is based heavily on the
278.Xr gptboot 8
279man page by
280.An Warren Block Aq wblock@FreeBSD.org .
281