Pi-Hole/docs
1
0
Fork 0
mirror of https://github.com/pi-hole/docs.git synced 2025-12-20 11:18:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix MD060 rule

Browse Source 
Signed-off-by: yubiuser <github@yubiuser.dev>
This commit is contained in:
yubiuser
2025-11-17 12:28:02 +01:00
parent 5e68b10112
commit cc078749eb
12 changed files with 157 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.devcontainer/Dockerfile
View File

@@ -4,7 +4,8 @@ RUN apk add --no-cache \
git \
nano \
openssh \
py3-pip
py3-pip \
tzdata
ENV USER node
USER ${USER}

5
.markdownlint.json
View File

@@ -37,5 +37,8 @@
"MD046": {
"style": "fenced"
},
"MD059": false
"MD059": false,
"MD060": {
"style": "any"
}
}

20
docs/api/tls.md
View File

@@ -23,9 +23,9 @@ It is worth noting that the certificate is only valid for the domain that you ha
### Firefox (tested with Firefox 121.0)
Before | After
:-----:|:-----:
![Firefox Untrusted](../images/api/firefox-pihole-untrusted.png) | ![Firefox Trusted](../images/api/firefox-pihole-trusted.png)
| Before | After |
| :-----: | :-----: |
| ![Firefox Untrusted](../images/api/firefox-pihole-untrusted.png) | ![Firefox Trusted](../images/api/firefox-pihole-trusted.png) |
1. Open the settings page of Firefox at [about:preferences#privacy](about:preferences#privacy)
2. Search for "Certificates"
@@ -44,9 +44,9 @@ If the last step did not work, make sure that you have generated the certificate
### Chrome (tested with Chrome 120.0)
Before | After
:-----:|:-----:
![Chrome Untrusted](../images/api/chrome-pihole-untrusted.png) | ![Chrome Trusted](../images/api/chrome-pihole-trusted.png)
| Before | After |
| :-----: | :-----: |
| ![Chrome Untrusted](../images/api/chrome-pihole-untrusted.png) | ![Chrome Trusted](../images/api/chrome-pihole-trusted.png) |
1. Open the settings page of Chrome at [chrome://settings/privacy](chrome://settings/privacy)
2. Navigate to "Manage certificates" in the "Security" submenu of "Privacy and security" or use the search bar
@@ -64,10 +64,10 @@ If the last step did not work, see the remark below the Firefox instructions abo
### Android (tested with Android 11 and Firefox Mobile 121.1.0)
Before | After
:-----:|:-----:
![Android Firefox Untrusted](../images/api/android-pihole-untrusted.png) | ![Android Firefox Trusted](../images/api/android-pihole-trusted.png)
![Android Chrome Untrusted](../images/api/android-chrome-untrusted.png) | ![Android Chrome Trusted](../images/api/android-chrome-trusted.png)
| Before | After |
| :-----: | :-----: |
| ![Android Firefox Untrusted](../images/api/android-pihole-untrusted.png) | ![Android Firefox Trusted](../images/api/android-pihole-trusted.png) |
| ![Android Chrome Untrusted](../images/api/android-chrome-untrusted.png) | ![Android Chrome Trusted](../images/api/android-chrome-trusted.png) |
1. Go to your device's settings
2. Navigate to "System Security" or "Security & location" (depending on your device)

38
docs/ftldns/cache_dump.md
View File

@@ -115,28 +115,28 @@ Self-explanatory: Queries sent, retried, and failed to the individual upstream s
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
| 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
| 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.

96
docs/group_management/example.md
View File

@@ -62,12 +62,12 @@ after your database modifications to have FTL flush its internal domain-blocking
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | doubleclick.net | Yes
192.168.0.101 | Group 1 | doubleclick.net | **No**
192.168.0.102 | Group 2 + Default | doubleclick.net | Yes
192.168.0.103 | Group 3 + Default | doubleclick.net | Yes
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | doubleclick.net | Yes |
| 192.168.0.101 | Group 1 | doubleclick.net | **No** |
| 192.168.0.102 | Group 2 + Default | doubleclick.net | Yes |
| 192.168.0.103 | Group 3 + Default | doubleclick.net | Yes |
All three clients got automatically assigned to the default (`Default`) group when they were added. The default group includes all subscribed lists and list domains (if not already changed by the user). When we remove the default group for client `192.168.0.101`, we effectively remove all associations to any subscribed lists and domains. This leaves this client completely unblocked.
@@ -84,12 +84,12 @@ All three clients got automatically assigned to the default (`Default`) group wh
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | doubleclick.net | Yes
192.168.0.101 | Group 1 | doubleclick.net | **Yes**
192.168.0.102 | Group 2 + Default | doubleclick.net | Yes
192.168.0.103 | Group 3 + Default | doubleclick.net | Yes
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | doubleclick.net | Yes |
| 192.168.0.101 | Group 1 | doubleclick.net | **Yes** |
| 192.168.0.102 | Group 2 + Default | doubleclick.net | Yes |
| 192.168.0.103 | Group 3 + Default | doubleclick.net | Yes |
`192.168.0.101` gets `doubleclick.net` blocked as it uses a subscribed list including this domain. All other clients stay unchanged.
@@ -112,12 +112,12 @@ Add the domain to be blocked
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | denylisted.com | **Yes**
192.168.0.101 | Group 1 | denylisted.com | No
192.168.0.102 | Group 2 + Default | denylisted.com | **Yes**
192.168.0.103 | Group 3 + Default | denylisted.com | **Yes**
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | denylisted.com | **Yes** |
| 192.168.0.101 | Group 1 | denylisted.com | No |
| 192.168.0.102 | Group 2 + Default | denylisted.com | **Yes** |
| 192.168.0.103 | Group 3 + Default | denylisted.com | **Yes** |
Note that Pi-hole is *not* blocking this domain for client `192.168.0.101` as we removed the default assignment through group 0 above. All remaining clients are linked through the Default group to this domain and see it as being blocked.
@@ -135,12 +135,12 @@ Assign this domain to group 1
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | denylisted.com | Yes
192.168.0.101 | Group 1 | denylisted.com | **Yes**
192.168.0.102 | Group 2 + Default | denylisted.com | Yes
192.168.0.103 | Group 3 + Default | denylisted.com | Yes
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | denylisted.com | Yes |
| 192.168.0.101 | Group 1 | denylisted.com | **Yes** |
| 192.168.0.102 | Group 2 + Default | denylisted.com | Yes |
| 192.168.0.103 | Group 3 + Default | denylisted.com | Yes |
All clients see this domain as being blocked: Client 1 due to a direct assignment through group 1, all remaining clients through the default group 0 (unchanged).
@@ -158,12 +158,12 @@ Remove default assignment to all clients not belonging to a group
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | denylisted.com | **No**
192.168.0.101 | Group 1 | denylisted.com | Yes
192.168.0.102 | Group 2 + Default | denylisted.com | **No**
192.168.0.103 | Group 3 + Default | denylisted.com | **No**
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | denylisted.com | **No** |
| 192.168.0.101 | Group 1 | denylisted.com | Yes |
| 192.168.0.102 | Group 2 + Default | denylisted.com | **No** |
| 192.168.0.103 | Group 3 + Default | denylisted.com | **No** |
While client 1 keeps its explicit assignment through group 1, the remaining clients lost their unassignments when we removed group 0 from the assignment.
@@ -186,12 +186,12 @@ Add the domain to be allowlisted
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | doubleclick.net | **No**
192.168.0.101 | Group 1 | doubleclick.net | Yes
192.168.0.102 | Group 2 + Default | doubleclick.net | **No**
192.168.0.103 | Group 3 + Default | doubleclick.net | **No**
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | doubleclick.net | **No** |
| 192.168.0.101 | Group 1 | doubleclick.net | Yes |
| 192.168.0.102 | Group 2 + Default | doubleclick.net | **No** |
| 192.168.0.103 | Group 3 + Default | doubleclick.net | **No** |
Client `192.168.0.101` is not allowlisting this domain as we removed the default assignment through group 0 above. All remaining clients are linked through the default group to this domain and see it as being allowlisted. Note that this is completely analog to step 1 of [example 3](#example-3-denylisting).
@@ -208,12 +208,12 @@ Remove default group assignment
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | doubleclick.net | **Yes**
192.168.0.101 | Group 1 | doubleclick.net | Yes
192.168.0.102 | Group 2 + Default | doubleclick.net | **Yes**
192.168.0.103 | Group 3 + Default | doubleclick.net | **Yes**
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | doubleclick.net | **Yes** |
| 192.168.0.101 | Group 1 | doubleclick.net | Yes |
| 192.168.0.102 | Group 2 + Default | doubleclick.net | **Yes** |
| 192.168.0.103 | Group 3 + Default | doubleclick.net | **Yes** |
Requests from all clients are blocked as the new allowlist entry is not associated with any group and, hence, is not used by any client.
@@ -231,11 +231,11 @@ Assign this domain to group 2
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | doubleclick.net | Yes
192.168.0.101 | Group 1 | doubleclick.net | Yes
192.168.0.102 | Group 2 + Default | doubleclick.net | **No**
192.168.0.103 | Group 3 + Default | doubleclick.net | Yes
| Client | Group membership | Domain | Blocked |
| ------------- | ----- | ------ | ------- |
| *all other* | Default | doubleclick.net | Yes |
| 192.168.0.101 | Group 1 | doubleclick.net | Yes |
| 192.168.0.102 | Group 2 + Default | doubleclick.net | **No** |
| 192.168.0.103 | Group 3 + Default | doubleclick.net | Yes |
Client 2 got the allowlist entry explicitly assigned to. Accordingly, client 2 does not get the domain blocked whereas all remaining clients still see this domain as blocked.

6
docs/main/coverage.md
View File

@@ -4,7 +4,7 @@ description: Sites and articles about Pi-hole
last_updated: Sun Jan 13 19:20:35 2019 UTC
---
### YouTube/Twit/Video
## YouTube/Twit/Video
- [Security Now Netcast: Pi-hole](https://www.youtube.com/watch?v=p7-osq_y8i8&t=100m26s) _Oct 13, 2015_
- [TekThing: Raspberry Pi-Hole Makes Ads Disappear!](https://www.youtube.com/watch?v=8Co59HU2gY0&t=2m) _Dec 18, 2015_
@@ -15,11 +15,11 @@ last_updated: Sun Jan 13 19:20:35 2019 UTC
- [Know How 355: Killing ads with a Raspberry Pi-Hole!](https://www.twit.tv/shows/know-how/episodes/355) _Nov 9, 2017_
- [Linus Tech Tips: Block EVERY Online Ad with THIS](https://www.youtube.com/watch?v=KBXTnrD_Zs4) _Aug 28, 2019_
### Podcasts
## Podcasts
- [MacObserver Podcast 585](https://www.macobserver.com/tmo/podcast/macgeekgab-585) _Dec 27, 2015_
### Blogs
## Blogs
- [Lifehacker: Turn A Raspberry Pi Into An Ad Blocker With A Single Command](https://www.lifehacker.com.au/2015/02/turn-a-raspberry-pi-into-an-ad-blocker-with-a-single-command/) _Feb 17, 2015_
- [MakeUseOf: Adblock Everywhere: The Raspberry Pi-Hole Way](https://www.makeuseof.com/tag/adblock-everywhere-raspberry-pi-hole-way/) _Mar 25, 2015_

20
docs/main/prerequisites.md
View File

@@ -4,7 +4,7 @@ description: Operating system and network requirements
last_updated: May 25 2020
---
### Hardware
## Hardware
Pi-hole is very lightweight and does not require much processing power
@@ -17,11 +17,11 @@ Pi-hole is very lightweight and does not require much processing power
Despite the name, you are not limited to running Pi-hole on a Raspberry Pi.
Any hardware that runs one of the supported operating systems will do!
### Software
## Software
Pi-hole is supported on distributions utilizing [systemd](https://systemd.io/) or [sysvinit](https://www.nongnu.org/sysvinit/)!
#### Supported Operating Systems
### Supported Operating Systems
The following operating systems are **officially** supported:
@@ -44,14 +44,14 @@ Pi-hole only supports actively maintained versions of these systems.
<!-- markdownlint-enable code-block-style -->
### IP Addressing
## IP Addressing
Pi-hole needs a static IP address to properly function (a DHCP reservation is just fine).
### Ports
## Ports
| Service | Port | Protocol | Notes |
| --------------------|:-------------|:---------| --------------------|
| -------------------- | ------------- | --------- | -------------------- |
| pihole-FTL | 53 (DNS) | TCP/UDP | If you happen to have another DNS server running, such as BIND, you will need to turn it off in order for Pi-hole to respond to DNS queries. |
| pihole-FTL | 67 (DHCP) | IPv4 UDP | The DHCP server is an optional feature that requires additional ports. |
| pihole-FTL | 547 (DHCPv6) | IPv6 UDP | The DHCP server is an optional feature that requires additional ports. |
@@ -62,14 +62,14 @@ Pi-hole needs a static IP address to properly function (a DHCP reservation is ju
The use of pihole-FTL on ports _67_ or _547_ is optional, but required if you use the DHCP functions of Pi-hole.
The use of port _123_ is required when using pihole-FTL as NTP-Server.
### Firewalls
## Firewalls
Below are some examples of firewall rules that will need to be set on your Pi-hole server in order to use the functions available. These are only shown as guides, the actual commands used will be found with your distribution's documentation.
Because Pi-hole was designed to work inside a local network, the following rules will block the traffic from the Internet for security reasons. `192.168.0.0/16` is the most common local network IP range for home users but it can be different in your case, for example other common local network IPs are `10.0.0.0/8` and `172.16.0.0/12`.
**Check your local network settings before applying these rules.**
#### IPTables
### IPTables
IPTables uses two sets of tables. One set is for IPv4 chains, and the second is for IPv6 chains. If only IPv4 blocking is used for the Pi-hole installation, only apply the rules for IP4Tables. Full Stack (IPv4 and IPv6) require both sets of rules to be applied. _Note: These examples insert the rules at the front of the chain. Please see your distribution's documentation for the exact proper command to use._
@@ -94,7 +94,7 @@ ip6tables -I INPUT -p udp -m udp --sport 546:547 --dport 546:547 -j ACCEPT
ip6tables -I INPUT -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
```
#### FirewallD
### FirewallD
Using the `--permanent` argument will ensure the firewall rules persist reboots. If only IPv4 blocking is used for the Pi-hole installation, the `dhcpv6` service can be removed from the commands below. Finally `--reload` to have the new firewall configuration take effect immediately.
@@ -103,7 +103,7 @@ firewall-cmd --permanent --add-service=http --add-service=https --add-service=dn
firewall-cmd --reload
```
#### ufw
### ufw
ufw stores all rules persistently, so you just need to execute the commands below.

4
docs/regex/tutorial.md
View File

@@ -79,12 +79,14 @@ Example | Interpretation
Alternations can be used as an "or" operator in regular expressions.
<!-- markdownlint-disable MD056 -->
<!-- markdownlint-disable MD060 -->
Example | Interpretation
--- | ---
`(abc)|(def)` | matches `abc` *and* `def`
`domain(a|b)\.com` | matches `domaina.com` and `domainb.com` but not `domain.com` or `domainx.com`
`domain(a|b)*\.com` | matches `domain.com`, `domainaaaa.com` `domainbbb.com` but not `domainab.com` (any number of `a` or `b` in between `domain` and `.com`)
<!-- markdownlint-enable MD056 -->
<!-- markdownlint-enable MD060 -->
## Character classes (`[:class:]`)
In addition to character groups, there are also some special character classes available, such as
@@ -132,6 +134,7 @@ A domain name shall not start or end with a dash but can contain any number of t
# Cheatsheet
<!-- markdownlint-disable MD056 -->
<!-- markdownlint-disable MD060 -->
Expression | Meaning | Example
------------ | ------------- | -----------
`^` | Beginning of string | `^client` matches strings that begin with `client`, such as `client.server.com` but not `more.client.server.com` (exception: within a character range (`[]`) `^` means negation)
@@ -147,3 +150,4 @@ Expression | Meaning | Example
`{ }` | Matches a specified number of occurrences of the previous | `[0-9]{3}` matches any three-digit number like `315` but not `31`;<br>`[0-9]{2,4}` matches two- to four-digit numbers like `12`, `123`, and `1234` but not `1` or `12345`;<br>`[0-9]{2,}` matches any number with two or more digits like `1234567`, `123456789`, but not `1`
`\` | Used to escape a special character not inside `[]` | `google\.com` matches `google.com`
<!-- markdownlint-enable MD056 -->
<!-- markdownlint-enable MD060 -->

2
package-lock.json generated
View File

@@ -830,6 +830,7 @@
"integrity": "sha512-0+g7Fi/Y3qfvwfhJr77CpC/dEEoc4k7SvumlnL1tb68O+7fjKtIUG7aKzNUQIMXTVi8x63jcfXg4swz/ZYKyCw==",
"dev": true,
"license": "MIT",
"peer": true,
"dependencies": {
"globby": "15.0.0",
"js-yaml": "4.1.1",
@@ -868,6 +869,7 @@
"integrity": "sha512-CTPAcRBq57cn3R8n3hwc2REddc28hjR7RzDXQ+lXLmMJYqn20BaI2cGw6QjgZGIgVfp2Wdfw4aMzgNteQ6qJgQ==",
"dev": true,
"license": "MIT",
"peer": true,
"bin": {
"marked": "bin/marked.js"
},