From 57cafa2c388388a60f6d33f92d197b059aefaa91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20K=C3=B6nig?= Date: Wed, 13 Jul 2022 13:07:20 +0200 Subject: [PATCH] Make group management more prominent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Christian König --- docs/database/gravity/groups.md | 13 --------- .../gravity => group_management}/example.md | 26 +++++++++--------- docs/group_management/groups.md | 9 ++++++ .../group_management}/example-adlists-1.png | Bin .../group_management}/example-clients-1.png | Bin .../group_management}/example-clients-2.png | Bin .../group_management}/example-clients-3.png | Bin .../group_management}/example-domain-1.png | Bin .../group_management}/example-domain-2.png | Bin .../group_management}/example-domain-3.png | Bin .../group_management}/example-domain-4.png | Bin .../group_management}/example-domain-5.png | Bin .../group_management}/example-domain-6.png | Bin .../group_management}/example-groups.png | Bin .../group_management}/example-new-black.png | Bin .../group_management}/example-new-white.png | Bin mkdocs.yml | 4 ++- 17 files changed, 25 insertions(+), 27 deletions(-) rename docs/{database/gravity => group_management}/example.md (88%) create mode 100644 docs/group_management/groups.md rename docs/{database/gravity => images/group_management}/example-adlists-1.png (100%) rename docs/{database/gravity => images/group_management}/example-clients-1.png (100%) rename docs/{database/gravity => images/group_management}/example-clients-2.png (100%) rename docs/{database/gravity => images/group_management}/example-clients-3.png (100%) rename docs/{database/gravity => images/group_management}/example-domain-1.png (100%) rename docs/{database/gravity => images/group_management}/example-domain-2.png (100%) rename docs/{database/gravity => images/group_management}/example-domain-3.png (100%) rename docs/{database/gravity => images/group_management}/example-domain-4.png (100%) rename docs/{database/gravity => images/group_management}/example-domain-5.png (100%) rename docs/{database/gravity => images/group_management}/example-domain-6.png (100%) rename docs/{database/gravity => images/group_management}/example-groups.png (100%) rename docs/{database/gravity => images/group_management}/example-new-black.png (100%) rename docs/{database/gravity => images/group_management}/example-new-white.png (100%) diff --git a/docs/database/gravity/groups.md b/docs/database/gravity/groups.md index 2dcf871..8c9dc33 100644 --- a/docs/database/gravity/groups.md +++ b/docs/database/gravity/groups.md @@ -1,7 +1,5 @@ ## Group management -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. - Groups are defined in the `group` table and can have an optional description in addition to the mandatory name of the group. Label | Type | Uniqueness enforced | Content @@ -25,14 +23,3 @@ Label | Type | Content `group_id` | integer | `id` of associated group in the `group` table 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. - -## Effect of group management - -The great flexibility to manage domains in zero, one, or multiple groups may result in unexpected behavior when, e.g., the domains are enabled in some but disabled in other groups. For the sake of convenience, we describe the possible configurations and whether *FTL*DNS uses these domains (✔) or not (✘) in such cases. - -- Domain disabled: ✘
Note that the domain is never imported by *FTL*DNS, even if it is contained in an enabled group. - -- Domain enabled: It depends... - - Not managed by a group: ✔ - - Contained in one or more groups (at least one enabled): ✔ - - Contained in one or more groups (all disabled): ✘ diff --git a/docs/database/gravity/example.md b/docs/group_management/example.md similarity index 88% rename from docs/database/gravity/example.md rename to docs/group_management/example.md index c4e5e75..8121689 100644 --- a/docs/database/gravity/example.md +++ b/docs/group_management/example.md @@ -16,7 +16,7 @@ after your database modifications to have FTL flush its internal domain-blocking The `Default` group has a special meaning and cannot be deleted. All domains, clients, and adlists without a specific group assignment are automatically managed through this group. Disabling this group will disable Pi-hole blocking for all unmanaged devices. - ![Adding three groups](example-groups.png) + ![Adding three groups](../images/group_management/example-groups.png) ??? "Raw database instructions" ```sql @@ -29,7 +29,7 @@ after your database modifications to have FTL flush its internal domain-blocking Add three clients at your will, their IP addresses might differ from the ones in this example. - ![Adding three clients](example-clients-1.png) + ![Adding three clients](../images/group_management/example-clients-1.png) ??? "Raw database instructions" ```sql @@ -40,7 +40,7 @@ after your database modifications to have FTL flush its internal domain-blocking 3. **Link the clients to the created groups.** - ![Link groups and clients](example-clients-2.png) + ![Link groups and clients](../images/group_management/example-clients-2.png) ??? "Raw database instructions" ```sql @@ -53,7 +53,7 @@ after your database modifications to have FTL flush its internal domain-blocking **Task:** Exclude client 1 from Pi-hole's blocking by removing client 1 from the `Default` group. -![Change client groups assignment - Overview](example-clients-3.png) +![Change client groups assignment - Overview](../images/group_management/example-clients-3.png) ??? "Raw database instructions" ```sql @@ -76,7 +76,7 @@ All three clients got automatically assigned to the default (`Default`) group wh **Task:** Assign adlist with ID 1 to group 1 (in addition to the default assignment to group 0). This results in client `192.168.0.101` using *only this* adlist (we removed the default association in the last step). -![Change blocklist group assignment - Overview](example-adlists-1.png) +![Change blocklist group assignment - Overview](../images/group_management/example-adlists-1.png) ??? "Raw database instructions" ```sql @@ -103,9 +103,9 @@ Client | Group membership | Domain | Blocked Add the domain to be blocked -![Add new exact blacklist domain](example-new-black.png) +![Add new exact blacklist domain](../images/group_management/example-new-black.png) -![Resulting row in the list of domains](example-domain-1.png) +![Resulting row in the list of domains](../images/group_management/example-domain-1.png) ??? "Raw database instructions" ```sql @@ -128,7 +128,7 @@ Note that Pi-hole is *not* blocking this domain for client `192.168.0.101` as we Assign this domain to group 1 -![Assign group to a new domain](example-domain-2.png) +![Assign group to a new domain](../images/group_management/example-domain-2.png) ??? "Raw database instructions" ```sql @@ -151,7 +151,7 @@ All clients see this domain as being blocked: Client 1 due to a direct assignmen Remove default assignment to all clients not belonging to a group -![Remove Default group from new domain](example-domain-3.png) +![Remove Default group from new domain](../images/group_management/example-domain-3.png) ??? "Raw database instructions" ```sql @@ -178,9 +178,9 @@ While client 1 keeps its explicit assignment through group 1, the remaining clie Add the domain to be whitelisted -![Add a new exact whitelist domain](example-new-white.png) +![Add a new exact whitelist domain](../images/group_management/example-new-white.png) -![Resulting row in the list of domains](example-domain-4.png) +![Resulting row in the list of domains](../images/group_management/example-domain-4.png) ??? "Raw database instructions" ```sql @@ -202,7 +202,7 @@ Client `192.168.0.101` is not whitelisting this domain as we removed the default Remove default group assignment -![Remove default group assignment](example-domain-5.png) +![Remove default group assignment](../images/group_management/example-domain-5.png) ??? "Raw database instructions" ```sql @@ -224,7 +224,7 @@ Requests from all clients are blocked as the new whitelist entry is not associat Assign this domain to group 2 -![Assign group to a new domain](example-domain-6.png) +![Assign group to a new domain](../images/group_management/example-domain-6.png) ??? "Raw database instructions" ```sql diff --git a/docs/group_management/groups.md b/docs/group_management/groups.md new file mode 100644 index 0000000..07e697c --- /dev/null +++ b/docs/group_management/groups.md @@ -0,0 +1,9 @@ +## Group management + +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. + +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. + +## Effect of group management + +The great flexibility to manage domains in zero, one, or multiple groups may result in unexpected behavior when, e.g., the domains are enabled in some but disabled in other groups. diff --git a/docs/database/gravity/example-adlists-1.png b/docs/images/group_management/example-adlists-1.png similarity index 100% rename from docs/database/gravity/example-adlists-1.png rename to docs/images/group_management/example-adlists-1.png diff --git a/docs/database/gravity/example-clients-1.png b/docs/images/group_management/example-clients-1.png similarity index 100% rename from docs/database/gravity/example-clients-1.png rename to docs/images/group_management/example-clients-1.png diff --git a/docs/database/gravity/example-clients-2.png b/docs/images/group_management/example-clients-2.png similarity index 100% rename from docs/database/gravity/example-clients-2.png rename to docs/images/group_management/example-clients-2.png diff --git a/docs/database/gravity/example-clients-3.png b/docs/images/group_management/example-clients-3.png similarity index 100% rename from docs/database/gravity/example-clients-3.png rename to docs/images/group_management/example-clients-3.png diff --git a/docs/database/gravity/example-domain-1.png b/docs/images/group_management/example-domain-1.png similarity index 100% rename from docs/database/gravity/example-domain-1.png rename to docs/images/group_management/example-domain-1.png diff --git a/docs/database/gravity/example-domain-2.png b/docs/images/group_management/example-domain-2.png similarity index 100% rename from docs/database/gravity/example-domain-2.png rename to docs/images/group_management/example-domain-2.png diff --git a/docs/database/gravity/example-domain-3.png b/docs/images/group_management/example-domain-3.png similarity index 100% rename from docs/database/gravity/example-domain-3.png rename to docs/images/group_management/example-domain-3.png diff --git a/docs/database/gravity/example-domain-4.png b/docs/images/group_management/example-domain-4.png similarity index 100% rename from docs/database/gravity/example-domain-4.png rename to docs/images/group_management/example-domain-4.png diff --git a/docs/database/gravity/example-domain-5.png b/docs/images/group_management/example-domain-5.png similarity index 100% rename from docs/database/gravity/example-domain-5.png rename to docs/images/group_management/example-domain-5.png diff --git a/docs/database/gravity/example-domain-6.png b/docs/images/group_management/example-domain-6.png similarity index 100% rename from docs/database/gravity/example-domain-6.png rename to docs/images/group_management/example-domain-6.png diff --git a/docs/database/gravity/example-groups.png b/docs/images/group_management/example-groups.png similarity index 100% rename from docs/database/gravity/example-groups.png rename to docs/images/group_management/example-groups.png diff --git a/docs/database/gravity/example-new-black.png b/docs/images/group_management/example-new-black.png similarity index 100% rename from docs/database/gravity/example-new-black.png rename to docs/images/group_management/example-new-black.png diff --git a/docs/database/gravity/example-new-white.png b/docs/images/group_management/example-new-white.png similarity index 100% rename from docs/database/gravity/example-new-white.png rename to docs/images/group_management/example-new-white.png diff --git a/mkdocs.yml b/mkdocs.yml index 0d8ffdc..c512209 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -98,7 +98,6 @@ nav: - 'Domain database': - 'Overview': database/gravity/index.md - 'Group management': database/gravity/groups.md - - 'Examples': database/gravity/example.md - 'Database recovery': database/gravity/recovery.md - 'FTLDNS': - 'Overview': ftldns/index.md @@ -120,6 +119,9 @@ nav: - 'gdb': ftldns/debugging.md - 'valgrind': ftldns/valgrind.md - 'In-depth manual': ftldns/in-depth.md + - 'Group management': + - 'Overview': group_management/groups.md + - 'Examples': group_management/example.md - 'RegEx blocking': - "Overview": regex/overview.md - "Testing": regex/testmode.md