Track FTL's OpenSSL, nghttp2 and nghttp3 dependencies in the compile guide - #1400
Open
DL6ER wants to merge 4 commits into
Open
Track FTL's OpenSSL, nghttp2 and nghttp3 dependencies in the compile guide#1400DL6ER wants to merge 4 commits into
DL6ER wants to merge 4 commits into
Conversation
✅ Deploy Preview for pihole-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
DL6ER
force-pushed
the
new/openssl
branch
2 times, most recently
from
July 10, 2026 18:12
7eddb99 to
797b5b5
Compare
DL6ER
changed the title
FTL's `development` branch links against OpenSSL 3.5 while `master` still uses mbedTLS. Document the OpenSSL 3.5.7 build (mirroring the `ftl-build` container, using `./config` for native host target auto-detection) next to the existing mbedTLS instructions, and note which branch needs which library. The mbedTLS section can be dropped once the next FTL release ships OpenSSL. Signed-off-by: DL6ER <dl6er@dl6er.de>
DL6ER
changed the title
DL6ER
changed the title
Member
Author
|
Should be merged after pi-hole/FTL#2941 has been merged as the text says that |
DL6ER
changed the title
Member
Author
|
Keeping both the mbedTLS and OpenSSL instructions on purpose for now (a bit of Zweigleisigkeit): FTL on Once the next FTL release (the one including the OpenSSL migration) is out, the mbedTLS section can be removed. Until then, having both does not hurt, which is why this PR no longer depends on pi-hole/FTL#2941 and can be merged at any time. |
FTL targets OpenSSL 4.0 (it ships SSL_get_peer_addr, which the later DoQ work needs). Bump the from-source instructions to 4.0.0 and drop no-ssl3 / no-engine from the config line: SSLv3 and the ENGINE API are already removed in 4.0, so both are only accepted there as deprecated Configure options. Signed-off-by: DL6ER <dl6er@dl6er.de>
The from-source guide now follows the `development` branch explicitly, with a note that it may not match `master` or older releases. Since `development` moved its webserver TLS stack to OpenSSL, remove the `libmbedtls` section and the master-vs-development hedge and keep OpenSSL as the single path. Also make the build feature-complete: call out OpenSSL 4.0 (with a note that an older 3.5.x works but disables the HTTP/3 and QUIC features), and add `nghttp2`/`nghttp3` from-source steps so a locally built binary serves HTTP/2 and HTTP/3 like the official release. Signed-off-by: DL6ER <dl6er@dl6er.de>
rdwebdesign
reviewed
Jul 26, 2026
yubiuser
reviewed
Jul 27, 2026
yubiuser
left a comment
yubiuser
left a comment
Member
There was a problem hiding this comment.
The whole ToC for this page is distorted. Install native build environment and Use containerized build environment are not part of the ToC. I suspect, it's because both use a level one heading. I think it would work, if all headings are moved one level down (# -> ##, ## -> ###,..)
`mkdocs` only renders a table of contents when a page has at most one first-order heading. `compile.md` had two (`Install native build environment` and `Use containerized build environment`), so the ToC came out distorted. Shift every heading down one level, matching what we already did for `signals.md`. Two more review points: 1. Drop the mbedTLS/OpenSSL example from the introductory note. The note is about `development` differing from `master` in general, and that particular difference disappears with the next release - without the example the note stays true indefinitely. 2. Turn the `Caution` section into a `!!! warning` admonition. It is a single-sentence aside, not a section of its own, and it no longer shows up in the ToC as a sibling of the real build steps. Signed-off-by: DL6ER <dl6er@dl6er.de>
DL6ER
changed the title
Member
Author
|
You are right about the cause. All headings moved down one level, same as we did for |
yubiuser
approved these changes
Aug 21, 2026
yubiuser
left a comment
yubiuser
left a comment
Member
There was a problem hiding this comment.
Thanks for taken some time to improve documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Both FTL PRs this documents are merged into
development: pi-hole/FTL#2941 (OpenSSL migration) and pi-hole/FTL#2976 (HTTP/2 and HTTP/3 webserver). This can be merged whenever.What
Brings the FTL compile-from-source guide in line with what
developmentactually builds against: OpenSSL instead of mbedTLS, plus the two newnghttp2/nghttp3dependencies. Also fixes the page's table of contents, which never rendered correctly.Details
OpenSSL replaces mbedTLS
libmbedtlssection is gone; aCompile OpenSSL from sourcesection takes its place. mbedTLS is no longer used anywhere indevelopment, so keeping both would only be confusing.ftl-buildcontainer's trimmedno-*configure flags (static-onlylibssl/libcrypto, no legacy provider, no unused protocols/ciphers, no DSO).no-ssl3andno-engineare dropped compared to the container's 3.x flags, as both are already removed in 4.0../config(auto target detection) rather than the container's per-archcase/./Configure- a native host build does not cross-compile.sedpatch is gone as well, as OpenSSL enables threading by default.make install_devinstalls only headers and static libraries, so noopensslCLI or man pages end up on the host.New
nghttp2andnghttp3sectionsFTL serves the web interface and the API over HTTP/2 and HTTP/3 now, so both libraries get their own build section. They are technically optional - without them FTL falls back to HTTP/1.1 - but we install both so a locally built binary matches the official release.
Which branch these instructions describe
A note at the top states that the guide follows
development, i.e., the code the next release is built from, and that other branches or older releases may need different dependencies. It deliberately avoids naming a concrete difference so it does not go stale after the next release.Table of contents
mkdocsonly renders a table of contents when a page has at most one first-order heading. This page had two (Install native build environmentandUse containerized build environment), so the ToC came out distorted. Every heading is shifted down one level, the same fix we applied tosignals.mdin b1e926c. TheCautionsection becomes a!!! warningadmonition on the way, as a single sentence does not warrant a section of its own.