1.\" Copyright (c) 2013 Warren Block 2.\" All rights reserved. 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 March 18, 2022 26.Dt GPTBOOT 8 27.Os 28.Sh NAME 29.Nm gptboot 30.Nd GPT bootcode for UFS on BIOS-based computers 31.Sh DESCRIPTION 32.Nm 33is used on BIOS-based computers to boot from a UFS partition on a 34GPT-partitioned disk. 35.Nm 36is installed in a 37.Cm freebsd-boot 38partition with 39.Xr gpart 8 . 40For UEFI, 41.Xr gptboot.efi 8 42is used instead. 43While conceptually similar, the details differ. 44.Pp 45When it starts, 46.Nm 47first reads the GPT and determines which drive and partition to 48boot from, as described under 49.Sx BOOTING , 50below. 51If it does not find an eligible partition, or if the user hits a 52key within three seconds, 53.Nm 54switches from auto-boot to interactive mode. 55Interactive mode allows manual selection of the disk, partition, 56filename, and boot option flags, as described in 57.Xr boot 8 . 58.Sh IMPLEMENTATION NOTES 59The GPT standard allows a variable number of partitions, but 60.Nm 61only boots from tables with 128 partitions or less. 62.Sh PARTITION ATTRIBUTES 63.Nm 64checks and manages several attributes of GPT UFS partitions. 65.Bl -tag -width ".Cm bootfailed" 66.It Cm bootme 67Attempt to boot from this partition. 68If more than one partition has the 69.Cm bootme 70attribute set, 71.Nm 72will attempt to boot each one until successful. 73.It Cm bootonce 74Attempt to boot from this partition only one time. 75Setting this attribute with 76.Xr gpart 8 77automatically also sets the 78.Cm bootme 79attribute. 80Multiple partitions may have the 81.Cm bootonce 82and 83.Cm bootme 84attributes set. 85.It Cm bootfailed 86The 87.Cm bootfailed 88attribute marks partitions that had the 89.Cm bootonce 90attribute set, but failed to boot. 91This attribute is managed by the system. 92See 93.Sx "BOOTING" 94and 95.Sx "POST-BOOT ACTIONS" 96below for details. 97.El 98.Sh USAGE 99For normal usage, the user does not have to set or manage any of the 100partition attributes. 101.Nm 102will boot from the first UFS partition found. 103.Pp 104The 105.Cm bootonce 106attribute can be used for testing an upgraded operating system on 107an already-working computer. 108The existing system partition is left untouched, and the new version 109of the operating system to be tested is installed on another partition. 110The 111.Cm bootonce 112attribute is set on that new test partition. 113The next boot is attempted from the test partition. 114Success or failure will be shown in the system log files. 115After a successful boot of the test partition, a user script can check 116the logs and change the 117.Cm bootme 118attributes so the test partition becomes the new system partition. 119Because the 120.Cm bootonce 121attribute is cleared after an attempted boot, a failed boot will not 122leave the system attempting to boot from a partition that will never 123succeed. 124Instead, the system will boot from the older, known-working operating 125system that has not been modified. 126If the 127.Cm bootme 128attribute is set on any partitions, booting will be attempted from them 129first. 130If no partitions with 131.Cm bootme 132attributes are found, booting will be attempted from the first UFS 133partition found. 134.Sh BOOTING 135.Nm 136first reads the partition table. 137All 138.Cm freebsd-ufs 139partitions with only the 140.Cm bootonce 141attribute set, indicating a failed boot, are set to 142.Cm bootfailed . 143.Nm 144then scans through all of the 145.Cm freebsd-ufs 146partitions. 147Boot behavior depends on the combination of 148.Cm bootme 149and 150.Cm bootonce 151attributes set on those partitions. 152.Bl -tag -width ".Cm bootonce + .Cm bootme" 153.It Cm bootonce + Cm bootme 154Highest priority: booting is attempted from each of the 155.Cm freebsd-ufs 156partitions with both of these attributes. 157On each partition, the 158.Cm bootme 159attribute is removed and the boot attempted. 160.It Cm bootme 161Middle priority: booting is attempted from each of the 162.Cm freebsd-ufs 163partitions with the 164.Cm bootme 165attribute. 166.El 167.Pp 168If neither 169.Cm bootonce 170nor 171.Cm bootme 172attributes are found on any partitions, booting is attempted from the 173first 174.Cm freebsd-ufs 175partition on the disk. 176.Sh POST-BOOT ACTIONS 177The startup script 178.Pa /etc/rc.d/gptboot 179checks the attributes of 180.Cm freebsd-ufs 181partitions on all GPT disks. 182Partitions with the 183.Cm bootfailed 184attribute generate a 185.Dq boot from X failed 186system log message. 187Partitions with only the 188.Cm bootonce 189attribute, indicating a partition that successfully booted, generate a 190.Dq boot from X succeeded 191system log message. 192The 193.Cm bootfailed 194attributes are cleared from all the partitions. 195The 196.Cm bootonce 197attribute is cleared from the partition that successfully booted. 198There is normally only one of these. 199.Sh FILES 200.Bl -tag -width /boot/gptboot -compact 201.It Pa /boot/gptboot 202bootcode binary 203.It Pa /boot.config 204parameters for the boot blocks 205.Pq optional 206.El 207.Sh EXAMPLES 208.Nm 209is installed in a 210.Cm freebsd-boot 211partition, usually the first partition on the disk. 212A 213.Dq protective MBR 214.Po 215see 216.Xr gpart 8 217.Pc 218is typically installed in combination with 219.Nm . 220.Pp 221Install 222.Nm 223on the 224.Pa ada0 225drive: 226.Bd -literal -offset indent 227gpart bootcode -b /boot/pmbr -p /boot/gptboot -i 1 ada0 228.Ed 229.Pp 230.Nm 231can also be installed without the PMBR: 232.Bd -literal -offset indent 233gpart bootcode -p /boot/gptboot -i 1 ada0 234.Ed 235.Pp 236Set the 237.Cm bootme 238attribute for partition 2: 239.Bd -literal -offset indent 240gpart set -a bootme -i 2 ada0 241.Ed 242.Pp 243Set the 244.Cm bootonce 245attribute for partition 2, automatically also setting the 246.Cm bootme 247attribute: 248.Bd -literal -offset indent 249gpart set -a bootonce -i 2 ada0 250.Ed 251.Sh SEE ALSO 252.Xr boot.config 5 , 253.Xr rc.conf 5 , 254.Xr boot 8 , 255.Xr gpart 8 256.Sh HISTORY 257.Nm 258appeared in 259.Fx 7.1 . 260.Sh AUTHORS 261This manual page was written by 262.An Warren Block Aq wblock@FreeBSD.org . 263