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