From ed766339839c8b2c609549df4bdebb0e415cc83c Mon Sep 17 00:00:00 2001 From: DL6ER Date: Fri, 10 Jul 2026 11:09:59 +0200 Subject: [PATCH 1/4] Add OpenSSL from-source build instructions alongside mbedTLS 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 --- docs/ftldns/compile.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/ftldns/compile.md b/docs/ftldns/compile.md index ac2b95c94..1039459b0 100644 --- a/docs/ftldns/compile.md +++ b/docs/ftldns/compile.md @@ -37,9 +37,11 @@ sudo make install Since Ubuntu 20.04, you need to specify the library directory explicitly. Otherwise, the library will be installed in custom locations where it would not be found by `cmake`. +FTL needs one of the following two cryptographic libraries for serving the web interface and the API over HTTPS. Which one you need depends on the branch you build (see [Get the source](#get-the-source) below): the `master` branch still links against mbedTLS, while the `development` branch - and the upcoming release - uses OpenSSL. Compiling the matching library is enough, though installing both does no harm. + ## Compile `libmbedtls` from source -FTL uses another cryptographic library (`libmbedtls`) containing cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols used for serving the web interface and the API over HTTPS. +FTL uses this cryptographic library (`libmbedtls`) containing cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols used for serving the web interface and the API over HTTPS. Compile and install a recent version using: @@ -56,6 +58,28 @@ sudo cmake --install build The `sed` commands are necessary to enable multi-threading support in `libmbedtls` as there is no `configure` script to do this for us (see also [here](https://github.com/Mbed-TLS/mbedtls#configuration)). +## Compile `OpenSSL` from source + +FTL uses this cryptographic library (OpenSSL) containing cryptographic primitives, X.509 certificate manipulation and the SSL/TLS protocols used for serving the web interface and the API over HTTPS. + +Compile and install a recent version using: + +```bash +wget https://github.com/openssl/openssl/releases/download/openssl-3.5.7/openssl-3.5.7.tar.gz -O openssl-3.5.7.tar.gz +tar -xzf openssl-3.5.7.tar.gz +cd openssl-3.5.7 +./config \ + no-shared no-tests no-docs no-apps \ + no-legacy no-comp no-dtls no-ssl3 \ + no-psk no-srp no-idea no-rc2 no-rc4 no-rc5 no-md4 no-mdc2 no-whirlpool \ + no-engine no-dso \ + --prefix=/usr/local --libdir=lib --openssldir=/usr/local/ssl +make -j $(nproc) +sudo make install_dev +``` + +`./config` auto-detects the correct build target for your host, so no per-architecture tuning is needed. The `no-*` options trim the build down to just the static `libssl`/`libcrypto` that FTL links against, dropping the legacy provider, unused protocols and ciphers, engines and DSO to keep the binary small. Multi-threading support is enabled by default, so no manual configuration is required. `make install_dev` installs only the headers and static libraries (no `openssl` command-line tool or man pages). + ## Get the source Now, clone the FTL repo (or your own fork) to get the source code of FTL: From 5a0e7341e68e5896b3d4d30c6737291ede911b0f Mon Sep 17 00:00:00 2001 From: DL6ER Date: Tue, 21 Jul 2026 21:20:00 +0200 Subject: [PATCH 2/4] compile: build OpenSSL 4.0 from source instead of 3.5 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 --- docs/ftldns/compile.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/ftldns/compile.md b/docs/ftldns/compile.md index 1039459b0..568d00ad7 100644 --- a/docs/ftldns/compile.md +++ b/docs/ftldns/compile.md @@ -65,20 +65,20 @@ FTL uses this cryptographic library (OpenSSL) containing cryptographic primitive Compile and install a recent version using: ```bash -wget https://github.com/openssl/openssl/releases/download/openssl-3.5.7/openssl-3.5.7.tar.gz -O openssl-3.5.7.tar.gz -tar -xzf openssl-3.5.7.tar.gz -cd openssl-3.5.7 +wget https://ftl.pi-hole.net/libraries/openssl-4.0.0.tar.gz -O openssl-4.0.0.tar.gz +tar -xzf openssl-4.0.0.tar.gz +cd openssl-4.0.0 ./config \ no-shared no-tests no-docs no-apps \ - no-legacy no-comp no-dtls no-ssl3 \ + no-legacy no-comp no-dtls \ no-psk no-srp no-idea no-rc2 no-rc4 no-rc5 no-md4 no-mdc2 no-whirlpool \ - no-engine no-dso \ + no-dso \ --prefix=/usr/local --libdir=lib --openssldir=/usr/local/ssl make -j $(nproc) sudo make install_dev ``` -`./config` auto-detects the correct build target for your host, so no per-architecture tuning is needed. The `no-*` options trim the build down to just the static `libssl`/`libcrypto` that FTL links against, dropping the legacy provider, unused protocols and ciphers, engines and DSO to keep the binary small. Multi-threading support is enabled by default, so no manual configuration is required. `make install_dev` installs only the headers and static libraries (no `openssl` command-line tool or man pages). +`./config` auto-detects the correct build target for your host, so no per-architecture tuning is needed. The `no-*` options trim the build down to just the static `libssl`/`libcrypto` that FTL links against, dropping the legacy provider, unused protocols and ciphers, and DSO to keep the binary small (`no-ssl3` and `no-engine` are not needed on OpenSSL 4.0 - SSLv3 and the ENGINE API are already removed there). Multi-threading support is enabled by default, so no manual configuration is required. `make install_dev` installs only the headers and static libraries (no `openssl` command-line tool or man pages). ## Get the source From efc76de0c48b60c20e3d41af94848f7f98fe6b88 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Sun, 26 Jul 2026 13:31:16 +0200 Subject: [PATCH 3/4] compile: track development on OpenSSL, drop mbedTLS 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 --- docs/ftldns/compile.md | 59 ++++++++++++++++++++++++++---------------- 1 file changed, 37 insertions(+), 22 deletions(-) diff --git a/docs/ftldns/compile.md b/docs/ftldns/compile.md index 568d00ad7..6c1da3ad1 100644 --- a/docs/ftldns/compile.md +++ b/docs/ftldns/compile.md @@ -1,5 +1,8 @@ We pre-compile FTL for you to save you the trouble of compiling anything yourself. However, sometimes you may want to make your own modifications. To test them, you have to compile FTL from source. Luckily, you don't have to be a programmer to build FTL from source and install it on your system; you only have to know the basics we provide in here. With just a few commands, you can build FTL from source like a pro. +!!! note + These instructions follow FTL's `development` branch - the code the next release is built from. They are not guaranteed to match the current `master` branch or older releases, whose build dependencies can differ (for example, `master` still links mbedTLS while `development` has moved to OpenSSL). If you are building a different branch and something does not line up, just ask us - we are happy to help with the specifics. + # Install native build environment This will install all necessary tools to build FTL directly in your host operating system. It is usually the easiest solution and works with all editors available. @@ -37,30 +40,9 @@ sudo make install Since Ubuntu 20.04, you need to specify the library directory explicitly. Otherwise, the library will be installed in custom locations where it would not be found by `cmake`. -FTL needs one of the following two cryptographic libraries for serving the web interface and the API over HTTPS. Which one you need depends on the branch you build (see [Get the source](#get-the-source) below): the `master` branch still links against mbedTLS, while the `development` branch - and the upcoming release - uses OpenSSL. Compiling the matching library is enough, though installing both does no harm. - -## Compile `libmbedtls` from source - -FTL uses this cryptographic library (`libmbedtls`) containing cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols used for serving the web interface and the API over HTTPS. - -Compile and install a recent version using: - -```bash -wget https://github.com/Mbed-TLS/mbedtls/releases/download/mbedtls-4.0.0/mbedtls-4.0.0.tar.bz2 -O mbedtls-4.0.0.tar.bz2 -tar -xjf mbedtls-4.0.0.tar.bz2 -cd mbedtls-4.0.0 -sed -i '/#define MBEDTLS_THREADING_C/s*^//**g' tf-psa-crypto/include/psa/crypto_config.h -sed -i '/#define MBEDTLS_THREADING_PTHREAD/s*^//**g' tf-psa-crypto/include/psa/crypto_config.h -cmake -S . -B build -DCMAKE_C_FLAGS="-fomit-frame-pointer" -cmake --build build -j $(nproc) -sudo cmake --install build -``` - -The `sed` commands are necessary to enable multi-threading support in `libmbedtls` as there is no `configure` script to do this for us (see also [here](https://github.com/Mbed-TLS/mbedtls#configuration)). - ## Compile `OpenSSL` from source -FTL uses this cryptographic library (OpenSSL) containing cryptographic primitives, X.509 certificate manipulation and the SSL/TLS protocols used for serving the web interface and the API over HTTPS. +FTL uses this cryptographic library (OpenSSL) containing cryptographic primitives, X.509 certificate manipulation and the SSL/TLS protocols used for serving the web interface and the API over HTTPS. Build **OpenSSL 4.0** here: it is the version FTL is developed against and the one that provides the native QUIC API the HTTP/3 features rely on. Compile and install a recent version using: @@ -80,6 +62,39 @@ sudo make install_dev `./config` auto-detects the correct build target for your host, so no per-architecture tuning is needed. The `no-*` options trim the build down to just the static `libssl`/`libcrypto` that FTL links against, dropping the legacy provider, unused protocols and ciphers, and DSO to keep the binary small (`no-ssl3` and `no-engine` are not needed on OpenSSL 4.0 - SSLv3 and the ENGINE API are already removed there). Multi-threading support is enabled by default, so no manual configuration is required. `make install_dev` installs only the headers and static libraries (no `openssl` command-line tool or man pages). +!!! note "Building against an older OpenSSL" + An older OpenSSL such as 3.5.7 works too, but it lacks the per-connection QUIC peer-address API FTL relies on, so building against it disables the HTTP/3 and QUIC features (HTTP/1.1 and HTTP/2 remain available). Use OpenSSL 4.0 for a feature-complete binary. + +## Compile `nghttp2` from source + +FTL uses `nghttp2` to serve the web interface and the API over HTTP/2. Compile and install a recent version using: + +```bash +wget https://ftl.pi-hole.net/libraries/nghttp2-1.69.0.tar.gz -O nghttp2-1.69.0.tar.gz +tar -xzf nghttp2-1.69.0.tar.gz +cd nghttp2-1.69.0 +./configure --enable-lib-only --enable-static --disable-shared +make -j $(nproc) +sudo make install +``` + +`--enable-lib-only` builds just the `libnghttp2` library FTL links against, skipping the bundled applications and their extra dependencies. + +## Compile `nghttp3` from source + +FTL uses `nghttp3` together with OpenSSL's native QUIC to serve the web interface and the API over HTTP/3. Compile and install a recent version using: + +```bash +wget https://ftl.pi-hole.net/libraries/nghttp3-1.17.0.tar.gz -O nghttp3-1.17.0.tar.gz +tar -xzf nghttp3-1.17.0.tar.gz +cd nghttp3-1.17.0 +./configure --enable-lib-only --enable-static --disable-shared +make -j $(nproc) +sudo make install +``` + +`nghttp2` and `nghttp3` are technically optional - without them FTL still builds and serves the web interface over HTTP/1.1 - but we install both here so the locally built binary is feature-complete and matches the official release (HTTP/1.1, HTTP/2 and, with OpenSSL 4.0, HTTP/3). + ## Get the source Now, clone the FTL repo (or your own fork) to get the source code of FTL: From dd2bf7d9d6a0a6f51204f89fa5162b716f60a62a Mon Sep 17 00:00:00 2001 From: DL6ER Date: Sun, 9 Aug 2026 11:26:50 +0200 Subject: [PATCH 4/4] compile: fix the table of contents and apply review suggestions `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 --- docs/ftldns/compile.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/ftldns/compile.md b/docs/ftldns/compile.md index 6c1da3ad1..c64e973cc 100644 --- a/docs/ftldns/compile.md +++ b/docs/ftldns/compile.md @@ -1,30 +1,30 @@ We pre-compile FTL for you to save you the trouble of compiling anything yourself. However, sometimes you may want to make your own modifications. To test them, you have to compile FTL from source. Luckily, you don't have to be a programmer to build FTL from source and install it on your system; you only have to know the basics we provide in here. With just a few commands, you can build FTL from source like a pro. !!! note - These instructions follow FTL's `development` branch - the code the next release is built from. They are not guaranteed to match the current `master` branch or older releases, whose build dependencies can differ (for example, `master` still links mbedTLS while `development` has moved to OpenSSL). If you are building a different branch and something does not line up, just ask us - we are happy to help with the specifics. + These instructions follow FTL's `development` branch - the code the next release is built from. They are not guaranteed to match the current `master` branch or older releases, whose build dependencies can differ. If you are building a different branch and something does not line up, just ask us - we are happy to help with the specifics. -# Install native build environment +## Install native build environment This will install all necessary tools to build FTL directly in your host operating system. It is usually the easiest solution and works with all editors available. -## Installing the Required Software +### Installing the Required Software First, we'll install the basic software you'll need to compile from source, like the GCC compiler and other utilities. Install them by running the following command in a terminal: -### Debian / Ubuntu / Raspbian +#### Debian / Ubuntu / Raspbian ```bash sudo apt install git wget ca-certificates build-essential libgmp-dev m4 cmake libidn2-dev libunistring-dev libreadline-dev xxd ``` -### Fedora +#### Fedora ```bash sudo dnf install git wget ca-certificates gcc gmp-devel gmp-static m4 cmake libidn2-devel libunistring-devel readline-devel xxd ``` -## Compile `libnettle` from source +### Compile `libnettle` from source FTL uses a cryptographic library (`libnettle`) for handling DNSSEC signatures. Compile and install a recent version using: @@ -40,7 +40,7 @@ sudo make install Since Ubuntu 20.04, you need to specify the library directory explicitly. Otherwise, the library will be installed in custom locations where it would not be found by `cmake`. -## Compile `OpenSSL` from source +### Compile `OpenSSL` from source FTL uses this cryptographic library (OpenSSL) containing cryptographic primitives, X.509 certificate manipulation and the SSL/TLS protocols used for serving the web interface and the API over HTTPS. Build **OpenSSL 4.0** here: it is the version FTL is developed against and the one that provides the native QUIC API the HTTP/3 features rely on. @@ -65,7 +65,7 @@ sudo make install_dev !!! note "Building against an older OpenSSL" An older OpenSSL such as 3.5.7 works too, but it lacks the per-connection QUIC peer-address API FTL relies on, so building against it disables the HTTP/3 and QUIC features (HTTP/1.1 and HTTP/2 remain available). Use OpenSSL 4.0 for a feature-complete binary. -## Compile `nghttp2` from source +### Compile `nghttp2` from source FTL uses `nghttp2` to serve the web interface and the API over HTTP/2. Compile and install a recent version using: @@ -80,7 +80,7 @@ sudo make install `--enable-lib-only` builds just the `libnghttp2` library FTL links against, skipping the bundled applications and their extra dependencies. -## Compile `nghttp3` from source +### Compile `nghttp3` from source FTL uses `nghttp3` together with OpenSSL's native QUIC to serve the web interface and the API over HTTP/3. Compile and install a recent version using: @@ -95,7 +95,7 @@ sudo make install `nghttp2` and `nghttp3` are technically optional - without them FTL still builds and serves the web interface over HTTP/1.1 - but we install both here so the locally built binary is feature-complete and matches the official release (HTTP/1.1, HTTP/2 and, with OpenSSL 4.0, HTTP/3). -## Get the source +### Get the source Now, clone the FTL repo (or your own fork) to get the source code of FTL: @@ -109,7 +109,7 @@ If you want to build another branch and not `master`, use checkout to get to thi git checkout development ``` -## Compile the source +### Compile the source FTL can now be compiled using either the build script @@ -127,7 +127,7 @@ cmake --build . -- -j $(nproc) Note that both ways are exactly equivalent and that you do not need `root` privileges here. -## Install the new binary system-wide +### Install the new binary system-wide Install the new binary using either @@ -147,11 +147,10 @@ Finally, restart FTL to use the new binary: sudo service pihole-FTL restart ``` -## Caution +!!! warning + Once your homebrew `pihole-FTL` binary is built and installed, do not run `pihole -up` or `pihole checkout`. These commands might overwrite your local `pihole-FTL` binary with Pi-hole's pre-compiled binaries. -Once your homebrew `pihole-FTL` binary is built and installed, do not run `pihole -up` or `pihole checkout`. These commands might overwrite your local `pihole-FTL` binary with Pi-hole's pre-compiled binaries. - -# Use containerized build environment +## Use containerized build environment While most people think of [Docker](https://www.docker.com/) as a deployment environment, it's also a wonderful tool to create and maintain build environments. Pi-hole provides `ftl-build` containers composed of everything needed to build FTL for various architectures on your `x86_64` hosts. Check out [Docker Hub `pi-hole/ftl-build`](https://hub.docker.com/r/pihole/ftl-build/tags) for the available build containers as well as the [Releases overview](https://github.com/pi-hole/docker-base-images/releases/) for a detailed changelog.