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