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