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