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 May 8, 2018
  28 .Dt EFIBOOTMGR 8
  29 .Os
  30 .Sh NAME
  31 .Nm efibootmgr
  32 .Nd manipulate the EFI Boot Manager
  33 .Sh SYNOPSIS
  34 .Op Fl aAnNB Ar Bootvar
  35 .Op Fl t Ar timeout
  36 .Op Fl T
  37 .Op Fl o Ar bootorder
  38 .Op Fl verbose
  39 .Op Fl c -k Ar kernel -l Ar loader [-L Ar label] [--dry-run] [-b Bootvar]
  40 .Sh "DESCRIPTION"
  41 .Nm
  42 manipulates how UEFI Boot Managers boot the system.
  43 Methods of booting can be created and destroyed.
  44 Boot methods can be activated or deactivated.
  45 The order of boot methods tried can be changed.
  46 Temporary boot methods can override the usual booting methods.
  47 .Pp
  48 The UEFI standard defines how hosts may control what is used to
  49 bootstrap the system.
  50 Each method is encapsulated within a persistent UEFI variable, stored
  51 by the UEFI BIOS of the form
  52 .Va BootXXXX .
  53 These variables are numbered, describe where to load the bootstrap
  54 program from, and whether or not the method is active.
  55 The boot order of these methods is controlled by another variable
  56 .Va BootOrder .
  57 The currently booting method is communicated using
  58 .Va BootCurrent .
  59 A global timeout can also be set.
  60 .Pp
  61 .Nm
  62 requires that the kernel efirt module to get and set these
  63 non-volatile variables.
  64 .Pp
  65 The following options are available:
  66 .Bl -tag -width 28m
  67 .It Fl c Fl -create
  68 Create a new Boot Variable
  69 .It Fl l -loader Ar loader
  70 The path to and name of the loader.
  71 .It Fl k -kernel Ar kernel
  72 The path to and name of the kernel.
  73 .It Fl b Bootvar
  74 When creating an entry, use Bootvar as the index.
  75 Fail if it already exists.
  76 .It Fl L -label Ar label
  77 An optional description for the entry.
  78 .It Fl D -dry-run
  79 Process but do not set the given BootVar.
  80 .It Fl B -delete Ar BootVarNum
  81 Delete the given BootVar Num.
  82 .It Fl a -activate Ar BootVarNum
  83 Activate the given BootVarNum.
  84 .It Fl A -deactivate Ar BootVarNum
  85 Deactivate the given BootVarNum.
  86 .It Fl n -bootnext  Ar BootVarNum
  87 Set BootVarNum as the BootNext variable.
  88 .It Fl N -delete-bootnext
  89 Delete the BootNext optional BootVar.
  90 .It Fl o -bootorder Ar bootorder
  91 Set BootOrder variable to the given comma delimited set of BootVarNums.
  92 The numbers are in hex to match BootXXXX, but may omit leading zeros.
  93 .It Fl t -set-timeout Ar timeout
  94 Set the bootmenu timeout value.
  95 .It Fl T -del-timeout
  96 Delete the BootTimeout variable.
  97 .It Fl v -verbose
  98 Display the device path of BootVars in the output.
  99 .El
 100 .Pp
 101 .Sh Exammples
 102 .Pp
 103 To Display the current Boot related variables in the system:
 104 .Pp
 105 .Dl efibootmgr [-v]
 106 .Pp
 107 This will display the optional BootNext BootVar, BootCurrent,
 108 or currently booted BootVar, followed by the optional Timeout value, any
 109 BootOrder that maybe set, followed finally by all currently defined Boot
 110 variables, active or not. The verbose flag will augment this output with
 111 the hardrive partition uuids, size/offset and device-path of the
 112 variable.
 113 .Pp
 114 The
 115 .Nm
 116 program can be used to create new EFI boot variables. To create a new
 117 boot var pointing to an installation with its EFI partition mounted
 118 under /mnt, the given loader and a label "FreeBSD-11":
 119 .Pp
 120 .Dl efibootmgr -c -l /mnt/EFI/BOOT/BOOTX64.EFI -L FreeBSD-11
 121 .Pp
 122 This will result in the next available BootVarNum being assigned to a
 123 new UEFI load variable, and given the label "FreeBSD-11" such as:
 124 .Pp
 125 .Dl Boot0009 FreeBSD-11
 126 .Pp
 127 Note newly created BootVars are created inactive. The active state is denoted
 128 by an '*' following the BootVar name in the output.  They are also inserted
 129 into the first position of current BootOrder variable if it exists. They
 130 must first be set to active before being considered available to attempt booting from, else they
 131 are ignored.
 132 .Pp
 133 .Dl efibootmgr -B 0009
 134 .Pp
 135 Will delete the given BootVar Boot0009
 136 .Pp
 137 To set a given newly created BootVar active use:
 138 .Pp
 139 .Dl efibootmgr -a 0009
 140 .Pp
 141 To set a given BootVar to be used as the BootNext variable, irrespective
 142 of its active state, use:
 143 .Pp
 144 .Dl efibootmgr -n 0009
 145 .Pp
 146 To set the BootOrder for the next reboot  use:
 147 .Pp
 148 .Dl efibootmgr -o 0009,0003,...
 149 .Pp
 150 .Sh SEE ALSO
 151 .Xr efivar 8 ,
 152 .Xr uefi 8 ,
 153 .Xr gpart 8