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