From a8b672c388e0698eb97f7fcd5b8e397c093faa8a Mon Sep 17 00:00:00 2001
From: DL6ER <16748619+DL6ER@users.noreply.github.com>
Date: Sat, 19 Sep 2026 19:13:05 +0000
Subject: [PATCH] docs: update pihole.toml documentation

---
 docs/ftldns/configfile.md | 59 ++++++++++++++++++++++++++++-----------
 1 file changed, 43 insertions(+), 16 deletions(-)

diff --git a/docs/ftldns/configfile.md b/docs/ftldns/configfile.md
index 710e04c7..7c9a51dc 100644
--- a/docs/ftldns/configfile.md
+++ b/docs/ftldns/configfile.md
@@ -2669,37 +2669,41 @@ true or false
 Additional options passed directly to the web server.
 
 This can be used to set any option supported by the underlying web server
-(CivetWeb). See the CivetWeb documentation for a list of supported options. The
-options are passed as an array of strings, where each string is an option in the
-form `"<option>=<value>"`. Be aware that this is an advanced option and that setting
-options here may break the web server if invalid or conflicting with other settings
-applied based on other settings in this file. The config options specified here are
-added to the end of the passed options. This makes it possible to overwrite settings
-set by Pi-hole (only the last values is used when a config option is specified
-multiple times). Use with caution.
+(CivetWeb). The options are passed as an array of strings, where each string is an
+option in the form `"<option>=<value>"`. The config options specified here are added
+to the end of the passed options. This makes it possible to overwrite settings set
+by Pi-hole (only the last value is used when a config option is specified multiple
+times). Use with caution: setting options here may break the web server if they
+conflict with other settings applied based on other settings in this file.
 
-**Example:** `[ "ssl_protocol_version=4", "ssl_cipher_list=AES128:!MD5" ]`
+Options given here reach the web server unchecked, and some of them decide which
+files it serves or executes, so this option cannot be set through the API. Set it in
+/etc/pihole/pihole.toml, through an environment variable, or with `"pihole-FTL
+
+--config"` - all of which require access to the host.
+
+**Example:** `[ "num_threads=8", "max_request_size=32768" ]`
 
 **Allowed values are:**
-An array of valid CivetWeb options
+An array of permitted CivetWeb options
 
 **Default value:** `[]`
 
 === "TOML"
     ```toml
     [webserver]
-      advancedOpts = [ "ssl_protocol_version=4", "ssl_cipher_list=AES128:!MD5" ]
+      advancedOpts = [ "num_threads=8", "max_request_size=32768" ]
     ```
 === "CLI"
     ```shell
-    sudo pihole-FTL --config webserver.advancedOpts '[ "ssl_protocol_version=4", "ssl_cipher_list=AES128:!MD5" ]'
+    sudo pihole-FTL --config webserver.advancedOpts '[ "num_threads=8", "max_request_size=32768" ]'
     ```
 === "Environment (Docker Compose)"
     ```yaml
     environment:
       FTLCONF_webserver_advancedOpts: |-
-        ssl_protocol_version=4
-        ssl_cipher_list=AES128:!MD5
+        num_threads=8
+        max_request_size=32768
     ```
 
 
@@ -2840,10 +2844,18 @@ roughly 30 years for the certificate.
 
 ### `webroot`
 
-Server root on the host
+Server root on the host.
+
+Every file below this directory can be requested over the network once
+webserver.serve_all is enabled, so it cannot be `"/"` or any other directory
+containing `"/etc/pihole"`.
+
+Relocating the document root decides which files the web server serves, so it cannot
+be set through the API. Set it in /etc/pihole/pihole.toml, through an environment
+variable, or with `"pihole-FTL --config"` - all of which require access to the host.
 
 **Allowed values are:**
-A valid path
+A valid absolute path not containing `"/etc/pihole"`
 
 **Default value:** `"/var/www/html"`
 
@@ -2866,6 +2878,10 @@ A valid path
 
 Sub-directory of the root containing the web interface
 
+This decides where the web server serves the interface from, so it cannot be set
+through the API. Set it in /etc/pihole/pihole.toml, through an environment variable,
+or with `"pihole-FTL --config"` - all of which require access to the host.
+
 **Allowed values are:**
 A valid subpath, both slashes are needed!
 
@@ -2902,6 +2918,10 @@ empty. Setting this field to an incorrect value may result in the web interface
 being accessible.
 Don't use this setting if you are not using a reverse proxy!
 
+This decides where the web server serves the interface from, so it cannot be set
+through the API. Set it in /etc/pihole/pihole.toml, through an environment variable,
+or with `"pihole-FTL --config"` - all of which require access to the host.
+
 **Allowed values are:**
 A valid URL prefix or empty
 
@@ -3825,6 +3845,13 @@ from working.
 
 Use this option with extra care.
 
+dnsmasq directives such as `"dhcp-script"` and `"conf-script"` name programs that
+dnsmasq then executes, so this option cannot be set through the API. Set it in
+/etc/pihole/pihole.toml, through an environment variable, or with `"pihole-FTL
+
+--config"` - all of which require access to the host, which anyone placing such a
+script has anyway.
+
 **Example:** `[ "address=/example.com/192.168.0.1", "address=/example.org/192.168.0.2",
 "address=/example.net/192.168.0.3" ]`