From 3e3d72c6b8619811c992781df17dce7b8d709f26 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Sat, 8 Jul 2023 14:07:50 +0200 Subject: [PATCH] Add domain priorities concerning what is to be blocked and allowed Signed-off-by: DL6ER --- docs/database/gravity/index.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/database/gravity/index.md b/docs/database/gravity/index.md index b0f4ac5a1..79af6f1cb 100644 --- a/docs/database/gravity/index.md +++ b/docs/database/gravity/index.md @@ -1,8 +1,18 @@ -Pi-hole uses the well-known relational database management system SQLite3 for managing the various domains that are used to control the DNS filtering system. The database-based domain management has been added with Pi-hole v5.0. +Pi-hole uses the well-known relational database management system SQLite3 for managing the various domains that are used to control the DNS filtering system. The database-based domain management has been added with Pi-hole v5.0. The ability to subscribe to external *allow*lists has been added with Pi-hole v6.0. + +## Priorities +Pi-hole uses the following priorities when deciding whether to block or allow a domain: + +1. Exact allowlist entries +2. Regex allowlist entries +3. Exact blocklist entries +4. Subscribed allowlists +5. Subscribed blocklists +6. Regex blocklist entries ## Domain tables (`domainlist`) -The database stores white-, and blacklists which are directly relevant for Pi-hole's domain blocking behavior. The `domainlist` table contains all domains on the white- and blacklists. 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 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 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. @@ -11,7 +21,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 whitelist,
`1` = exact blacklist,
`2` = regex whitelist,
`3` = regex blacklist +`type` | integer | No | `0` = exact allowlist,
`1` = exact blocklist,
`2` = regex allowlist,
`3` = regex blocklist `domain` | text | Yes | Domain `enabled` | boolean | No | Flag whether domain should be used by `pihole-FTL`
(`0` = disabled, `1` = enabled) `date_added` | integer | No | Timestamp when domain was added @@ -35,18 +45,18 @@ Label | Type | Uniqueness enforced | Content `invalid_domains` | integer | No | Number of invalid domains on this list `status` | integer | No | `1` = List download was successful, `2` = List unchanged upstream, Pi-hole used a local copy, `3` = List unavailable, Pi-hole used a local copy, `4` = List unavailable, there is no local copy of this list available on your Pi-hole -## Gravity Table (`gravity`) +## Gravity Tables (`gravity` and `antigravity`) -The `gravity` table consists of the domains that have been processed by Pi-hole's `gravity` (`pihole -g`) command. The domains in this list are the collection of domains sourced from the configured sources (see the [`adlist` table](index.md#adlist-table-adlist). +The `gravity` and `antigravity` table consists of the domains that have been processed by Pi-hole's `gravity` (`pihole -g`) command. The domains in this list are the collection of domains sourced from the configured sources (see the [`adlist` table](index.md#adlist-table-adlist)). -During each run of `pihole -g`, this table is flushed and completely rebuilt from the newly obtained set of domains to be blocked. +During each run of `pihole -g`, these tables are flushed and completely rebuilt from the newly obtained set of domains to be blocked or allowed. Label | Type | Content ----- | ---- | ------- -`domain` | text | Blocked domain compiled from adlist referenced by `adlist_id` -`adlist_id` | integer | ID associated to adlists in table `adlist` +`domain` | text | Domain compiled from subscribed list referenced by `adlist_id` +`adlist_id` | integer | ID associated to subscribed list in table `adlist` -Uniqueness is enforced on pairs of (`domain`, `adlist_id`). In other words: domains can be added multiple times, however, only when they are referencing different adlists as their origins. +Uniqueness is enforced on pairs of (`domain`, `adlist_id`) in both tables. In other words: domains can be added multiple times, however, only when they are referencing different adlists as their origins. ## Client table (`client`)