Skip to content

Commit

Permalink
OpenNetworkBoot: Add PXE and HTTP(S) Boot support
Browse files Browse the repository at this point in the history
  • Loading branch information
@mikebeaton
mikebeaton committed Nov 20, 2024
1 parent 5d6759c commit fd7319b
Show file tree
Hide file tree
Showing 36 changed files with 3,506 additions and 623 deletions.
2 changes: 2 additions & 0 deletions Changelog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ OpenCore Changelog
- Added Arrow Lake CPU detection
- Fixed Raptor Lake CPU detection
- Supported booting with TuneD in Fedora 41 in OpenLinuxBoot
- Added OpenNetworkBoot driver to support HTTP(S) and PXE boot
- Supported DMG loading and verification (e.g. macOS Recovery) over HTTP(S) boot

#### v1.0.2
- Fixed error in macrecovery when running headless, thx @mkorje
Expand Down
138 changes: 137 additions & 1 deletion Docs/Configuration.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4119,6 +4119,7 @@ \subsection{Debug Properties}\label{miscdebugprops}
\item \texttt{HDA} --- AudioDxe
\item \texttt{KKT} --- KeyTester
\item \texttt{LNX} --- OpenLinuxBoot
\item \texttt{NTBT} --- OpenNetworkBoot
\item \texttt{MMDD} --- MmapDump
\item \texttt{OCPAVP} --- PavpProvision
\item \texttt{OCRST} --- ResetSystem
Expand Down Expand Up @@ -6579,6 +6580,9 @@ \subsection{Drivers}\label{uefidrivers}
& \hyperref[uefilinux]{OpenCore plugin} implementing \texttt{OC\_BOOT\_ENTRY\_PROTOCOL}
to allow direct detection and booting of Linux distributions from OpenCore, without
chainloading via GRUB. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenNetworkBoot}}\textbf{*}
& \hyperref[uefipxe]{OpenCore plugin} implementing \texttt{OC\_BOOT\_ENTRY\_PROTOCOL}
to show available PXE and HTTP(S) boot options on the OpenCore boot menu. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenNtfsDxe}}\textbf{*}
& New Technologies File System (NTFS) read-only driver.
NTFS is the primary file system for Microsoft Windows versions that are based on Windows NT. \\
Expand Down Expand Up @@ -7092,9 +7096,141 @@ \subsubsection{Additional information}
therefore \texttt{efibootmgr} rather than \texttt{bootctl} must be used for any low-level Linux command line interaction
with the boot menu.

\subsection{OpenNetworkBoot}\label{uefipxe}

OpenNetworkBoot is an OpenCore plugin implementing \texttt{OC\_BOOT\_ENTRY\_PROTOCOL}.
It enables PXE and HTTP(S) Boot options in the OpenCore menu if these
are supported by the underlying firmware, or if the required network boot drivers
have been loaded using OpenCore.

It has additional support for loading \texttt{.dmg} files and their associated
\texttt{.chunklist} file over HTTP(S) Boot, allowing macOS recovery to be
started over HTTP(S) Boot: if either extension is seen in the HTTP(S) Boot URI
then the other file of the pair is automatically loaded as well, and both are
passed to OpenCore to verify and boot from the DMG file.

PXE Boot is already supported on most firmware, so in most cases PXE Boot entries
should appear as soon as the driver is loaded. Using the additional network boot
drivers provided with OpenCore, when needed, HTTP(S) Boot should be available on
most firmware even if not natively supported.

Detailed information about the available network boot drivers and how to configure
PXE and HTTP(S) Boot is provided on
\href{https://github.com/acidanthera/OpenCorePkg/blob/master/Platform/OpenNetworkBoot/README.md}{this page}.

The following configuration options may be specified in the \texttt{Arguments} section for this driver:

\begin{itemize}
\item \texttt{-4} - Boolean flag, enabled if present. \medskip

If specified enable IPv4 for PXE and HTTP(S) Boot. Disable IPV6
unless the \texttt{-6} flag is also present. If neither flag is
present, both are enabled by default. \medskip

\item \texttt{-6} - Boolean flag, enabled if present. \medskip

If specified enable IPv6 for PXE and HTTP(S) Boot. Disable IPV4
unless the \texttt{-4} flag is also present. If neither flag is
present, both are enabled by default. \medskip

\item \texttt{-{}-aux} - Boolean flag, enabled if present. \medskip

If specified the driver will generate auxiliary boot entries. \medskip

\item \texttt{-{}-delete-all-certs[:\{OWNER\_GUID\}]} - Default: not set. \medskip

If specified, delete all certificates present for \texttt{OWNER\_GUID}.
\texttt{OWNER\_GUID} is optional, and will default to all zeros if not specified. \medskip

\item \texttt{-{}-delete-cert[:\{OWNER\_GUID\}]="\{cert-text\}"} - Default: not set. \medskip

If specified, delete the given certificate(s) for HTTPS Boot. The certificate(s) can be specified
as a multi-line PEM value between double quotes.
\texttt{OWNER\_GUID} is optional, and will default to all zeros if not specified.
A single PEM file can contain one or more certicates.
Multiple instances of this option can be used to delete multiple different
PEM files, if required.

\item \texttt{-{}-enroll-cert[:\{OWNER\_GUID\}]="\{cert-text\}"} - Default: not set. \medskip

If specified, enroll the given certificate(s) for HTTPS Boot. The certificate(s) can be specified
as a multi-line PEM value between double quotes.
\texttt{OWNER\_GUID} is optional, and will default to all zeros if not specified.
A single PEM file can contain one or more certicates.
Multiple instances of this option can be used to enroll multiple different
PEM files, if required. \medskip

\item \texttt{-{}-http} - Boolean flag, enabled if present. \medskip

If specified enable HTTP(S) Boot. Disable PXE Boot unless
the \texttt{-{}-pxe} flag is also present. If neither flag is
present, both are enabled by default. \medskip

\item \texttt{-{}-https} - Boolean flag, enabled if present. \medskip

If enabled, allow only \texttt{https://} URIs for HTTP(S) Boot.
Additionally has the same behaviour as the \texttt{-{}-http} flag. \medskip

\item \texttt{-{}-pxe} - Boolean flag, enabled if present. \medskip

If specified enable PXE Boot, and disable HTTP(S) Boot unless
the \texttt{-{}-http} or \texttt{-{}-https} flags are present.
If none of these flags are present, both PXE and HTTP(S) Boot are
enabled by default. \medskip

\item \texttt{-{}-uri} - String value, no default. \medskip

If present, specify the URI to use for HTTP(S) Boot. If not present then
DHCP boot options must be enabled on the network in order for HTTP(S)
Boot to know what to boot.

\end{itemize} \medskip

\subsubsection{OpenNetworkBoot Certificate Management}

Certificates are enrolled to NVRAM storage, therefore once
a certificate has been enrolled, it will remain enrolled even if the \texttt{-{}-enroll-cert} config
option is removed. \texttt{-{}-delete-cert} or \texttt{-{}-delete-all-certs}
should be used to remove enrolled certificates.

Checking for certificate presence by the \texttt{-{}-enroll-cert}
and \texttt{-{}-delete-cert} options uses the simple algorithm
of matching by exact file contents, not by file meaning. The intended
usage is to leave an \texttt{-{}-enroll-cert} option present in the config
file until it is time to delete it, e.g. after another more up-to-date
\texttt{-{}-enroll-cert} option has been added and tested. At this point
the user can change \texttt{-{}-enroll-cert} to \texttt{-{}-delete-cert}
for the old certificate. \medskip

Certificate options are processed one at a time, in
order, and each will potentially make changes to the certificate NVRAM storage.
However each option will not change the NVRAM store if it is already correct
for the option at that point in time (e.g. will not enroll a certificate if it is
already enrolled).
Avoid combinations such as \texttt{-{}-delete-all-certs} followed by
\texttt{-{}-enroll-cert}, as this will modify the NVRAM certificate
storage twice on every boot. However a combination such as
\texttt{-{}-delete-cert="\{certA-text\}"} followed by \texttt{-{}-enroll-cert="\{certB-text\}"}
(with \texttt{certA-text} and \texttt{certB-text} different) is safe,
because certA will only be deleted if it is present
and certB will only be added if it is not present, therefore no
NVRAM changes will be made on the second and subsequent boots
with these options.

In some cases (such as OVMF with https:// boot support) the
\texttt{OpenNetworkBoot} certificate configuration options manage the same
certificates as those seen in the firmware UI. In other cases of vendor customised
HTTPS Boot firmware, the certificates managed by this driver will be
separate from those managed by firmware.

When using the debug version of this driver, the OpenCore debug log includes \texttt{NTBT:} entries
that show which certificates are enrolled and removed by these options, and which
certificates are present after all certificate configuration options have been processed.

\subsection{Other Boot Entry Protocol drivers}

In addition to the \hyperref[uefilinux]{OpenLinuxBoot} plugin, the following \texttt{OC\_BOOT\_ENTRY\_PROTOCOL}
In addition to the \hyperref[uefilinux]{OpenLinuxBoot} and \hyperref[uefipxe]{OpenNetworkBoot} plugins,
the following \texttt{OC\_BOOT\_ENTRY\_PROTOCOL}
plugins are made available to add optional, configurable boot entries to the OpenCore boot picker.

\subsubsection{ResetNvramEntry}\label{uefiresetnvram}
Expand Down
24 changes: 19 additions & 5 deletions Docs/Flavours.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Icon pack authors are encouraged to provide only those icons for which there is

In the case of macOS only, a flavour based on the detected OS version is applied automatically (as shown below), and the user does not normally need to override this.

For icon pack authors, the **Apple** icon is recommended, **AppleRecovery** and **AppleTM** are suggested, all others are entirely optional.
For icon pack authors, the **Apple** icon is recommended, **AppleRecv** and **AppleTM** are suggested, all others are entirely optional.

- **Apple12:Apple** - Monterey (`Apple12.icns`)
- **Apple11:Apple** - Big Sur (`Apple11.icns`)
Expand Down Expand Up @@ -155,18 +155,31 @@ If providing `NVRAMTool.icns`, it should be themed so that it could be applied t
- **ResetNVRAM:NVRAMTool** - Reset NVRAM tool (`ResetNVRAM.icns`)
- This is the recommended flavour, used for the entry created by the `ResetNvramEntry.efi` driver.
- As another example of how flavours work: **ResetNVRAM:NVRAMTool** will look for `ResetNVRAM.icns`, then `NVRAMTool.icns` (and then, by OC default behaviour, `Tool.icns` then `HardDrive.icns`)
- **Note**: Including **ResetNVRAM** anywhere in a user flavour triggers picker audio-assist and builtin label support for "Reset NVRAM"
- **Note**: Including **ResetNVRAM** anywhere in a flavour triggers picker audio-assist and builtin label support for "Reset NVRAM"
- **ToggleSIP:NVRAMTool** - Icon themed for Toggle SIP tool (`ToggleSIP.icns`)
- **ToggleSIP_Enabled:ToggleSIP:NVRAMTool** - Icon themed for Toggle SIP tool when SIP is enabled (system is protected)
- **ToggleSIP_Disabled:ToggleSIP:NVRAMTool** - Icon themed for Toggle SIP tool when SIP is disabled (system is unprotected)
- **Note**: Including **ToggleSIP_Enabled** or **ToggleSIP_Disabled** anywhere in a user flavour triggers picker audio-assist and builtin label support for the two states of the Toggle SIP menu entry
- **Note**: Including **ToggleSIP_Enabled** or **ToggleSIP_Disabled** anywhere in a flavour triggers picker audio-assist and builtin label support for the two states of the Toggle SIP menu entry

### Network Boot

`OpenNetworkBoot.efi` uses the following flavours:

- **HttpBoot4:HttpBoot:NetworkBoot** - IPv4 HTTP(S) Boot
- **HttpBoot6:HttpBoot:NetworkBoot** - IPv6 HTTP(S) Boot
- **PxeBoot4:PxeBoot:NetworkBoot** - IPv4 PXE Boot
- **PxeBoot6:PxeBoot:NetworkBoot** - IPv6 PXE Boot

If none of these icons are available, network boot is treated like an external OS, so the fallbacks are **Other** followed by **HardDrive**.

- **Note**: Including **NetworkBoot** anywhere in a flavour triggers picker audio-assist and builtin label support for "Network Boot"

### Other Tools

A list of other known tools which are common enough that some icon pack artists may wish to provide a standard icon for them:

- **FirmwareSettings** - A boot menu entry for accessing firmware settings (`FirmwareSettings.icns`)
- **Note**: Including **FirmwareSettings** anywhere in a user flavour triggers picker audio-assist and builtin label support for "Firmware Settings"
- **FirmwareSettings** - A boot menu entry for accessing firmware settings, such as generated by `FirmwareSettingsEntry.efi` (`FirmwareSettings.icns`)
- **Note**: Including **FirmwareSettings** anywhere in a flavour triggers picker audio-assist and builtin label support for "Firmware Settings"
- **MemTest** - A system memory testing tool such as that available from [memtest86.com](https://www.memtest86.com/) (`MemTest.icns`)

## Bootloaders
Expand Down Expand Up @@ -198,6 +211,7 @@ Provided by OcBinaryData. Used automatically by OC in some circumstances, if pro
- **ExtAppleTM** - Apple Time Machine (on external drive) (fallback: **ExtHardDrive**)
- **Shell** - Shell tool (fallback: **Tool**)
- **Tool** - Generic tool (fallback: **HardDrive**)
- **Other** - Other OS (fallback: **HardDrive**)
- **Windows** - Microsoft Windows (fallback: **HardDrive**)

### Additional Optional
Expand Down
120 changes: 120 additions & 0 deletions Docs/Sample.plist
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1697,6 +1697,30 @@
<key>Path</key>
<string>Ext4Dxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
<key>Comment</key>
<string></string>
<key>Enabled</key>
<false/>
<key>LoadEarly</key>
<false/>
<key>Path</key>
<string>RngDxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
<key>Comment</key>
<string></string>
<key>Enabled</key>
<false/>
<key>LoadEarly</key>
<false/>
<key>Path</key>
<string>Hash2DxeCrypto.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
Expand Down Expand Up @@ -1781,6 +1805,66 @@
<key>Path</key>
<string>Udp4Dxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
<key>Comment</key>
<string></string>
<key>Enabled</key>
<false/>
<key>LoadEarly</key>
<false/>
<key>Path</key>
<string>Mtftp4Dxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
<key>Comment</key>
<string></string>
<key>Enabled</key>
<false/>
<key>LoadEarly</key>
<false/>
<key>Path</key>
<string>Dhcp6Dxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
<key>Comment</key>
<string></string>
<key>Enabled</key>
<false/>
<key>LoadEarly</key>
<false/>
<key>Path</key>
<string>Ip6Dxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
<key>Comment</key>
<string></string>
<key>Enabled</key>
<false/>
<key>LoadEarly</key>
<false/>
<key>Path</key>
<string>Udp6Dxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
<key>Comment</key>
<string></string>
<key>Enabled</key>
<false/>
<key>LoadEarly</key>
<false/>
<key>Path</key>
<string>Mtftp6Dxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
Expand All @@ -1793,6 +1877,18 @@
<key>Path</key>
<string>TcpDxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
<key>Comment</key>
<string></string>
<key>Enabled</key>
<false/>
<key>LoadEarly</key>
<false/>
<key>Path</key>
<string>UefiPxeBcDxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
Expand Down Expand Up @@ -1841,6 +1937,30 @@
<key>Path</key>
<string>HttpBootDxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
<key>Comment</key>
<string></string>
<key>Enabled</key>
<false/>
<key>LoadEarly</key>
<false/>
<key>Path</key>
<string>TlsDxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
<key>Comment</key>
<string></string>
<key>Enabled</key>
<false/>
<key>LoadEarly</key>
<false/>
<key>Path</key>
<string>RamDiskDxe.efi</string>
</dict>
<dict>
<key>Arguments</key>
<string></string>
Expand Down
Loading

0 comments on commit fd7319b

Please sign in to comment.