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