usr.sbin/efibootmgr/efibootmgr.8

   1 .\"
   2 .\" Copyright (c) 2017-2018 Netflix, Inc.
   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 AUTHOR 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 AUTHOR 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 15, 2023
  28 .Dt EFIBOOTMGR 8
  29 .Os
  30 .Sh NAME
  31 .Nm efibootmgr
  32 .Nd manipulate the EFI Boot Manager
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl v
  36 .Nm
  37 .Fl a
  38 .Fl b Ar bootnum
  39 .Nm
  40 .Fl A
  41 .Fl b Ar bootnum
  42 .Nm
  43 .Fl B
  44 .Fl b Ar bootnum
  45 .Nm
  46 .Fl c
  47 .Fl l Ar loader
  48 .Op Fl aD
  49 .Op Fl b Ar bootnum
  50 .Op Fl k Ar kernel
  51 .Op Fl L Ar label
  52 .Op Fl e Ar env
  53 .Nm
  54 .Fl E
  55 .Op Fl d
  56 .Op Fl p
  57 .Nm
  58 .Fl F
  59 .Nm
  60 .Fl f
  61 .Nm
  62 .Fl n
  63 .Fl b Ar bootnum
  64 .Nm
  65 .Fl N
  66 .Nm
  67 .Fl o Ar bootorder
  68 .Nm
  69 .Fl t Ar timeout
  70 .Nm
  71 .Fl T
  72 .Nm Fl u Ar unix-path
  73 .Sh "DESCRIPTION"
  74 The
  75 .Nm
  76 program manipulates how UEFI Boot Managers boot the system.
  77 It can create and destroy methods for booting along with activating or
  78 deactivating them.
  79 It can also change the defined order of boot methods.
  80 It can create a temporary boot (BootNext) variable that references a
  81 boot method to be tried once upon the next boot.
  82 .Pp
  83 The UEFI standard defines how hosts may control what is used to
  84 bootstrap the system.
  85 Each method is encapsulated within a persistent UEFI variable, stored
  86 by the UEFI BIOS of the form
  87 .Cm Boot Ns Em XXXX
  88 (where XXXX are uppercase hexadecimal digits).
  89 These variables are numbered, each describing where to load the bootstrap
  90 program from, and whether or not the method is active (used for booting,
  91 otherwise the method will be skipped).
  92 The order of these methods is controlled by another variable,
  93 .Cm BootOrder .
  94 The currently booted method is communicated using
  95 .Cm BootCurrent .
  96 A global timeout can also be set.
  97 .Pp
  98 .Nm
  99 requires that the kernel module
 100 .Xr efirt 9
 101 module be present or loaded to get and set these
 102 non-volatile variables.
 103 .Pp
 104 The following options are available:
 105 .Bl -tag -width Ds
 106 .It Fl a -activate
 107 Activate the given
 108 .Ar bootnum
 109 boot entry, or the new entry when used with
 110 .Fl c .
 111 .It Fl A -deactivate
 112 Deactivate the given
 113 .Ar bootnum
 114 boot entry.
 115 .It Fl b -bootnum Ar bootnum
 116 When creating or modifying an entry, use
 117 .Ar bootnum
 118 as the index.
 119 When creating a new entry, fail if it already exists.
 120 .It Fl B -delete
 121 Delete the given
 122 .Ar bootnum
 123 boot entry.
 124 .It Fl c -create
 125 Create a new
 126 .Cm Boot
 127 variable (aka method or entry).
 128 .It Fl D -dry-run
 129 Process but do not change any variables.
 130 .It Fl E -esp
 131 Print the
 132 .Fx
 133 path to the ESP device, derived from the EFI variables
 134 .Va BootCurrent
 135 and
 136 .Va BootXXXX .
 137 This is the ESP partition used by UEFI to boot the current
 138 instance of the system.
 139 If
 140 .Fl d -device-path
 141 is specified, the UEFI device path to the ESP is reported instead.
 142 If
 143 .Fl p -unix-path
 144 is specified, the mount point of the ESP is reported instead.
 145 .It Fl f -fw-ui , Fl F -no-fw-ui
 146 Set or clear the request to the system firmware to stop in its user
 147 interface on the next boot.
 148 .It Fl k -kernel Ar kernel
 149 The path to and name of the kernel.
 150 .It Fl l -loader Ar loader
 151 The path to and name of the loader.
 152 .It Fl L -label Ar label
 153 An optional description for the method.
 154 .It Fl n -bootnext
 155 Set
 156 .Ar bootnum
 157 boot entry as the
 158 .Cm BootNext
 159 variable.
 160 .It Fl N -delete-bootnext
 161 Delete the
 162 .Cm BootNext
 163 optional variable.
 164 .It Fl o -bootorder Ar bootorder
 165 Set
 166 .Cm BootOrder
 167 variable to the given comma delimited set of
 168 .Ar bootnum Ns s .
 169 The numbers are in hex to match
 170 .Cm Boot Ns Em XXXX ,
 171 but may omit leading zeros.
 172 .It Fl t -set-timeout Ar timeout
 173 Set the bootmenu timeout value.
 174 .It Fl T -del-timeout
 175 Delete the
 176 .Cm BootTimeout
 177 variable.
 178 .It Fl u -efidev Ar unix-path
 179 Displays the UEFI device path of
 180 .Ar unix-path .
 181 .It Fl v -verbose
 182 Display the device path of boot entries in the output.
 183 .El
 184 .Sh Examples
 185 To display the current
 186 .Cm Boot
 187 related variables in the system:
 188 .Pp
 189 .Dl efibootmgr -v
 190 .Pp
 191 This will display the optional
 192 .Cm BootNext
 193 (if present),
 194 .Cm BootCurrent
 195 (currently booted method), followed by the optional
 196 .Cm Timeout
 197 value, any
 198 .Cm BootOrder
 199 that may be set, followed finally by all currently defined
 200 .Cm Boot
 201 variables, active or not.
 202 The verbose flag,
 203 .Pq Fl v ,
 204 augments this output with the disk partition uuids,
 205 size/offset and device-path of the variable.
 206 The flag will also include any unreferenced (by BootOrder) variables.
 207 .Pp
 208 The
 209 .Nm
 210 program can be used to create new EFI boot variables.
 211 The following command may be used to create a new boot method, using
 212 the EFI partition mounted under
 213 .Pa /boot/efi ,
 214 mark the method active, using
 215 the given loader and label the method
 216 .Qq FreeBSD-11 :
 217 .Pp
 218 .Dl efibootmgr -a -c -l /boot/efi/EFI/freebsd/loader.efi -L FreeBSD-11
 219 .Pp
 220 This will result in the next available bootnum being assigned to a
 221 new UEFI boot variable, and given the label
 222 .Qq FreeBSD-11
 223 such as:
 224 .Pp
 225 .Dl Boot0009 FreeBSD-11
 226 .Pp
 227 Note newly created boot entries are, by default, created inactive, hence
 228 the reason
 229 .Fl a
 230 flag is specified above so that it will be considered for booting.
 231 The active state is denoted by a '*' following the
 232 .Cm Boot Ns Em XXXX
 233 name in the output.
 234 They are also inserted into the first position of current
 235 .Cm BootOrder
 236 variable if it exists.
 237 They must first be set to active before being considered available to attempt
 238 booting from, else they are ignored.
 239 .Pp
 240 .Dl efibootmgr -B -b 0009
 241 .Pp
 242 Will delete the given boot entry Boot0009.
 243 .Pp
 244 To set the given boot entry active:
 245 .Pp
 246 .Dl efibootmgr -a -b 0009
 247 .Pp
 248 To set a given boot entry to be used as the
 249 .Cm BootNext
 250 variable, irrespective of its active state, use:
 251 .Pp
 252 .Dl efibootmgr -n -b 0009
 253 .Pp
 254 To set the
 255 .Cm BootOrder
 256 for the next reboot use:
 257 .Pp
 258 .Dl efibootmgr -o 0009,0003,...
 259 .Sh SEE ALSO
 260 .Xr efirt 9 ,
 261 .Xr efivar 8 ,
 262 .Xr gpart 8 ,
 263 .Xr uefi 8
 264 .Sh STANDARDS
 265 The Unified Extensible Firmware Interface Specification is available
 266 from
 267 .Pa www.uefi.org .