stand/efi/gptboot/gptboot.efi.8

   1 .\" Copyright (c) 2013 Warren Block All rights reserved.
   2 .\" Copyright (c) 2021 Warner Losh
   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 6, 2021
  28 .Dt GPTBOOT.EFI 8
  29 .Os
  30 .Sh NAME
  31 .Nm gptboot.efi
  32 .Nd GPT bootcode for UFS on UEFI computers
  33 .Sh DESCRIPTION
  34 .Nm
  35 is used on UEFI computers to boot from a UFS partition on a
  36 GPT-partitioned disk.
  37 .Nm
  38 is installed in the EFI System Partition (ESP).
  39 For BIOS-based computers,
  40 see
  41 .Xr gptboot 8
  42 for details.
  43 While conceptually similar, the details differ.
  44 .Nm
  45 works only with UFS root file systems.
  46 Users with ZFS partitions should use
  47 .Xr loader.efi 8
  48 with
  49 .Xr bectl 8
  50 to control what dataset is used for root.
  51 .Pp
  52 What UEFI computers boot is usually controlled via the mechanisms explained in
  53 .Xr efibootmgr 8
  54 using
  55 .Xr loader.efi 8
  56 or
  57 .Xr boot1.efi 8 .
  58 However, some setups cannot use those mechanisms.
  59 When the users cannot rely on host-supplied UEFI variables
  60 or they want the contents of the media alone to decide root,
  61 .Nm
  62 accomplishes these goals.
  63 .Pp
  64 When it starts,
  65 .Nm
  66 first reads the GPT and determines which drive and partition to
  67 boot from, as described under
  68 .Sx BOOTING ,
  69 below.
  70 If it does not find an eligible partition, it returns to the UEFI
  71 firmware.
  72 The firmware will then try the next bootable item in the UEFI Boot Manager's
  73 list, if any, usually a different disk.
  74 .Sh IMPLEMENTATION NOTES
  75 The GPT standard allows a variable number of partitions, but
  76 .Nm
  77 only boots from tables with 128 partitions or less.
  78 .Sh PARTITION ATTRIBUTES
  79 .Nm
  80 checks and manages several attributes of GPT UFS partitions.
  81 These flags are
  82 .Fx
  83 specific and non-standard.
  84 .Bl -tag -width ".Cm bootfailed"
  85 .It Cm bootme
  86 Attempt to boot from this partition.
  87 If more than one partition has the
  88 .Cm bootme
  89 attribute set,
  90 .Nm
  91 will attempt to boot each one until successful.
  92 .It Cm bootonce
  93 Attempt to boot from this partition only one time.
  94 Setting this attribute with
  95 .Xr gpart 8
  96 automatically also sets the
  97 .Cm bootme
  98 attribute.
  99 Multiple partitions may have the
 100 .Cm bootonce
 101 and
 102 .Cm bootme
 103 attributes set.
 104 .It Cm bootfailed
 105 The
 106 .Cm bootfailed
 107 attribute marks partitions that had the
 108 .Cm bootonce
 109 attribute set, but failed to boot.
 110 This attribute is managed by the system.
 111 See
 112 .Sx "BOOTING"
 113 and
 114 .Sx "POST-BOOT ACTIONS"
 115 below for details.
 116 .El
 117 .Sh USAGE
 118 For normal usage, the user does not have to set or manage any of the
 119 partition attributes.
 120 .Nm
 121 will boot from the first UFS partition found on the device.
 122 .Pp
 123 The
 124 .Cm bootonce
 125 attribute can be used for testing an upgraded operating system on
 126 an already-working computer.
 127 The existing system partition is left untouched, and the new version
 128 of the operating system to be tested is installed on another partition.
 129 The
 130 .Cm bootonce
 131 attribute is set on that new test partition.
 132 The next boot is attempted from the test partition.
 133 Success or failure will be shown in the system log files.
 134 After a successful boot of the test partition, a user script can check
 135 the logs and change the
 136 .Cm bootme
 137 attributes so the test partition becomes the new system partition.
 138 Because the
 139 .Cm bootonce
 140 attribute is cleared after an attempted boot, a failed boot will not
 141 leave the system attempting to boot from a partition that will never
 142 succeed.
 143 Instead, the system will boot from the older, known-working operating
 144 system that has not been modified.
 145 If the
 146 .Cm bootme
 147 attribute is set on any partitions, booting will be attempted from them
 148 first.
 149 If no partitions with
 150 .Cm bootme
 151 attributes are found, booting will be attempted from the first UFS
 152 partition found.
 153 .Sh BOOTING
 154 .Nm
 155 first reads the partition table.
 156 All
 157 .Cm freebsd-ufs
 158 partitions with only the
 159 .Cm bootonce
 160 attribute set, indicating a failed boot, are set to
 161 .Cm bootfailed .
 162 .Nm
 163 then scans through all of the
 164 .Cm freebsd-ufs
 165 partitions.
 166 Boot behavior depends on the combination of
 167 .Cm bootme
 168 and
 169 .Cm bootonce
 170 attributes set on those partitions.
 171 .Bl -tag -width ".Cm bootonce + .Cm bootme"
 172 .It Cm bootonce + Cm bootme
 173 Highest priority: booting is attempted from each of the
 174 .Cm freebsd-ufs
 175 partitions with both of these attributes.
 176 On each partition, the
 177 .Cm bootme
 178 attribute is removed and the boot attempted.
 179 .It Cm bootme
 180 Middle priority: booting is attempted from each of the
 181 .Cm freebsd-ufs
 182 partitions with the
 183 .Cm bootme
 184 attribute.
 185 .El
 186 .Pp
 187 If neither
 188 .Cm bootonce
 189 nor
 190 .Cm bootme
 191 attributes are found on any partitions, booting is attempted from the
 192 first
 193 .Cm freebsd-ufs
 194 partition on the disk.
 195 .Sh POST-BOOT ACTIONS
 196 The startup script
 197 .Pa /etc/rc.d/gptboot
 198 checks the attributes of
 199 .Cm freebsd-ufs
 200 partitions on all GPT disks.
 201 Partitions with the
 202 .Cm bootfailed
 203 attribute generate a
 204 .Dq boot from X failed
 205 system log message.
 206 Partitions with only the
 207 .Cm bootonce
 208 attribute, indicating a partition that successfully booted, generate a
 209 .Dq boot from X succeeded
 210 system log message.
 211 The
 212 .Cm bootfailed
 213 attributes are cleared from all the partitions.
 214 The
 215 .Cm bootonce
 216 attribute is cleared from the partition that successfully booted.
 217 There is normally only one of these.
 218 .Sh FILES
 219 .Bl -tag -width /boot/gptboot.efi -compact
 220 .It Pa /boot/gptboot.efi
 221 bootcode binary
 222 .It Pa /boot/efi/efi/boot/bootx64.efi
 223 Default boot loader for amd64 systems.
 224 .It Pa /boot/efi/efi/boot/bootaa64.efi
 225 Default boot loader for arm64 systems.
 226 .It Pa /boot/efi/efi/boot/bootarm.efi
 227 Default boot loader for arm systems.
 228 .It Pa /boot/efi/efi/boot/bootriscv64.efi
 229 Default boot loader for riscv systems.
 230 .El
 231 .Sh EXAMPLES
 232 .Nm
 233 is installed in the ESP with
 234 .Xr cp 1 .
 235 .Pp
 236 Install
 237 .Nm
 238 into the ESP for the system.
 239 This assumes the ESP is mounted in the standard
 240 .Pa /boot/efi
 241 directory.
 242 For amd64, use the following
 243 .Bd -literal -offset indent -compact
 244 cp /boot/gptboot.efi /boot/efi/efi/boot/bootx64.efi
 245 .Ed
 246 For other systems, use the file listed in the
 247 .Sx FILES
 248 section.
 249 .Pp
 250 Set the
 251 .Cm bootme
 252 attribute for partition 2:
 253 .Bd -literal -offset indent
 254 gpart set -a bootme -i 2 ada0
 255 .Ed
 256 .Pp
 257 Set the
 258 .Cm bootonce
 259 attribute for partition 2, automatically also setting the
 260 .Cm bootme
 261 attribute:
 262 .Bd -literal -offset indent
 263 gpart set -a bootonce -i 2 ada0
 264 .Ed
 265 .Sh SEE ALSO
 266 .Xr rc.conf 5 ,
 267 .Xr boot 8 ,
 268 .Xr efibootmgr 8 ,
 269 .Xr gpart 8 ,
 270 .Xr gptboot 8 ,
 271 .Xr loader.efi 8
 272 .Sh HISTORY
 273 .Nm
 274 appeared in
 275 .Fx 13.0
 276 .Sh AUTHORS
 277 This manual page written by
 278 .An Warner Losh Aq imp@FreeBSD.org .
 279 It is based heavily on the
 280 .Xr gptboot 8
 281 man page by
 282 .An Warren Block Aq wblock@FreeBSD.org .