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