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: head/usr.sbin/efibootmgr/efibootmgr.8 354925 2019-11-20 23:58:36Z imp $
  26 .\"
  27 .Dd June 13, 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 .Nm
  70 manipulates how UEFI Boot Managers boot the system.
  71 Methods of booting can be created and destroyed.
  72 Boot methods can be activated or deactivated.
  73 The order of boot methods tried can be changed.
  74 Temporary boot methods can override the usual booting methods.
  75 .Pp
  76 The UEFI standard defines how hosts may control what is used to
  77 bootstrap the system.
  78 Each method is encapsulated within a persistent UEFI variable, stored
  79 by the UEFI BIOS of the form
  80 .Cm Boot Ns Em XXXX .
  81 These variables are numbered, describe where to load the bootstrap
  82 program from, and whether or not the method is active.
  83 The boot order of these methods is controlled by another variable
  84 .Cm BootOrder .
  85 The currently booting method is communicated using
  86 .Cm BootCurrent .
  87 A global timeout can also be set.
  88 .Pp
  89 .Nm
  90 requires that the kernel efirt module be loaded to get and set these
  91 non-volatile variables.
  92 .Pp
  93 The following options are available:
  94 .Bl -tag -width Ds
  95 .It Fl a , Fl -activate
  96 Activate the given
  97 .Ar bootnum
  98 boot entry, or the new entry when used with
  99 .Fl c .
 100 .It Fl A , Fl -deactivate
 101 Deactivate the given
 102 .Ar bootnum
 103 boot entry.
 104 .It Fl b Ar bootnum , Fl -bootnum Ar bootnum
 105 When creating or modifying an entry, use
 106 .Ar bootnum
 107 as the index.
 108 When creating a new entry, fail if it already exists.
 109 .It Fl B , Fl -delete
 110 Delete the given
 111 .Ar bootnum
 112 boot entry.
 113 .It Fl c , Fl -create
 114 Create a new
 115 .Cm Boot
 116 variable.
 117 .It Fl D , Fl -dry-run
 118 Process but do not change any variables.
 119 .It Fl E , Fl -esp
 120 Print the
 121 .Dx
 122 path to the ESP device, derived from the EFI variables
 123 .Va BootCurrent
 124 and
 125 .Va BootXXXX .
 126 This is the ESP partition used by UEFI to boot the current
 127 instance of the system.
 128 If
 129 .Fl d -device-path
 130 is specified, the UEFI device path to the ESP is reported instead.
 131 If
 132 .Fl p -unix-path
 133 is specified, the mount point of the ESP is reported instead.
 134 .It Fl k Ar kernel , Fl -kernel Ar kernel
 135 The path to and name of the kernel.
 136 .It Fl l Ar loader , Fl -loader Ar loader
 137 The path to and name of the loader.
 138 .It Fl L Ar label , Fl -label Ar label
 139 An optional description for the entry.
 140 .It Fl n , Fl -bootnext
 141 Set
 142 .Ar bootnum
 143 boot entry as the
 144 .Cm BootNext
 145 variable.
 146 .It Fl N , Fl -delete-bootnext
 147 Delete the
 148 .Cm BootNext
 149 optional variable.
 150 .It Fl o Ar bootorder , Fl -bootorder Ar bootorder
 151 Set
 152 .Cm BootOrder
 153 variable to the given comma delimited set of
 154 .Ar bootnum Ns s .
 155 The numbers are in hex to match
 156 .Cm Boot Ns Em XXXX ,
 157 but may omit leading zeros.
 158 .It Fl t Ar timeout , Fl -set-timeout Ar timeout
 159 Set the bootmenu timeout value.
 160 .It Fl T , Fl -del-timeout
 161 Delete the
 162 .Cm BootTimeout
 163 variable.
 164 .It Fl v , Fl -verbose
 165 Display the device path of boot entries in the output.
 166 .El
 167 .Sh EXAMPLES
 168 To display the current
 169 .Cm Boot
 170 related variables in the system:
 171 .Pp
 172 .Dl efibootmgr [-v]
 173 .Pp
 174 This will display the optional
 175 .Cm BootNext
 176 bootnum,
 177 .Cm BootCurrent ,
 178 or currently booted bootnum, followed by the optional
 179 .Cm Timeout
 180 value, any
 181 .Cm BootOrder
 182 that may be set, followed finally by all currently defined
 183 .Cm Boot
 184 variables, active or not.
 185 The verbose flag will augment this output with the disk partition uuids,
 186 size/offset and device-path of the variable.
 187 .Pp
 188 The
 189 .Nm
 190 program can be used to create new EFI boot variables.
 191 To create a new boot var pointing to an installation with its EFI partition
 192 mounted under
 193 .Pa /mnt ,
 194 the given loader and a label
 195 .Qq FreeBSD-11 :
 196 .Pp
 197 .Dl efibootmgr -c -l /mnt/EFI/freebsd/loader.efi -L FreeBSD-11
 198 .Pp
 199 This will result in the next available bootnum being assigned to a
 200 new UEFI boot variable, and given the label
 201 .Qq FreeBSD-11
 202 such as:
 203 .Pp
 204 .Dl Boot0009 FreeBSD-11
 205 .Pp
 206 Note newly created boot entries are created inactive.
 207 The active state is denoted by an '*' following the
 208 .Cm Boot Ns Em XXXX
 209 name in the output.
 210 They are also inserted into the first position of current
 211 .Cm BootOrder
 212 variable if it exists.
 213 They must first be set to active before being considered available to attempt
 214 booting from, else they are ignored.
 215 .Pp
 216 .Dl efibootmgr -B -b 0009
 217 .Pp
 218 Will delete the given boot entry Boot0009.
 219 .Pp
 220 To set a given newly created boot entry active use:
 221 .Pp
 222 .Dl efibootmgr -a -b 0009
 223 .Pp
 224 To set a given boot entry to be used as the
 225 .Cm BootNext
 226 variable, irrespective of its active state, use:
 227 .Pp
 228 .Dl efibootmgr -n -b 0009
 229 .Pp
 230 To set the
 231 .Cm BootOrder
 232 for the next reboot use:
 233 .Pp
 234 .Dl efibootmgr -o 0009,0003,...
 235 .Sh SEE ALSO
 236 .Xr efivar 8 ,
 237 .Xr uefi 8