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