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