From 1e5ca0f9c4be5f61fe28d70547a2f2778eed0bf5 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Mon, 30 Jun 2025 13:31:09 +0200 Subject: [PATCH] Add webserver documentation Signed-off-by: DL6ER --- docs/ftldns/webserver.md | 40 ++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 +- 2 files changed, 41 insertions(+), 1 deletion(-) create mode 100644 docs/ftldns/webserver.md diff --git a/docs/ftldns/webserver.md b/docs/ftldns/webserver.md new file mode 100644 index 0000000..49e5525 --- /dev/null +++ b/docs/ftldns/webserver.md @@ -0,0 +1,40 @@ +### FTL's Embedded Webserver and Lua Server Pages + +FTL comes with the embedded webserver [CivetWeb](https://github.com/civetweb/civetweb) supporting Lua server pages (LSP). This means you can write dynamic web content directly using Lua scripts, similar to how PHP is used in traditional web development. Lua offers several advantages over PHP in the embedded context: + +- **Lightweight and Fast:** Lua has a very small memory footprint and is designed for high performance, making it ideal for our purposes. +- **Easy Integration:** Lua is easy to embed and extend, allowing seamless integration with FTL. We can easily bundle any Lua libraries we need, and they can be used directly in the webserver. No extra tools or external dependencies are required. +- **Simplicity:** Lua's syntax is straightforward and easy to learn, reducing the complexity of writing and maintaining server-side scripts. +- **Security:** Running Lua scripts within the FTL webserver provides a controlled environment, minimizing potential security risks compared to running a full PHP interpreter. + +--- + +You can use the webserver to serve static files, dynamic content, or even custom HTTP responses (see the following examples). The webserver is configured through `pihole.toml` and can be accessed at `https://pi.hole/admin/`. Serving files outside of the webserver's home directory (`admin/`) is disabled by default for security reasons. It can be enabled by setting `webserver.serve_all` to `true`. + +### Example 1: Custom HTTP status code + +Create a file like + +``` plain +HTTP/1.1 204 No Content +Connection: close +Cache-Control: max-age=0, must-revalidate + +``` + +Two important things here: You need to save it using "MS-DOS formatting" (`\r\n` line endings) and there needs to be a single trailing line. + +### Example 2: Regular page but manual headers + +You could also use it for "regular" pages, e.g., + +``` plain +HTTP/1.0 200 OK +Content-Type: text/html + + +

+ +``` + +which will print an empty page with "2" on it. diff --git a/mkdocs.yml b/mkdocs.yml index e8084aa..60a0af6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -142,6 +142,7 @@ nav: - 'Blocking mode': ftldns/blockingmode.md - 'Privacy levels': ftldns/privacylevels.md - 'dnsmasq warnings': ftldns/dnsmasq_warn.md + - 'Webserver': ftldns/webserver.md - 'Advanced': - 'Install from source': ftldns/compile.md - 'Signals': 'ftldns/signals.md' @@ -246,7 +247,6 @@ plugins: - redirects: redirect_maps: 'ftldns/database.md': database/index.md - 'ftldns/regex/index.md': ftldns/regex/overview.md 'main/presentations.md': index.md 'main/prerequesites.md': main/prerequisites.md 'guides/unbound.md': guides/dns/unbound.md