Merge branch 'pi-hole:master' into patch-1

This commit is contained in:
ThomasKramps
2025-02-16 13:21:15 +01:00
committed by GitHub
25 changed files with 1340 additions and 221 deletions
@@ -16,7 +16,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
uses: actions/checkout@v4.1.1
uses: actions/checkout@v4.2.2
- name: Compress Images
uses: calibreapp/image-actions@1.1.0 # TODO: if they start using a tag like v1, switch to that
+4 -4
View File
@@ -17,19 +17,19 @@ jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4.1.1
- uses: actions/checkout@v4.2.2
with:
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v5.0.0
uses: actions/setup-python@v5.4.0
with:
python-version: "${{ env.PYTHON_VERSION }}"
architecture: "x64"
cache: pip
- name: Set up Node.js
uses: actions/setup-node@v4.0.2
uses: actions/setup-node@v4.2.0
with:
node-version: "${{ env.NODE }}"
cache: npm
@@ -41,7 +41,7 @@ jobs:
run: npm ci
- name: Build docs
run: mkdocs build
run: mkdocs build --strict
- name: Test
run: npm test
+1 -1
View File
@@ -10,7 +10,7 @@ jobs:
steps:
-
name: Checkout repository
uses: actions/checkout@v4.1.1
uses: actions/checkout@v4.2.2
-
name: Spell-Checking
uses: codespell-project/actions-codespell@master
+1 -1
View File
@@ -9,6 +9,6 @@ jobs:
name: editorconfig-checker
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4.1.1
- uses: actions/checkout@v4.2.2
- uses: editorconfig-checker/action-editorconfig-checker@main
- run: editorconfig-checker
+1 -1
View File
@@ -13,7 +13,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Check if PRs are have merge conflicts
uses: eps1lon/actions-label-merge-conflict@v2.1.0
uses: eps1lon/actions-label-merge-conflict@v3.0.3
with:
dirtyLabel: "Merge Conflict"
repoToken: "${{ secrets.GITHUB_TOKEN }}"
+1 -1
View File
@@ -17,7 +17,7 @@ jobs:
pull-requests: write
steps:
- uses: actions/stale@v9.0.0
- uses: actions/stale@v9.1.0
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
# Do not automatically mark PR/issue as stale
+2 -2
View File
@@ -33,7 +33,7 @@ exhaustive, and do not form part of our licenses.
material not subject to the license. This includes other CC-
licensed material, or material used under an exception or
limitation to copyright. More considerations for licensors:
wiki.creativecommons.org/Considerations_for_licensors
wiki.creativecommons.org/Considerations_for_licensors
Considerations for the public: By using one of our public
licenses, a licensor grants the public permission to use the
@@ -50,7 +50,7 @@ exhaustive, and do not form part of our licenses.
Although not required by our licenses, you are encouraged to
respect those requests where reasonable. More_considerations
for the public:
wiki.creativecommons.org/Considerations_for_licensees
wiki.creativecommons.org/Considerations_for_licensees
=======================================================================
+1 -1
View File
@@ -29,7 +29,7 @@ Pi-hole makes use of many commands, and here we will break down those required t
| [Version](#version) | `pihole version` |
| [Uninstall](#uninstall) | `pihole uninstall` |
| [Status](#status) | `pihole status` |
| [Enable & Disable](#enable-&-disable) | `pihole enable` <!-- markdownlint-disable-line MD051 --> |
| [Enable & Disable](#enable-disable) | `pihole enable` <!-- markdownlint-disable-line MD051 --> |
| [Restart DNS](#restart-dns) | `pihole restartdns` |
| [Checkout](#checkout) | `pihole checkout` |
+5 -5
View File
@@ -107,7 +107,7 @@ ID | Resource Record (a.k.a. query type)
15 | `SVCB`
16 | `HTTPS`
Any other query type will be stored with an offset of 100, i.e., `TYPE66` will be stored as `166` in the database (see [pi-hole/FTL #1013](https://github.com/pi-hole/FTL/pull/1013)). This is done to allow for future extensions of the query type list without having to change the database schema. The `OTHER` query type is deprecated since Pi-hole FTL v5.4 (released Jan 2021) and not used anymore. It is kept for backwards compatibility. Note that `OTHER` is still used for the [regex extension `querytype=`](../regex/pi-hole.md#querytype) filter and used for all queries not covered by the above list.
Any other query type will be stored with an offset of 100, i.e., `TYPE66` will be stored as `166` in the database (see [pi-hole/FTL #1013](https://github.com/pi-hole/FTL/pull/1013)). This is done to allow for future extensions of the query type list without having to change the database schema. The `OTHER` query type is deprecated since Pi-hole FTL v5.4 (released Jan 2021) and not used anymore. It is kept for backwards compatibility. Note that `OTHER` is still used for the [regex extension `querytype=`](../regex/pi-hole.md#only-match-specific-query-types) filter and used for all queries not covered by the above list.
### Supported status types
@@ -117,14 +117,14 @@ ID | Status | | Details
1 | Blocked | ❌ | Domain contained in [gravity database](gravity/index.md#gravity-table-gravity)
2 | Allowed | ✅ | Forwarded
3 | Allowed | ✅ | Replied from cache
4 | Blocked | ❌ | Domain matched by a [regex blacklist](gravity/index.md#regex-table-regex) filter
5 | Blocked | ❌ | Domain contained in [exact blacklist](gravity/index.md#blacklist-table-blacklist)
4 | Blocked | ❌ | Domain matched by a [regex blacklist](gravity/index.md#domain-tables-domainlist) filter
5 | Blocked | ❌ | Domain contained in [exact blacklist](gravity/index.md#domain-tables-domainlist)
6 | Blocked | ❌ | By upstream server (known blocking page IP address)
7 | Blocked | ❌ | By upstream server (`0.0.0.0` or `::`)
8 | Blocked | ❌ | By upstream server (`NXDOMAIN` with `RA` bit unset)
9 | Blocked | ❌ | Domain contained in [gravity database](gravity/index.md#gravity-table-gravity)<br>*Blocked during deep CNAME inspection*
10 | Blocked | ❌ | Domain matched by a [regex blacklist](gravity/index.md#regex-table-regex) filter<br>*Blocked during deep CNAME inspection*
11 | Blocked | ❌ | Domain contained in [exact blacklist](gravity/index.md#blacklist-table-blacklist)<br>*Blocked during deep CNAME inspection*
10 | Blocked | ❌ | Domain matched by a [regex blacklist](gravity/index.md#domain-tables-domainlist) filter<br>*Blocked during deep CNAME inspection*
11 | Blocked | ❌ | Domain contained in [exact blacklist](gravity/index.md#domain-tables-domainlist)<br>*Blocked during deep CNAME inspection*
12 | Allowed | ✅ | Retried query
13 | Allowed | ✅ | Retried but ignored query (this may happen during ongoing DNSSEC validation)
14 | Allowed | ✅ | Already forwarded, not forwarding again
+2 -2
View File
@@ -9,7 +9,7 @@ sudo killall -USR1 pihole-FTL
Such a cache dump looks like
``` plain
cache size 10000, 0/20984 cache insertions re-used unexpired cache entries.
cache size 10000, 0/20984 cache insertions reused unexpired cache entries.
queries forwarded 10247, queries answered locally 14713
queries for authoritative zones 0
pool memory in use 22272, max 24048, allocated 480000
@@ -80,7 +80,7 @@ where we stripped lines like `Dec 15 20:32:02 dnsmasq[4177892]:` for the sake of
### Cache metrics
``` plain
cache size 10000, 0/20984 cache insertions re-used unexpired cache entries.
cache size 10000, 0/20984 cache insertions reused 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.
+1 -1
View File
@@ -18,7 +18,7 @@ Once you are used to it, you can skip most of the steps. Debugging *FTL*DNS is q
## Start of debugging session
1. Use `sudo gdb -p $(pidof pihole-FTL)` to attach the debugger to the already running `pihole-FTL` process
1. Use `sudo gdb -p $(cat /run/pihole-FTL.pid)` to attach the debugger to the already running `pihole-FTL` process
2. Once loading of the symbols has finished (the `(gdb)` input prompt is shown), enter `continue` to continue the operation of `pihole-FTL` inside the debugger. All debugger features are now available.
3. When `pihole-FTL` has crashed, copy & paste the terminal output into a (new) issue. Also, type `backtrace` and include its output. We might ask for additional information in order to isolate your particular issue.
+1 -1
View File
@@ -2,7 +2,7 @@
Pi-hole offers three choices for interface on its dashboard:
![Available interface settings](/images/interface-settings.png)
![Available interface settings](../images/interface-settings.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).
+17 -6
View File
@@ -9,12 +9,12 @@ It is worth noting, however, that the upstream DNS-Over-HTTPS provider will stil
## Configuring DNS-Over-HTTPS
Along with releasing their DNS service [1.1.1.1](https://blog.cloudflare.com/announcing-1111/), Cloudflare implemented DNS-Over-HTTPS proxy functionality into one of their tools: [`cloudflared`](https://github.com/cloudflare/cloudflared).
Along with releasing their DNS service [1.1.1.1](https://blog.cloudflare.com/announcing-1111/) (and later [1.1.1.1 for Families](https://blog.cloudflare.com/introducing-1-1-1-1-for-families)) Cloudflare implemented DNS-Over-HTTPS proxy functionality into one of their tools: [`cloudflared`](https://github.com/cloudflare/cloudflared).
In the following sections, we will be covering how to install and configure this tool on `Pi-hole`.
!!! info
The `cloudflared` binary will work with other DoH providers (for example, you could use `https://8.8.8.8/dns-query` for Google's DNS-Over-HTTPS service).
The `cloudflared` binary will also work with other DoH providers (for example, [Google's DoH service](https://developers.google.com/speed/public-dns/docs/doh) or [Quad9's DoH service](https://quad9.net/service/service-addresses-and-features)).
### Installing `cloudflared`
@@ -81,7 +81,18 @@ Edit configuration file by copying the following in to `/etc/default/cloudflared
```bash
# Commandline args for cloudflared, using Cloudflare DNS
CLOUDFLARED_OPTS=--port 5053 --upstream https://1.1.1.1/dns-query --upstream https://1.0.0.1/dns-query
CLOUDFLARED_OPTS=--port 5053 --upstream https://cloudflare-dns.com/dns-query
```
!!! info
See the other available [Cloudflare endpoints](https://developers.cloudflare.com/1.1.1.1/infrastructure/network-operators/#available-endpoints).
If you're running cloudflared on different host than pi-hole, you can add listening address to all IPs (for security, change 0.0.0.0 to your machine's IP, e.g. 192.168.1.1):
```bash
# Commandline args for cloudflared, using Cloudflare DNS
CLOUDFLARED_OPTS=--port 5053 --upstream https://1.1.1.1/dns-query --upstream https://1.0.0.1/dns-query --address 0.0.0.0
```
Update the permissions for the configuration file and `cloudflared` binary to allow access for the cloudflared user:
@@ -154,13 +165,13 @@ google.com. 191 IN A 172.217.22.14
Finally, configure Pi-hole to use the local `cloudflared` service as the upstream DNS server by specifying `127.0.0.1#5053` as the Custom DNS (IPv4):
![Screenshot of Pi-hole configuration](/images/DoHConfig.png)
![Screenshot of Pi-hole configuration](../../images/DoHConfig.png)
(don't forget to hit Return or click on `Save`)
### Updating `cloudflared`
The `cloudflared` tool will not receive updates through the package manager. However, you should keep the program update to date. You can either do this manually, or via a cron script.
The `cloudflared` tool will not receive updates through the package manager. However, you should keep the program update to date. You can either do this manually (e.g. by watching their [repo](https://github.com/cloudflare/cloudflared) for new releases), or via a cron script.
The procedure for updating depends on how you configured the `cloudflared` binary.
@@ -200,7 +211,7 @@ sudo chown root:root /etc/cron.weekly/cloudflared-updater
<!-- markdownlint-disable code-block-style -->
!!! warning
Make sure to add shebang `#!/bin/bash` in the beginning of `/etc/cron.weekly/cloudflared-updater`.
Otherwise, the command would not executed.
Otherwise, the command will not be executed.
<!-- markdownlint-enable code-block-style -->
The system will now attempt to update the cloudflared binary automatically, once per week.
+8 -18
View File
@@ -156,14 +156,6 @@ dig pi-hole.net @127.0.0.1 -p 5335
The first query may be quite slow, but subsequent queries, also to other domains under the same TLD, should be fairly quick.
You should also consider adding
``` plain
edns-packet-max=1232
```
to a config file like `/etc/dnsmasq.d/99-edns.conf` to signal FTL to adhere to this limit.
### Test validation
You can test DNSSEC validation using
@@ -179,7 +171,7 @@ The first command should give a status report of `SERVFAIL` and no IP address. T
Finally, configure Pi-hole to use your recursive DNS server by specifying `127.0.0.1#5335` as the Custom DNS (IPv4):
![Upstream DNS Servers Configuration](/images/RecursiveResolver.png)
![Upstream DNS Servers Configuration](../../images/RecursiveResolver.png)
(don't forget to hit Return or click on `Save`)
@@ -222,16 +214,14 @@ sudo service unbound restart
!!! warning
It's not recommended to increase verbosity for daily use, as unbound logs a lot. But it might be helpful for debugging purposes.
There are five levels of verbosity
There are five levels of verbosity:
```
Level 0 means no verbosity, only errors
Level 1 gives operational information
Level 2 gives detailed operational information
Level 3 gives query level information
Level 4 gives algorithm level information
Level 5 logs client identification for cache misses
```
- Level 0 means no verbosity, only errors
- Level 1 gives operational information
- Level 2 gives detailed operational information
- Level 3 gives query level information
- Level 4 gives algorithm level information
- Level 5 logs client identification for cache misses
First, specify the log file, human-readable timestamps and the verbosity level in the `server` part of
`/etc/unbound/unbound.conf.d/pi-hole.conf`:
+1 -1
View File
@@ -29,7 +29,7 @@ The long-term database can be disabled by setting
DBFILE=
```
in `/etc/pihole/pihole-FTL.conf` and running `sudo pihole restartdns` (see also [here](/ftldns/configfile/#dbfile)).
in `/etc/pihole/pihole-FTL.conf` and running `sudo pihole restartdns` (see also [here](../../ftldns/configfile.md/#dbfile)).
### 2.2 Increase DNS cache size
+1 -1
View File
@@ -1,6 +1,6 @@
{!guides/vpn/openvpn/deprecation_notice.md!}
This tutorial is tailored for setting up OpenVPN on a cloud-hosted virtual server (such as [Digital Ocean](https://www.digitalocean.com/?refcode=344d234950e1)). If you wish to have this working on your home network, you will need to tailor Pi-hole to listen on `eth0` (or similar), which we explain in [this section of the tutorial](dual-operation.md).
This tutorial is tailored for setting up OpenVPN on a cloud-hosted virtual server. If you wish to have this working on your home network, you will need to tailor Pi-hole to listen on `eth0` (or similar), which we explain in [this section of the tutorial](dual-operation.md).
### High-level Overview
+1 -1
View File
@@ -235,6 +235,6 @@ peer: F+80gbmHVlOrU+es13S18oMEX2g= ⬅ Your peer's public key will be differen
## Test for DNS leaks
You should run a DNS leak test on [www.dnsleaktest.com](https://www.dnsleaktest.com) to ensure your WireGuard tunnel does not leak DNS requests (so all are processed by your Pi-hole). The expected outcome is that you should only see DNS servers belonging to the upstream DNS destination you selected in Pi-hole. If you configured [Pi-hole as All-Around DNS Solution](/guides/dns/unbound/), you should only see the public IP address of your WireGuard server and no other DNS server.
You should run a DNS leak test on [www.dnsleaktest.com](https://www.dnsleaktest.com) to ensure your WireGuard tunnel does not leak DNS requests (so all are processed by your Pi-hole). The expected outcome is that you should only see DNS servers belonging to the upstream DNS destination you selected in Pi-hole. If you configured [Pi-hole as All-Around DNS Solution](../../dns/unbound.md), you should only see the public IP address of your WireGuard server and no other DNS server.
See also [What is a DNS leak and why should I care?](https://www.dnsleaktest.com/what-is-a-dns-leak.html) (external link).
+8 -8
View File
@@ -25,14 +25,14 @@ Pi-hole is supported on distributions utilizing [systemd](https://systemd.io/) o
The following operating systems are **officially** supported:
| Distribution | Release | Architecture |
| ------------ | ---------------- | ------------------- |
| Raspberry Pi OS <br>(formerly Raspbian) | Buster / Bullseye | ARM |
| Armbian OS | Any | ARM / x86_64 / riscv64 |
| Ubuntu | 20.x / 22.x / 23.x | ARM / x86_64 |
| Debian | 10 / 11 / 12 | ARM / x86_64 / i386 |
| Fedora | 36 / 37 / 38 | ARM / x86_64 |
| CentOS Stream | 8 / 9 | x86_64 |
- Raspberry Pi OS (formerly Raspbian)
- Armbian OS
- Ubuntu
- Debian
- Fedora
- CentOS Stream
Pi-hole only supports actively maintained versions of these systems.
<!-- markdownlint-disable code-block-style -->
!!! info
+1 -1
View File
@@ -2,7 +2,7 @@
## Only match specific query types
You can amend the regular expressions by special keywords added at the end to fine-tine regular expressions to match only specific [query types](../database/ftl.md#supported-query-types). In contrast to the description of `OTHER` as being deprecated for storing queries in the database, it is still supported for regular expressions and will match all queries that are not *explicitly* covered by the other query types (see also example below).
You can amend the regular expressions by special keywords added at the end to fine-tune regular expressions to match only specific [query types](../database/ftl.md#supported-query-types). In contrast to the description of `OTHER` as being deprecated for storing queries in the database, it is still supported for regular expressions and will match all queries that are not *explicitly* covered by the other query types (see also example below).
Example:
+2 -2
View File
@@ -134,7 +134,7 @@ eingetragen werden.
![Screenshot der Fritz!Box IPv6 Adressen Einstellungen](../images/routers/fritzbox-ipv6-2-de.png)
## Optional: Erhöhung der Priorität von DNS Anfragen
## Optional: Erhöhung der Priorität von DNS Anfragen {#optional-erhohung-der-prioritat-von-dns-anfragen}
Bei ausgelasteter Internetverbindung werden DNS-Anfragen u.U. stark verzögert bearbeitet. Dies kann in der Fritz!Box durch Hinterlegen von DNS als priorisierter Echtzeitanwendung vermieden werden. Falls nicht bereits geschehen, fügen Sie hierfür zunächst "`DNS`" als neuen Answendungstyp unter
@@ -188,7 +188,7 @@ zwei Zugangsprofile an (z.B. "`Standard`" und "`Unbeschränkt`"). Im Profil "`St
Erweiterte Einstellungen -> Gesperrte Netzwerkanwendungen
```
die [angelegte Netzwerkanwendung "`DNS`"](/routers/fritzbox-de/#optional-erhohung-der-prioritat-von-dns-anfragen) hinzu.
die [angelegte Netzwerkanwendung "`DNS`"](#optional-erhohung-der-prioritat-von-dns-anfragen) hinzu.
Im Profil "`Unbeschränkt`" darf "`DNS`" *nicht* als gesperrt hinterlegt werden.
Nun werden die Zugangsprofile unter
+1 -1
View File
@@ -175,7 +175,7 @@ If not already present, create two access profiles (e.g. "`Standard`" and "`Unre
Internet/Filters/Access Profiles -> Manage and Optimize Access Profiles
```
In the profile "`Standard`" add the network application "`DNS`" ([created above](/routers/fritzbox/#optional-increasing-the-priority-of-dns-requests)) under:
In the profile "`Standard`" add the network application "`DNS`" ([created above](#optional-increasing-the-priority-of-dns-requests)) under:
``` plain
Advanced settings -> Locked network applications
+5 -1
View File
@@ -4,6 +4,9 @@ repo_url: 'https://github.com/pi-hole/pi-hole'
edit_uri: '../docs/blob/master/docs/'
copyright:
remote_branch: gh-pages
validation:
links:
anchors: warn
theme:
name: 'material'
custom_dir: overrides
@@ -22,6 +25,7 @@ theme:
- search.highlight
- search.share
- content.action.edit
- content.code.copy
palette:
# Light mode
@@ -45,7 +49,7 @@ theme:
markdown_extensions:
# Code highlighting in ``` ``` blocks
# https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight
- pymdownx.highlight:
- pymdownx.highlight
- pymdownx.superfences
- pymdownx.inlinehilite
# Table of Contents
+1268 -154
View File
File diff suppressed because it is too large Load Diff
+2 -2
View File
@@ -22,7 +22,7 @@
"test": "npm run markdownlint && npm run linkinator"
},
"devDependencies": {
"linkinator": "^6.0.4",
"markdownlint-cli2": "0.12.1"
"linkinator": "^6.1.2",
"markdownlint-cli2": "0.17.2"
}
}
+4 -4
View File
@@ -1,5 +1,5 @@
mkdocs==1.5.3
mkdocs-git-revision-date-localized-plugin==1.2.4
mkdocs-material==9.5.13
mkdocs-redirects==1.2.1
mkdocs==1.6.1
mkdocs-git-revision-date-localized-plugin==1.3.0
mkdocs-material==9.6.4
mkdocs-redirects==1.2.2
markdown-include==0.8.1