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