Merge branch 'master' into release/FTL_v5.14

2024-12-06 19:27:12 +01:00 · 2022-02-12 23:19:46 +01:00
parent ea1ae69799 aeb083a799
commit 4b14f72c81
7 changed files with 83 additions and 23 deletions
@@ -39,6 +39,7 @@ The default settings for FTL's rate-limiting are to permit no more than `1000` q
 It is important to note that rate-limiting is happening on a *per-client* basis. Other clients can continue to use FTL while rate-limited clients are short-circuited at the same time.

 For this setting, both numbers, the maximum number of queries within a given time, **and** the length of the time interval (seconds) have to be specified. For instance, if you want to set a rate limit of 1 query per hour, the option should look like `RATE_LIMIT=1/3600`.
+The time interval is relative to when FTL has finished starting (start of the daemon + possible delay by DELAY_STARTUP)  then it will advance in steps of the rate-limiting interval. If a client reaches the maximum number of queries it will be blocked until **the end of the current interval**. This will be logged to `/var/log/pihole-FTL.log`, e.g. `Rate-limiting 10.0.1.39 for at least 44 seconds`. If the client continues to send queries while being blocked already and this number of queries during the blocking exceeds the limit the client will continue to be blocked **until the end of the next interval** (`pihole-FTL.log` will contain lines like `Still rate-limiting 10.0.1.39 as it made additional 5007 queries`).  As soon as the client requests less than the set limit, it will be unblocked (`Ending rate-limitation of 10.0.1.39`).

 Rate-limiting may be disabled altogether by setting `RATE_LIMIT=0/0` (this results in the same behavior as before FTL v5.7).

@@ -0,0 +1,34 @@
+## Pi-hole FTL's internal pcap packet dump
+
+Pi-hole has its own embedded package dumping. It can be enabled by adding the following to a file like `/etc/dnsmasq.d/99-record.conf`:
+
+```
+dumpfile=/etc/pihole/dump.pcap
+```
+
+(or any other location you prefer), in addition to
+
+```
+dumpmask=<mask>
+```
+
+where `mask` specifies which types of packets should be added to the dumpfile defined above. The argument should be the OR of the bitmasks for each type of packet to be dumped: it can be specified in hex by preceding the number with 0x in the normal way.
+Each time a packet is written to the dumpfile, we log the packet sequence and the mask representing its type. The current types are:
+
+- `0x0001` - DNS queries from clients
+- `0x0002` - DNS replies to clients
+- `0x0004` - DNS queries to upstream
+- `0x0008` - DNS replies from upstream
+- `0x0010` - queries send upstream for DNSSEC validation
+- `0x0020` - replies to queries for DNSSEC validation
+- `0x0040` - replies to client queries which fail DNSSEC validation
+- `0x0080` - replies to queries for DNSSEC validation which fail validation.
+
+If you just want to record everything and later filter this in Wireshark you can just add the two lines
+
+```
+dumpfile=/etc/pihole/dump.pcap
+dumpmask=0x00ff
+```
+
+{!abbreviations.md!}
@@ -112,7 +112,7 @@ After a restart, the server file should look like:

 ```plain
 [Interface]
-Address = 10.100.0.1/24, fd08::1/128
+Address = 10.100.0.1/24, fd08:4711::1/128
 ListenPort = 47111
 PrivateKey = XYZ123456ABC=                   # PrivateKey will be different

@@ -140,7 +140,7 @@ interface: wg0

 peer: F+80gbmHVlOrU+es13S18oMEX2g=   ⬅ Your peer's public key will be different
  preshared key: (hidden)
-  allowed ips: 10.100.0.2/32, fd08::2/128
+  allowed ips: 10.100.0.2/32, fd08:4711::2/128
 ```

 ## Create client configuration
@@ -163,7 +163,7 @@ Next, add your server as peer for this client:

 ```plain
 [Peer]
-AllowedIPs = 10.100.0.1/32, fd08::1/128
+AllowedIPs = 10.100.0.1/32, fd08:4711::1/128
 Endpoint = [your public IP or domain]:47111
 PersistentKeepalive = 25
 ```
@@ -100,7 +100,7 @@ It is possible to add this only for a few clients, leaving the others isolated t
    DNS = 10.100.0.1

    [Peer]
-    AllowedIPs = 10.100.0.0/24, fd08::/64, 192.168.2.0/24
+    AllowedIPs = 10.100.0.0/24, fd08:4711::/64, 192.168.2.0/24
    Endpoint = [your server's public IP or domain]:47111
    PublicKey = [public key of the server]
    PresharedKey = [pre-shared key of this client]
@@ -54,31 +54,54 @@ Ask the list maintainer to convert the IDNs to their punycode representation.
 Internationalizing Domain Names in Applications (IDNA) was conceived to allow client-side use of language-specific characters in domain names without requiring any existing infrastructure (DNS servers, mall servers, etc., including associated protocols) to change. Accordingly, the corresponding original [RFC 3490](https://tools.ietf.org/html/rfc3490) clearly states that IDNA is employed at application level, not on the server side.
 Hence, DNS servers never see any IDN domain name, which means DNS records do not store IDN domain names at all, only their [Punycode](https://en.wikipedia.org/wiki/Punycode)  representations.

-### While loading data from the long-term database you encountered an error
+### Error while loading data from the long-term database

 If requesting a lot of data from the long-term database you get this error

 ```code
 An unknown error occurred while loading the data.
-Check the server's log files (/var/log/lighttpd/error.log when you're using the default Pi-hole web server) for details. You may need to increase the memory available for Pi-hole in case you requested a lot of data.
+
+Check the server's log files (/var/log/lighttpd/error.log) for details.
+
+You may need to increase PHP memory limit.
+
+You can find more info in pi-hole's FAQ:
+https://docs.pi-hole.net/main/faq/#error-while-loading-data-from-the-long-term-database
 ```

 **Solution:**

-Increase PHP's memory and restart the server.
+You need to increase PHP's memory and restart the server.

-Replace `*` with your installed PHP version (e.g. `.../php/7.3/cgi/...`) to edit the file. Increase the `memory_limit`. You can use common abbreviation (M= megabyte, G= gigabyte). The amount of memory needed depends on many factors, e.g. availabe system RAM, other processes running on your device, the amount of data you want to process. Do not assign all availabe memory as this can freeze your system. One approache would be to double the limit and check if it might be already sufficient to retrieve the data. If not, add another 128M, check again, add another 128M,....
+The amount of memory needed depends on many factors:
+
+- availabe system RAM,
+- other processes running on your device,
+- the amount of data you want to process.
+
+One aproach would be to increase the limit by 128M and check if it was enough to retrieve the data.
+If not, add another 128M, check again. If not, add another 128M, check again, until you find the best value.
+
+_Note:_
+Do not assign all availabe memory as this can freeze your system.
 Please consider the possibility that your system does not have enough memory at all to load all the needed data.

+_Steps to increase `memory_limit`:_
+
+Open or create `.user.ini` file:
+
 ```bash
-sudo nano /etc/php/*/cgi/php.ini
-[..]
-; Maximum amount of memory a script may consume (128MB)
-; http://php.net/memory-limit
-memory_limit = 128M
-[..]
+sudo nano /var/www/html/.user.ini
 ```

+Add (or change) the memory limit (common abbreviation M=megabyte, G=gigabyte):
+
+```ini
+memory_limit = 256M
+```
+
+Restart the web server:
+
 ```bash
 sudo service lighttpd restart
 ```
@@ -108,16 +108,18 @@ nav:
    - 'DNS cache': ftldns/dns-cache.md
    - 'Blocking mode': ftldns/blockingmode.md
    - 'Privacy levels': ftldns/privacylevels.md
-    - 'Telnet API': ftldns/telnet-api.md
-    - 'Signals': 'ftldns/signals.md'
    - 'Compatibility': ftldns/compatibility.md
-    - 'Install from source': ftldns/compile.md
    - 'dnsmasq warnings': ftldns/dnsmasq_warn.md
-    - 'Cache dump': ftldns/cache_dump.md
-    - 'Debugging FTLDNS':
-      - 'gdb': ftldns/debugging.md
-      - 'valgrind': ftldns/valgrind.md
-    - 'In-depth manual': ftldns/in-depth.md
+    - 'Advanced':
+        - 'Install from source': ftldns/compile.md
+        - 'Telnet API': ftldns/telnet-api.md
+        - 'Signals': 'ftldns/signals.md'
+        - 'Cache dump': ftldns/cache_dump.md
+        - 'Packet dump': ftldns/package_dump.md
+        - 'Debugging':
+            - 'gdb': ftldns/debugging.md
+            - 'valgrind': ftldns/valgrind.md
+        - 'In-depth manual': ftldns/in-depth.md
  - 'RegEx blocking':
    - "Overview": regex/overview.md
    - "Testing": regex/testmode.md
@@ -1,5 +1,5 @@
 markdown-include==0.6.0
 mkdocs==1.2.3
 mkdocs-git-revision-date-localized-plugin==0.11.1
-mkdocs-material==8.1.8
+mkdocs-material==8.1.9
 mkdocs-redirects==1.0.3