stand/i386/gptboot/gptboot.8

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