pi-hole/docs
1
0
Fork 0
mirror of https://github.com/pi-hole/docs.git synced 2024-12-06 19:27:12 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge branch 'master' into dependabot/npm_and_yarn/linkinator-3.0.0

Browse Source
This commit is contained in:
DL6ER
2021-12-23 11:19:46 +01:00
committed by GitHub
parent 9ea31a8489 aef00f7a32
commit f0ad328b73
9 changed files with 293 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/extra.css
-1
View File
@@ -14,7 +14,6 @@
.md-typeset code,
.md-typeset pre {
white-space: pre-wrap;
color: var(--code-color);
}
docs/ftldns/cache_dump.md
+198
View File
@@ -0,0 +1,198 @@
## Cache dump interpretation
The `dnsmasq` core embedded into `pihole-FTL` prints a dump of the current cache content into the mail log file (default location `/var/log/pihole.log`) when receiving `SIGUSR1`, e.g. by
``` bash
sudo killall -USR1 pihole-FTL
```
Such a cache dump looks like
``` plain
cache size 10000, 0/20984 cache insertions re-used unexpired cache entries.
queries forwarded 10247, queries answered locally 14713
queries for authoritative zones 0
pool memory in use 22272, max 24048, allocated 480000
server 127.0.0.1#5353: queries sent 10801, retried or failed 69
server 192.168.2.1#53: queries sent 388, retried or failed 3
Host Address Flags Expires
imap.strato.de 2a01:238:20a:202:54f0::1103 6F Wed Dec 15 20:51:59 2021
imap.strato.de 81.169.145.103 4F Wed Dec 15 20:51:59 2021
api.github.com 6F N Wed Dec 15 20:36:02 2021
www.googleapis.com 2a00:1450:4001:831::200a 6F Wed Dec 15 20:34:35 2021
www.googleapis.com 2a00:1450:4001:801::200a 6F Wed Dec 15 20:34:35 2021
www.googleapis.com 2a00:1450:4001:80e::200a 6F Wed Dec 15 20:34:35 2021
www.googleapis.com 2a00:1450:4001:80f::200a 6F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.185.170 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.185.202 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.185.234 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.181.234 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 172.217.16.138 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.186.42 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.186.74 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.186.106 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.186.138 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.186.170 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 172.217.18.106 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.184.202 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.184.234 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 216.58.212.138 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.185.74 4F Wed Dec 15 20:34:35 2021
www.googleapis.com 142.250.185.106 4F Wed Dec 15 20:34:35 2021
KLA 192.168.2.246 4F D Thu Dec 16 12:49:00 2021
dominik-desktop 192.168.2.224 4F D Thu Dec 16 18:03:49 2021
fritz.repeater 192.168.2.3 4FRI H
lan F D Thu Dec 16 20:08:29 2021
dominik-laptop.lan 192.168.2.206 4FR D Thu Dec 16 20:07:45 2021
dominik-laptop.lan 2a02:b30:f0c:cf00::1ac 6FR D Wed Dec 15 21:07:44 2021
dominik-laptop.lan fd00::1ac 6FR D Wed Dec 15 21:07:44 2021
Internet-Radio 192.168.2.239 4F D Thu Dec 16 12:54:33 2021
Internet-Radio.lan 192.168.2.239 4FR D Thu Dec 16 12:54:33 2021
textsecure-service.whispersyst 13.248.212.111 4F Wed Dec 15 20:32:00 2021
textsecure-service.whispersyst 76.223.92.165 4F Wed Dec 15 20:32:00 2021
textsecure-service.whispersyst 6F N Wed Dec 15 20:42:00 2021
arduino.hosted-by-discourse.co 184.104.202.141 4F Wed Dec 15 20:35:40 2021
arduino.hosted-by-discourse.co 2001:470:1:9a5::141 6F Wed Dec 15 20:35:40 2021
posteo.de 185.67.36.168 4F V Wed Dec 15 20:32:59 2021
posteo.de 2a05:bc0:1000::168:1 6F V Wed Dec 15 20:32:59 2021
posteo.de 23244 8 256 KF V Wed Dec 15 20:32:59 2021
posteo.de 53881 8 257 KF V Wed Dec 15 20:32:59 2021
posteo.de 53881 8 2 SF V Wed Dec 15 20:46:13 2021
strato.de SF N V Wed Dec 15 20:51:59 2021
ip6-allnodes ff02::1 6FRI H
ubuntu.com SF N V Thu Dec 16 08:31:26 2021
fritz.2400 192.168.2.3 4F I H
de 57564 8 256 KF V Wed Dec 15 20:32:59 2021
de 26755 8 257 KF V Wed Dec 15 20:32:59 2021
de 63015 8 256 KF V Wed Dec 15 20:32:59 2021
de 26755 8 2 SF V Thu Dec 16 16:38:18 2021
<Root> 20326 8 257 KF V Thu Dec 16 17:46:14 2021
<Root> 14748 8 256 KF V Thu Dec 16 17:46:14 2021
<Root> 20326 8 2 SF I
i.stack.imgur.com ipv4.imgur.map.fastly.net CF Fri Dec 17 22:10:29 2021
[...]
```
where we stripped lines like `Dec 15 20:32:02 dnsmasq[4177892]:` for the sake of readability. The format is pretty self-explanatory.
### Cache metrics
``` plain
cache size 10000, 0/20984 cache insertions re-used unexpired cache entries.
```
tells us that the cache size is 10000 (Pi-hole's default value). None of the 20984 cache insertions had to overwrite still valid cache lines. If this number is zero, your cache was sufficiently large at any time. If this number is notably larger than zero, you should consider increasing the cache size.
### Query statistics
``` plain
queries forwarded 10247, queries answered locally 14713
queries for authoritative zones 0
```
Mostly self-explanatory. Queries answered locally can both be from local configuration, HOSTS files, DHCP leases, or from the local cache. Queries for authoritative zones can only appear when defining an authoritative zone (`dnsmasq` option `auth-server`).
### Blockdata statistics
``` plain
pool memory in use 22272, max 24048, allocated 480000
```
Blockdata is used to cache records that do not fit in normal cache records. These are `SRV` targets, and `DNSKEY` and `DS` key data objects. Negative (empty) entries do not occupy blockdata space. Blocks are preallocated to reduce heap fragmentation.
### Server statistics
```
server 127.0.0.1#5353: queries sent 10801, retried or failed 69
server 192.168.2.1#53: queries sent 388, retried or failed 3
```
Self-explanatory: Queries sent, retried, and failed to the individual upstream servers.
### Cache content
The first character of the flags describes the query type:
Character | Record type
----------|------------
`4` | `A` (IPv4 address)
`6` | `AAAA` (IPv6 address)
`C` | `CNAME`
`V` | `SRV`
`S` | `DS`
`K` | `DNSKEY`
`(empty)` | something else
The rest of the flags can be almost any combination of the following bits:
Bit | Interpretation
-------|---------------
`F` | Forward entry (domain-to-address record)
`R` | Reverse entry (address-to-domain, typically combined with `D` or `H`)
`I` | Immortal cache entry (no expiry, typically from local configuration)
`D` | DHCP-provided record
`N` | Negative record (This record does not exist)
`X` | NXDOMAIN (No record exists at all for this domain)
`H` | From HOSTS file (always combined with `I`)
`V` | DNSSEC verified
The `V` flag in negative DS records has a different meaning. Only validated `DS` records are every cached, and the `V` bit is used to store information about the presence of an `NS` record for the domain, i.e., if there's a zone cut at that point.
### Examples
#### `A` (`DHCP` provided)
``` plain
Host Address Flags Expires
Internet-Radio 192.168.2.239 4F D Thu Dec 16 12:54:33 2021
Internet-Radio.lan 192.168.2.239 4FR D Thu Dec 16 12:54:33 2021
```
Both cache entries describe an IPv4 cache record for a device in the local network. The `Internet-Radio.lan` has an `R` as it is the name to be served for a reverse lookup as it includes the local network domain `lan`.
#### `DNSKEY/DS`
``` plain
Host Address Flags Expires
de 57564 8 256 KF V Wed Dec 15 20:32:59 2021
de 26755 8 257 KF V Wed Dec 15 20:32:59 2021
de 63015 8 256 KF V Wed Dec 15 20:32:59 2021
de 26755 8 2 SF V Thu Dec 16 16:38:18 2021
<Root> 20326 8 257 KF V Thu Dec 16 17:46:14 2021
<Root> 14748 8 256 KF V Thu Dec 16 17:46:14 2021
<Root> 20326 8 2 SF I
```
The first three cache records are `DNSKEY` records (type `K`) of the `de` domain, the fifth and sixth cache records are `DNSKEY` records of the root zone.
The three numbers in the `address` field correspond to the key tag, the algorithm ID, and the key flags. The fourth and seventh entry corresponds to a `DS` record (type `S`) where the three numbers are the key tag, the used algorithm ID, and the digest.
Note that `DS` records may have an empty `address` field when they are `NODATA` (flag `N`) like
```
Host Address Flags Expires
hosted-by-discourse.com SF N V Sat Dec 18 11:06:03 2021
```
The `DS` of the root zone is marked *immortal* as it is given by the locally defined `trust-anchor`.
#### `CNAME`
``` plain
Host Address Flags Expires
i.stack.imgur.com ipv4.imgur.map.fastly.net CF Fri Dec 17 22:10:29 2021
```
The `address` field corresponds to the `CNAME` target record.
#### `SRV`
``` plain
Host Address Flags Expires
_sip._tcp.pcscf2.ims.telekom.d 100 10 5062 pspcscfhost2.ims.telekom.de VF Sat Dec 18 13:33:37 2021
```
The `address` field lists the priority (`100` in the example), the weight (`10`), and the SRV port (`5062`), followed by the target (`pspcscfhost2.ims.telekom.de`).
{!abbreviations.md!}
docs/ftldns/configfile.md
+18
View File
@@ -197,6 +197,24 @@ With this option, you can change how (and if) hourly PTR requests are made to ch
This setting can be used to disable ARP cache processing. When disabled, client identification and the network table will stop working reliably.
#### `CHECK_LOAD=true|false` (PR [#1249](https://github.com/pi-hole/FTL/pull/1249)) {#check_load data-toc-label='Check system load'}
Pi-hole is very lightweight on resources. Nevertheless, this does not mean that you should run Pi-hole on a server that is otherwise extremely busy as queuing on the system can lead to unecessary delays in DNS operation as the system becomes less and less usable as the system load increases because all resources are permanently in use. To account for this, FTL regularly checks the system load. To bring this to your attention, FTL warns about excessive load when the 15 minute system load average exceeds the number of cores.
This check can be disabled with this setting.
#### `CHECK_SHMEM=90` (PR [#1249](https://github.com/pi-hole/FTL/pull/1249)) {#check_shmem data-toc-label='Check shared-memory limits'}
FTL stores history in shared memory to allow inter-process communication with forked dedicated TCP workers. If FTL runs out of memory, it cannot continue to work as queries cannot be analyzed any further. Hence, FTL checks if enough shared memory is available on your system and warns you if this is not the case.
By default, FTL warns if the shared-memory usage exceeds 90%. You can set any integer limit between `0` to `100` (interpreted as percentages) where `0` means that checking of shared-memory usage is disabled.
#### `CHECK_DISK=90` (PR [#1249](https://github.com/pi-hole/FTL/pull/1249)) {#check_disk data-toc-label='Check disk space'}
FTL stores its long-term history in a database file on disk (see [here](../database/index.md)). Furthermore, FTL stores log files (see, e.g., [here](#file_LOGFILE)).
By default, FTL warns if usage of the disk holding any crutial file exceeds 90%. You can set any integer limit between `0` to `100` (interpreted as percentages) where `0` means that checking of disk usage is disabled.
---
### Long-term database settings
docs/ftldns/interfaces.md
+45 -19
View File
@@ -1,42 +1,68 @@
# Interface binding behavior
## Interface listening settings
Pi-hole offers three choices for interface on its dashboard:
Pi-hole offers three choices for interface listening behavior on its dashboard:
![Available interface settings](/images/interface-settings.png)
![Available interface listening behavior settings](/images/interface-listening.png)
By default, FTL binds the wildcard address. It does this for all options except *Bind only on interface `enp2s0`*. Your Pi-hole then discards requests that it shouldn't reply to. This has the big advantage of working even when interfaces come and go and change address (this happens way more often than one would think).
### Listen on all interfaces
# Recommended setting
This setting accepts DNS queries only from hosts whose address is on a local subnet, i.e. a subnet for which an interface exists on the server. It is intended to be set as a default on installation, to allow unconfigured installations to be useful but also safe from being used for DNS amplification attacks if (accidentally) running public.
## Allow only local requests {#local}
The `dnsmasq` option `local-service` is used.
This setting accepts DNS queries only from hosts whose address is on a local subnet, i.e., a subnet for which an interface exists on the server. It is intended to be set as a default on installation, to allow unconfigured installations to be useful but also safe from being used for DNS amplification attacks if (accidentally) running public.
### Listen only on interface `eth0`
The `dnsmasq` option
Listen only on the specified interface. The loopback (`lo`) interface is automatically added to the list of interfaces to use when this option is used. When the optional settings `bind-interfaces` or `bind-dynamic` are in effect, IP alias interface labels (e.g. `eth1:0`) are checked, rather than interface names.
``` plain
local-service
```
In the degenerate case when an interface has one address, this amounts to the same thing but when an interface has multiple addresses it allows control over which of those addresses are accepted. The same effect is achievable in default mode by using `listen-address`.
is used.
The `dnsmasq` option `interface=eth0` is used (the interface may be different).
# Potentially dangerous options
### Listen on all interfaces, permit all origins
## Respond only on interface `enp2s0` {#single}
We intentionally add this option to disable any possible `local-service` settings from other files. This truly allows any traffic to be replied to and a dangerous thing to do. You should always ask yourself if the first option doesn't work for you as well.
Respond only to queries arriving on the specified interface.
The loopback (`lo`) interface is automatically added to the list of interfaces to use when this option is used.
The `dnsmasq` option `except-interface=nonexisting` is used.
The `dnsmasq` option
## Technical details
``` plain
interface=enp2s0
```
By default, FTL binds the wildcard address, even when it is listening on only some interfaces. It then discards requests that it shouldn't reply to. This has the big advantage of working even when interfaces come and go and change address (this happens way more often than one would think).
is used (the interface may be different).
If this is not what you want, you can add the option
## Bind only on interface `enp2s0` {#bind}
```plain
As said above, the default is to bind to the wildcard address, discarding requests that we shouldn't reply to.
If this is not what you want, you can use this option as it forces FTL to really bind only the interfaces it is listening on. Note that this may result in issues when the interface may go down (cable unplugged, etc.).
About the only time when this is useful is when running another nameserver on the same port on the same machine. This may also happen if you run a virtualization API such as `libvirt`.
When this option is used, IP alias interface labels (e.g. `enp2s0:0`) are checked rather than interface names.
The `dnsmasq` options
``` plain
interface=enp2s0
bind-interfaces
```
to some file like `/etc/dnsmasq.d/99-user.conf` and see [the comment above](#listen-only-on-interface-eth0). This config forces FTL to really bind only the interfaces it is listening on.
About the only time when this is useful is when running another nameserver on the same port on the same machine.
are used (the interface may be different).
## Permit all origins {#all}
This truly allows any traffic to be replied to and is a dangerous thing to do as your Pi-hole could become an [open resolver](https://serverfault.com/questions/573465/what-is-an-open-dns-resolver-and-how-can-i-protect-my-server-from-being-misused). You should always ask yourself if the first option doesn't work for you as well.
The `dnsmasq` option
``` plain
except-interface=nonexisting
```
is used. We add this option to disable any possible `local-service` settings in other config files.
{!abbreviations.md!}
docs/images/interface-listening.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

docs/images/interface-settings.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

docs/main/faq.md
+29
View File
@@ -54,4 +54,33 @@ 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
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.
```
**Solution:**
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,....
Please consider the possibility that your system does not have enough memory at all to load all the needed data.
```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
[..]
```
```bash
sudo service lighttpd restart
```
{!abbreviations.md!}
mkdocs.yml
+1
View File
@@ -112,6 +112,7 @@ nav:
- '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
requirements.txt
+2 -2
View File
@@ -1,5 +1,5 @@
markdown-include==0.6.0
mkdocs==1.2.3
mkdocs-git-revision-date-localized-plugin==0.11
mkdocs-material==8.1.0
mkdocs-git-revision-date-localized-plugin==0.11.1
mkdocs-material==8.1.2
mkdocs-redirects==1.0.3