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