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

white/black -> allow/deny

Browse Source 
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
This commit is contained in:
Adam Warner
2024-10-20 15:37:09 +01:00
parent 3f436cc35c
commit e68cabf7f9
10 changed files with 50 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/database/domain-database/groups.md
View File

@@ -15,7 +15,7 @@ Group management is implemented using so-called linking tables. Hence, it is pos
- associate domains (and clients!) with any number of groups,
- manage lists together with groups,
- use the same groups for black- and whitelisted domains at the same time.
- use the same groups for deny and allowlist domains at the same time.
The linking tables are particularly simple, as they only link group `id`s with list `id`s. As an example, we describe the `domainlist_by_group` table. The `adlist` and `client` linking tables are constructed similarly.

10
docs/database/domain-database/index.md
View File

@@ -10,14 +10,14 @@ Pi-hole uses the following priorities when deciding whether to block or allow a
1. Exact allowlist entries
2. Regex allowlist entries
3. Exact blocklist entries
3. Exact denylist entries
4. Subscribed allowlists
5. Subscribed blocklists
6. Regex blocklist entries
5. Subscribed denylist
6. Regex denylist entries
## Domain tables (`domainlist`)
The database stores allow-, and blocklists which are directly relevant for Pi-hole's domain blocking behavior. The `domainlist` table contains all domains on the allow- and blocklists. It has a few extra fields to store data related to a given domain such as the `enabled` state, the dates when the domain was added and when it was last modified, and an optional comment.
The database stores allow-, and denylists which are directly relevant for Pi-hole's domain blocking behavior. The `domainlist` table contains all domains on the allow- and denylists. It has a few extra fields to store data related to a given domain such as the `enabled` state, the dates when the domain was added and when it was last modified, and an optional comment.
The date fields are defined as `INTEGER` fields as they expect numerical timestamps also known as *UNIX time*. The `date_added` and `date_modified` fields are initialized with the current timestamp converted to UNIX time. The `comment` field is optional and can be empty.
@@ -26,7 +26,7 @@ Pi-hole's *FTL*DNS reads the tables through the various view, omitting any disab
Label | Type | Uniqueness enforced | Content
----- | ---- | ------------------- | --------
`id` | integer | Yes | Unique ID for database operations
`type` | integer | No | `0` = exact allowlist,<br> `1` = exact blocklist,<br> `2` = regex allowlist,<br> `3` = regex blocklist
`type` | integer | No | `0` = exact allowlist,<br> `1` = exact denylist,<br> `2` = regex allowlist,<br> `3` = regex denylists
`domain` | text | Yes | Domain
`enabled` | boolean | No | Flag whether domain should be used by `pihole-FTL`<br>(`0` = disabled, `1` = enabled)
`date_added` | integer | No | Timestamp when domain was added

12
docs/database/query-database.md
View File

@@ -65,9 +65,9 @@ The content and type of the `additional_info` row depends on the status of the g
If a query was blocked due to a CNAME inspection (status 9, 10, 11), this field contains the domain which was the reason for blocking the entire CNAME chain (text).
##### Query influenced by a black- or whitelist entry {#additional_info_list data-toc-label='domainlist_id'}
##### Query influenced by a deny or allowlist entry {#additional_info_list data-toc-label='domainlist_id'}
If a query was influenced by a black- or whitelist entry, this field contains the ID of the corresponding entry in the [`domainlist`](domain-database/index.md#domain-tables-domainlist) table.
If a query was influenced by a deny or allowlist entry, this field contains the ID of the corresponding entry in the [`domainlist`](domain-database/index.md#domain-tables-domainlist) table.
### Counters table
@@ -118,14 +118,14 @@ ID | Status | | Details
1 | Blocked | ❌ | Domain contained in [gravity database](domain-database/index.md#gravity-tables-gravity-and-antigravity)
2 | Allowed | ✅ | Forwarded
3 | Allowed | ✅ | Replied from cache
4 | Blocked | ❌ | Domain matched by a [regex blacklist](domain-database/index.md#domain-tables-domainlist) filter
5 | Blocked | ❌ | Domain contained in [exact blacklist](domain-database/index.md#domain-tables-domainlist)
4 | Blocked | ❌ | Domain matched by a [regex denylist](domain-database/index.md#domain-tables-domainlist) filter
5 | Blocked | ❌ | Domain contained in [exact denylist](domain-database/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](domain-database/index.md#gravity-tables-gravity-and-antigravity)<br>*Blocked during deep CNAME inspection*
10 | Blocked | ❌ | Domain matched by a [regex blacklist](domain-database/index.md#domain-tables-domainlist) filter<br>*Blocked during deep CNAME inspection*
11 | Blocked | ❌ | Domain contained in [exact blacklist](domain-database/index.md#domain-tables-domainlist)<br>*Blocked during deep CNAME inspection*
10 | Blocked | ❌ | Domain matched by a [regex denylist](domain-database/index.md#domain-tables-domainlist) filter<br>*Blocked during deep CNAME inspection*
11 | Blocked | ❌ | Domain contained in [exact denylist](domain-database/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

48
docs/group_management/example.md
View File

@@ -95,31 +95,31 @@ Client | Group membership | Domain | Blocked
`192.168.0.101` gets `doubleclick.net` blocked as it uses an adlist including this domain. All other clients stay unchanged.
## Example 3: Blacklisting
## Example 3: Denylisting
**Task:** Add a single domain that should be **blacklisted only for group 1** (client `192.168.0.101`).
**Task:** Add a single domain that should be **denylisted only for group 1** (client `192.168.0.101`).
### Step 1
Add the domain to be blocked
![Add new exact blacklist domain](../images/group_management/example-new-black.png)
![Add new exact denylist domain](../images/group_management/example-new-black.png)
![Resulting row in the list of domains](../images/group_management/example-domain-1.png)
??? "Raw database instructions"
```sql
INSERT INTO domainlist (type, domain, comment) VALUES (1, 'blacklisted.com', 'Blacklisted for members of group 1');
INSERT INTO domainlist (type, domain, comment) VALUES (1, 'denylisted.com', 'Denylisted for members of group 1');
```
**Result**
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | blacklisted.com | **Yes**
192.168.0.101 | Group 1 | blacklisted.com | No
192.168.0.102 | Group 2 + Default | blacklisted.com | **Yes**
192.168.0.103 | Group 3 + Default | blacklisted.com | **Yes**
*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.
@@ -140,10 +140,10 @@ Assign this domain to group 1
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | blacklisted.com | Yes
192.168.0.101 | Group 1 | blacklisted.com | **Yes**
192.168.0.102 | Group 2 + Default | blacklisted.com | Yes
192.168.0.103 | Group 3 + Default | blacklisted.com | Yes
*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).
@@ -163,28 +163,28 @@ Remove default assignment to all clients not belonging to a group
Client | Group membership | Domain | Blocked
------------- | ----- | ------ | -------
*all other* | Default | blacklisted.com | **No**
192.168.0.101 | Group 1 | blacklisted.com | Yes
192.168.0.102 | Group 2 + Default | blacklisted.com | **No**
192.168.0.103 | Group 3 + Default | blacklisted.com | **No**
*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.
## Example 4: Whitelisting
## Example 4: Allowlisting
**Task:** Add a single domain that should be **whitelisted only for group 2** (client `192.168.0.102`).
**Task:** Add a single domain that should be **allowlisted only for group 2** (client `192.168.0.102`).
### Step 1
Add the domain to be whitelisted
Add the domain to be allowlisted
![Add a new exact whitelist domain](../images/group_management/example-new-white.png)
![Add a new exact allowlist domain](../images/group_management/example-new-white.png)
![Resulting row in the list of domains](../images/group_management/example-domain-4.png)
??? "Raw database instructions"
```sql
INSERT INTO domainlist (type, domain, comment) VALUES (0, 'doubleclick.net', 'Whitelisted for members of group 2');
INSERT INTO domainlist (type, domain, comment) VALUES (0, 'doubleclick.net', 'Allowlisted for members of group 2');
```
**Result**
@@ -196,7 +196,7 @@ Client | Group membership | Domain | Blocked
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 whitelisting 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 whitelisted. Note that this is completely analog to step 1 of [example 3](#example-3-blacklisting).
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).
### Step 2
@@ -218,7 +218,7 @@ Client | Group membership | Domain | Blocked
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 whitelist entry is not associated with any group and, hence, is not used by any client.
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.
### Step 3
@@ -241,4 +241,4 @@ Client | Group membership | Domain | Blocked
192.168.0.102 | Group 2 + Default | doubleclick.net | **No**
192.168.0.103 | Group 3 + Default | doubleclick.net | Yes
Client 2 got the whitelist entry explicitly assigned to. Accordingly, client 2 does not get the domain blocked whereas all remaining clients still see this domain as blocked.
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.

2
docs/group_management/index.md
View File

@@ -1,4 +1,4 @@
Any blocklist or domain on the white-/black-/regex-lists can be managed through groups. This allows not only grouping them to highlight their relationship, but also enabling/disabling them together if one, for instance, wants to visit a specific service only temporarily.
Any blocklist or domain on the allow-/deny-/regex-lists can be managed through groups. This allows not only grouping them to highlight their relationship, but also enabling/disabling them together if one, for instance, wants to visit a specific service only temporarily.
Group `Default` (`group_id` `0`) is special as it is automatically assigned to domains and clients not being a member of other groups. Each newly added client or domain gets assigned to group zero when being added.

2
docs/guides/webserver/nginx.md
View File

@@ -82,7 +82,7 @@
}
```
7. Create a username for authentication for the admin - we don't want other people in our network change our black and whitelist ;)
7. Create a username for authentication for the admin
```bash
htpasswd -c /etc/nginx/.htpasswd exampleuser

4
docs/main/pihole-command.md
View File

@@ -110,7 +110,7 @@ Since Pi-hole will log DNS queries by default, using this command to watch the l
| Script Location | [`/opt/pihole/gravity.sh`](https://github.com/pi-hole/pi-hole/blob/master/gravity.sh) |
| Example Usage | [`pihole -g`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#gravity) |
Gravity is one of the most important scripts of Pi-hole. Its main purpose is to retrieve blocklists, and then consolidate them into one unique list for the built-in DNS server to use, but it also serves to complete the process of manual whitelisting, blacklisting and wildcard update. It is run automatically each week, but it can be invoked manually at any time.
Gravity is one of the most important scripts of Pi-hole. Its main purpose is to retrieve blocklists, and then consolidate them into one unique list for the built-in DNS server to use, but it also serves to complete the process of manual allowlisting, denylisting and wildcard update. It is run automatically each week, but it can be invoked manually at any time.
**Basic Script Process**:
@@ -140,7 +140,7 @@ This command specifies whether the Pi-hole log should be used.
| Script Location | [`/usr/local/bin/pihole`](https://github.com/pi-hole/pi-hole/blob/master/pihole) |
| Example Usage | [`pihole -q -exact -adlist example.domain.com`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#adlist-query) |
This command will query your whitelist, blacklist, wildcards and adlists for a specified domain.
This command will query your allowlist, denylist, wildcards and adlists for a specified domain.
**Basic Script Process**:

8
docs/regex/index.md
View File

@@ -5,11 +5,11 @@ Our implementation is light and fast as each domain is only checked once for a m
## Hierarchy of regex filters in *FTL*DNS
*FTL*DNS uses a specific hierarchy to ensure regex filters work as you expect them to. Whitelisting always has priority over blacklisting.
*FTL*DNS uses a specific hierarchy to ensure regex filters work as you expect them to. Allowlisting always has priority over denylisting.
There are two locations where regex filters are important:
1. On loading the blocking domains form the `gravity` database table, *FTL*DNS skips not only exactly whitelisted domains but also those that match enabled whitelist regex filters.
2. When a queried domain matches a blacklist regex filter, the query will *not* be blocked if the domain *also* matches an exact or a regex whitelist entry.
1. On loading the blocking domains form the `gravity` database table, *FTL*DNS skips not only exactly allowlisted domains but also those that match enabled allowlist regex filters.
2. When a queried domain matches a denylist regex filter, the query will *not* be blocked if the domain *also* matches an exact or a regex allowlist entry.
## How to use regular expressions for filtering domains
@@ -34,4 +34,4 @@ Once the debugging mode is enabled, each match will be logged to `/var/log/pihol
The given DB ID corresponds to the ID of the corresponding row in the `domainlist` database table.
Note that validation is only done on the first occurrence of a domain to increase the computational efficiency of *FTL*DNS. The result of this evaluation is stored in an internal DNS cache that is separate from `dnsmasq`'s own DNS cache. This allows us to only flush this special cache when modifying the black- and whitelists *without* having to flush the entire DNS cache collected so far.
Note that validation is only done on the first occurrence of a domain to increase the computational efficiency of *FTL*DNS. The result of this evaluation is stored in an internal DNS cache that is separate from `dnsmasq`'s own DNS cache. This allows us to only flush this special cache when modifying the deny and allowlists *without* having to flush the entire DNS cache collected so far.

10
docs/regex/pi-hole.md
View File

@@ -22,25 +22,25 @@ but not
dig A abc
```
This allows you to do query type based black-/whitelisting.
This allows you to do query type based deny-/allowlisting.
Some user-provided examples are:
- `.*;querytype=!A`
A regex blacklist entry for blocking `AAAA` (in fact, everything else than `A`, call it "anti-`A`") requests for all clients assigned to the same group. This has been mentioned to be beneficial for devices like Chromecast. You may want to fine-tune this further to specific domains.
A regex denylist entry for blocking `AAAA` (in fact, everything else than `A`, call it "anti-`A`") requests for all clients assigned to the same group. This has been mentioned to be beneficial for devices like Chromecast. You may want to fine-tune this further to specific domains.
- `.*;querytype=PTR`
A regex whitelist entry used to permit `PTR` lookups with the above "anti-`A`" regex
A regex allowlist entry used to permit `PTR` lookups with the above "anti-`A`" regex
- `.*;querytype=ANY`
A regex blacklist entry to block `ANY` request network wide.
A regex denylist entry to block `ANY` request network wide.
- `.*;querytype=OTHER`
A regex blacklist entry to block `OTHER` request network wide. This rule will match, for instance, proprietary DNS requests using custom query types in the reserved range or queries for seldom used DNS record types like `IXFR` or `AXFR`.
A regex denylist entry to block `OTHER` request network wide. This rule will match, for instance, proprietary DNS requests using custom query types in the reserved range or queries for seldom used DNS record types like `IXFR` or `AXFR`.
Note that multiple (comma-separated) query types can be specified at the same time, e.g., `.*;querytype=A,AAAA` will match both `A` and `AAAA` requests. In a similar fashion, an inverted (`!` modifier) list, e.g., `.*;querytype=!A,AAAA` will match everything *except* `A` and `AAAA` requests.

2
docs/regex/tutorial.md
View File

@@ -1,6 +1,6 @@
# Pi-hole regular expressions tutorial
We provide a short but thorough introduction to our regular expressions implementation. This may come in handy if you are designing blocking or whitelisting rules (see also our cheat sheet below!). In our implementation, all characters match themselves except for the following special characters: `.[{}()\*+?|^$`. If you want to match those, you need to escape them like `\.` for a literal period, but no rule without exception (see character groups below for further details).
We provide a short but thorough introduction to our regular expressions implementation. This may come in handy if you are designing rules to deny or allow domains (see also our cheat sheet below!). In our implementation, all characters match themselves except for the following special characters: `.[{}()\*+?|^$`. If you want to match those, you need to escape them like `\.` for a literal period, but no rule without exception (see character groups below for further details).
## Anchors (`^` and `$`)