From 582da8846284a4eb4c03262b32b3ca03f2613a5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20K=C3=B6nig?= Date: Fri, 10 Jun 2022 23:58:53 +0200 Subject: [PATCH 1/6] Add >gateway endpoint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Christian König --- docs/ftldns/telnet-api.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/ftldns/telnet-api.md b/docs/ftldns/telnet-api.md index 0df2784..751112f 100644 --- a/docs/ftldns/telnet-api.md +++ b/docs/ftldns/telnet-api.md @@ -167,6 +167,14 @@ Connect via e.g. `telnet 127.0.0.1 4711` or use `echo ">command" | nc 127.0.0.1 86400 ``` -Note that the port can also be `0` if someone decides to disable the DNS server part of Pi-hole + Note that the port can also be `0` if someone decides to disable the DNS server part of Pi-hole + +- `>gateway`: Get the IP of the gateway of the default route and the corresponding interface + + ```text + 192.168.0.1 enp2s0 + ``` + + Note that if no non-default route could be found, `0.0.0.0` and an empty interface string is returned {!abbreviations.md!} From 2c153982acb5f1db87f53017099b1763c3f5fd57 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 18 Jun 2022 10:09:26 +0000 Subject: [PATCH 2/6] Bump mkdocs-material from 8.3.4 to 8.3.6 Bumps [mkdocs-material](https://github.com/squidfunk/mkdocs-material) from 8.3.4 to 8.3.6. - [Release notes](https://github.com/squidfunk/mkdocs-material/releases) - [Changelog](https://github.com/squidfunk/mkdocs-material/blob/master/CHANGELOG) - [Commits](https://github.com/squidfunk/mkdocs-material/compare/8.3.4...8.3.6) --- updated-dependencies: - dependency-name: mkdocs-material dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 63fa813..f6740b1 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,5 @@ markdown-include==0.6.0 mkdocs==1.3.0 mkdocs-git-revision-date-localized-plugin==1.0.1 -mkdocs-material==8.3.4 +mkdocs-material==8.3.6 mkdocs-redirects==1.0.4 From 2ce6470267ff67488615cbb682b6e80dbb054d36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20K=C3=B6nig?= Date: Mon, 20 Jun 2022 23:27:33 +0200 Subject: [PATCH 3/6] Change to heading style for API documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Christian König --- docs/ftldns/telnet-api.md | 304 +++++++++++++++++++++----------------- 1 file changed, 170 insertions(+), 134 deletions(-) diff --git a/docs/ftldns/telnet-api.md b/docs/ftldns/telnet-api.md index 751112f..07e103e 100644 --- a/docs/ftldns/telnet-api.md +++ b/docs/ftldns/telnet-api.md @@ -1,180 +1,216 @@ Connect via e.g. `telnet 127.0.0.1 4711` or use `echo ">command" | nc 127.0.0.1 4711` -- `>quit`: Closes the connection to the client +#### `>quit` {data-toc-label='quit'} -- `>stats` : Get current statistics +Closes the connection to the client - ```text - domains_being_blocked 116007 - dns_queries_today 30163 - ads_blocked_today 5650 - ads_percentage_today 18.731558 - unique_domains 1056 - queries_forwarded 4275 - queries_cached 20238 - clients_ever_seen 11 - unique_clients 9 - status enabled - ``` +#### `>stats` {data-toc-label='stats'} -- `>overTime` : over time data (10 min intervals) +Get current statistics - ```text - 1525546500 163 0 - 1525547100 154 1 - 1525547700 164 0 - 1525548300 167 0 - 1525548900 151 0 - 1525549500 143 0 - [...] - ``` +```text +domains_being_blocked 116007 +dns_queries_today 30163 +ads_blocked_today 5650 +ads_percentage_today 18.731558 +unique_domains 1056 +queries_forwarded 4275 +queries_cached 20238 +clients_ever_seen 11 +unique_clients 9 +status enabled +``` -- `>top-domains` : get top domains +#### `>overTime` {data-toc-label='overTime'} - ```text - 0 8462 x.y.z.de - 1 236 safebrowsing-cache.google.com - 2 116 pi.hole - 3 109 z.y.x.de - 4 93 safebrowsing.google.com - 5 96 plus.google.com - [...] - ``` +Get over time data (10 min intervals) - Variant: `>top-domains (15)` to show (up to) 15 entries +```text +1525546500 163 0 +1525547100 154 1 +1525547700 164 0 +1525548300 167 0 +1525548900 151 0 +1525549500 143 0 +[...] +``` -- `>top-ads` : get top ad domains +#### `>top-domains` {data-toc-label='top-domains'} - ```text - 0 8 googleads.g.doubleclick.net - 1 6 www.googleadservices.com - 2 1 cdn.mxpnl.com - 3 1 collector.githubapp.com - 4 1 www.googletagmanager.com - 5 1 s.zkcdn.net - [...] - ``` +Get top domains - Variant: `>top-ads (14)` to show (up to) 14 entries +```text +0 8462 x.y.z.de +1 236 safebrowsing-cache.google.com +2 116 pi.hole +3 109 z.y.x.de +4 93 safebrowsing.google.com +5 96 plus.google.com +[...] +``` -- `top-clients` : get recently active top clients (IP addresses + hostnames (if available)) +Variant: `>top-domains (15)` to show (up to) 15 entries - ```text - 0 9373 192.168.2.1 router - 1 484 192.168.2.2 work-machine - 2 8 127.0.0.1 localhost - ``` +#### `>top-ads` {data-toc-label='top-ads'} - Variant: `>top-clients (9)` to show (up to) 9 client entries or `>top-clients withzero (15)` to show (up to) 15 clients even if they have not been active recently (see PR #124 for further details) +Get top ad domains -- `>forward-dest` : get forward destinations (IP addresses + hostnames (if available)) along with the percentage. The first result (ID -2) will always be the percentage of domains answered from blocklists, whereas the second result (ID -1) will be the queries answered from the cache +```text +0 8 googleads.g.doubleclick.net +1 6 www.googleadservices.com +2 1 cdn.mxpnl.com +3 1 collector.githubapp.com +4 1 www.googletagmanager.com +5 1 s.zkcdn.net +[...] +``` - ```text - -2 18.70 blocklist blocklist - -1 67.10 cache cache - 0 14.20 127.0.0.1 localhost - ``` +Variant: `>top-ads (14)` to show (up to) 14 entries - Variant: `>forward-dest unsorted` to show forward destinations in unsorted order (equivalent to using `>forward-names`) +#### `top-clients` {data-toc-label='top-clients'} -- `>querytypes` : get collected query types percentage +Get recently active top clients (IP addresses + hostnames (if available)) - ```text - A (IPv4): 53.45 - AAAA (IPv6): 45.32 - ANY: 0.00 - SRV: 0.64 - SOA: 0.05 - PTR: 0.54 - TXT: 0.00 - ``` +```text +0 9373 192.168.2.1 router +1 484 192.168.2.2 work-machine +2 8 127.0.0.1 localhost +``` -- `>getallqueries` : get all queries that FTL has in memory +Variant: `>top-clients (9)` to show (up to) 9 client entries or `>top-clients withzero (15)` to show (up to) 15 clients even if they have not been active recently (see PR #124 for further details) - ```text - 1525554586 A fonts.googleapis.com 192.168.2.100 3 0 4 6 - 1525554586 AAAA fonts.googleapis.com 192.168.2.100 3 0 4 5 - 1525554586 A www.mkdocs.org 192.168.2.100 3 0 4 7 - 1525554586 AAAA www.mkdocs.org 192.168.2.100 2 0 3 21 - 1525554586 A squidfunk.github.io 192.168.2.100 2 0 3 20 - 1525554586 A pi-hole.net 192.168.2.100 3 0 4 5 - 1525554586 AAAA squidfunk.github.io 192.168.2.100 3 0 1 6 - 1525554586 AAAA pi-hole.net 192.168.2.100 2 0 1 18 - 1525554586 A github.com 192.168.2.100 3 0 4 5 - 1525554586 AAAA github.com 192.168.2.100 2 0 1 18 - ``` +#### `>forward-dest` {data-toc-label='forward-dest'} - Variants: `>getallqueries (37)` show (up to) 37 latest entries, `>getallqueries-time 1483964295 1483964312` gets all queries that FTL has in its database in a limited time interval, `>getallqueries-time 1483964295 1483964312 (17)` show matches in the (up to) 17 latest entries, `>getallqueries-domain www.google.com` gets all queries that FTL has in its database for a specific domain name, `>getallqueries-client 2.3.4.5` : gets all queries that FTL has in its database for a specific client name *or* IP +Get forward destinations (IP addresses + hostnames (if available)) along with the percentage. The first result (ID -2) will always be the percentage of domains answered from blocklists, whereas the second result (ID -1) will be the queries answered from the cache -- `>recentBlocked` : get most recently pi-holed domain name +```text +-2 18.70 blocklist blocklist +-1 67.10 cache cache +0 14.20 127.0.0.1 localhost +``` - ```text - www.googleadservices.com - ``` +Variant: `>forward-dest unsorted` to show forward destinations in unsorted order (equivalent to using `>forward-names`) - Variant: `>recentBlocked (4)` show the four most recent blocked domains +#### `>querytypes` {data-toc-label='querytypes'} -- `>clientID` : Get ID of currently connected client +Get collected query types percentage - ```text - 6 - ``` +```text +A (IPv4): 53.45 +AAAA (IPv6): 45.32 +ANY: 0.00 +SRV: 0.64 +SOA: 0.05 +PTR: 0.54 +TXT: 0.00 +``` -- `>version` : Get version information of the currently running FTL instance +#### `>getallqueries` {data-toc-label='getallqueries'} - ```text - version v1.6-3-g106498d-dirty - tag v1.6 - branch master - hash 106498d - date 2017-03-26 13:10:43 +0200 - ``` +Get all queries that FTL has in memory -- `>dbstats` : Get some statistics about `FTL`'s' long-term storage database (this request may take some time for processing in case of a large database file) + ```text +1525554586 A fonts.googleapis.com 192.168.2.100 3 0 4 6 +1525554586 AAAA fonts.googleapis.com 192.168.2.100 3 0 4 5 +1525554586 A www.mkdocs.org 192.168.2.100 3 0 4 7 +1525554586 AAAA www.mkdocs.org 192.168.2.100 2 0 3 21 +1525554586 A squidfunk.github.io 192.168.2.100 2 0 3 20 +1525554586 A pi-hole.net 192.168.2.100 3 0 4 5 +1525554586 AAAA squidfunk.github.io 192.168.2.100 3 0 1 6 +1525554586 AAAA pi-hole.net 192.168.2.100 2 0 1 18 +1525554586 A github.com 192.168.2.100 3 0 4 5 +1525554586 AAAA github.com 192.168.2.100 2 0 1 18 +``` - ```text - queries in database: 2700304 - database filesize: 199.20 MB - SQLite version: 3.23.1 - ``` +Variants: `>getallqueries (37)` show (up to) 37 latest entries, `>getallqueries-time 1483964295 1483964312` gets all queries that FTL has in its database in a limited time interval, `>getallqueries-time 1483964295 1483964312 (17)` show matches in the (up to) 17 latest entries, `>getallqueries-domain www.google.com` gets all queries that FTL has in its database for a specific domain name, `>getallqueries-client 2.3.4.5` : gets all queries that FTL has in its database for a specific client name *or* IP -- `>domain pi-hole.net`: Get detailed information about domain (if available) +#### `>recentBlocked` {data-toc-label='recentBlocked'} - ```text - Domain "pi-hole.net", ID: 254 - Total: 179 - Blocked: 0 - Wildcard blocked: false - ``` +Get most recently pi-holed domain name -- `>cacheinfo`: Get DNS server cache size and usage information +```text +www.googleadservices.com +``` - ```text - cache-size: 500000 - cache-live-freed: 0 - cache-inserted: 15529 - ``` +Variant: `>recentBlocked (4)` show the four most recent blocked domains -- `>dns-port`: Get DNS port FTL is listening on +#### `>clientID` {data-toc-label='clientID'} - ```text - 53 - ``` +Get ID of currently connected client -- `>maxlogage`: Get timespan of the statistics shown on the dashboard (in seconds) +```text +6 +``` - ```text - 86400 - ``` +#### `>version` {data-toc-label='version'} - Note that the port can also be `0` if someone decides to disable the DNS server part of Pi-hole +Get version information of the currently running FTL instance -- `>gateway`: Get the IP of the gateway of the default route and the corresponding interface +```text +version v1.6-3-g106498d-dirty +tag v1.6 +branch master +hash 106498d +date 2017-03-26 13:10:43 +0200 +``` - ```text - 192.168.0.1 enp2s0 - ``` +#### `>dbstats` {data-toc-label='dbstats'} - Note that if no non-default route could be found, `0.0.0.0` and an empty interface string is returned +Get some statistics about `FTL`'s' long-term storage database (this request may take some time for processing in case of a large database file) + +```text +queries in database: 2700304 +database filesize: 199.20 MB +SQLite version: 3.23.1 +``` + +#### `>domain pi-hole.net` {data-toc-label='domain'} + +Get detailed information about domain (if available) + +```text +Domain "pi-hole.net", ID: 254 +Total: 179 +Blocked: 0 +Wildcard blocked: false +``` + +#### `>cacheinfo` {data-toc-label='cacheinfo'} + +Get DNS server cache size and usage information + +```text +cache-size: 500000 +cache-live-freed: 0 +cache-inserted: 15529 +``` + +#### `>dns-port` {data-toc-label='dns-port'} + +Get DNS port FTL is listening on + +```text +53 +``` + +Note that the port can also be `0` if someone decides to disable the DNS server part of Pi-hole + +#### `>maxlogage` {data-toc-label='maxlogage'} + +Get timespan of the statistics shown on the dashboard (in seconds) + +```text +86400 +``` + +#### `>gateway` {data-toc-label='gateway'} + +Get the IP of the gateway of the default route and the corresponding interface + +```text +192.168.0.1 enp2s0 +``` + +Note that if no non-default route could be found, `0.0.0.0` and an empty interface string is returned {!abbreviations.md!} From 14bc1533595716234afdb28ce94784a3ba49eac0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20K=C3=B6nig?= Date: Tue, 21 Jun 2022 07:50:48 +0200 Subject: [PATCH 4/6] Separate each command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Christian König --- docs/ftldns/telnet-api.md | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/docs/ftldns/telnet-api.md b/docs/ftldns/telnet-api.md index 07e103e..5bec0a6 100644 --- a/docs/ftldns/telnet-api.md +++ b/docs/ftldns/telnet-api.md @@ -4,6 +4,8 @@ Connect via e.g. `telnet 127.0.0.1 4711` or use `echo ">command" | nc 127.0.0.1 Closes the connection to the client +--- + #### `>stats` {data-toc-label='stats'} Get current statistics @@ -21,6 +23,8 @@ unique_clients 9 status enabled ``` +--- + #### `>overTime` {data-toc-label='overTime'} Get over time data (10 min intervals) @@ -35,6 +39,8 @@ Get over time data (10 min intervals) [...] ``` +--- + #### `>top-domains` {data-toc-label='top-domains'} Get top domains @@ -51,6 +57,8 @@ Get top domains Variant: `>top-domains (15)` to show (up to) 15 entries +--- + #### `>top-ads` {data-toc-label='top-ads'} Get top ad domains @@ -67,7 +75,9 @@ Get top ad domains Variant: `>top-ads (14)` to show (up to) 14 entries -#### `top-clients` {data-toc-label='top-clients'} +--- + +#### `>top-clients` {data-toc-label='top-clients'} Get recently active top clients (IP addresses + hostnames (if available)) @@ -79,6 +89,8 @@ Get recently active top clients (IP addresses + hostnames (if available)) Variant: `>top-clients (9)` to show (up to) 9 client entries or `>top-clients withzero (15)` to show (up to) 15 clients even if they have not been active recently (see PR #124 for further details) +--- + #### `>forward-dest` {data-toc-label='forward-dest'} Get forward destinations (IP addresses + hostnames (if available)) along with the percentage. The first result (ID -2) will always be the percentage of domains answered from blocklists, whereas the second result (ID -1) will be the queries answered from the cache @@ -91,6 +103,8 @@ Get forward destinations (IP addresses + hostnames (if available)) along with th Variant: `>forward-dest unsorted` to show forward destinations in unsorted order (equivalent to using `>forward-names`) +--- + #### `>querytypes` {data-toc-label='querytypes'} Get collected query types percentage @@ -105,6 +119,8 @@ PTR: 0.54 TXT: 0.00 ``` +--- + #### `>getallqueries` {data-toc-label='getallqueries'} Get all queries that FTL has in memory @@ -124,6 +140,8 @@ Get all queries that FTL has in memory Variants: `>getallqueries (37)` show (up to) 37 latest entries, `>getallqueries-time 1483964295 1483964312` gets all queries that FTL has in its database in a limited time interval, `>getallqueries-time 1483964295 1483964312 (17)` show matches in the (up to) 17 latest entries, `>getallqueries-domain www.google.com` gets all queries that FTL has in its database for a specific domain name, `>getallqueries-client 2.3.4.5` : gets all queries that FTL has in its database for a specific client name *or* IP +--- + #### `>recentBlocked` {data-toc-label='recentBlocked'} Get most recently pi-holed domain name @@ -134,6 +152,8 @@ www.googleadservices.com Variant: `>recentBlocked (4)` show the four most recent blocked domains +--- + #### `>clientID` {data-toc-label='clientID'} Get ID of currently connected client @@ -142,6 +162,8 @@ Get ID of currently connected client 6 ``` +--- + #### `>version` {data-toc-label='version'} Get version information of the currently running FTL instance @@ -154,6 +176,8 @@ hash 106498d date 2017-03-26 13:10:43 +0200 ``` +--- + #### `>dbstats` {data-toc-label='dbstats'} Get some statistics about `FTL`'s' long-term storage database (this request may take some time for processing in case of a large database file) @@ -164,6 +188,8 @@ database filesize: 199.20 MB SQLite version: 3.23.1 ``` +--- + #### `>domain pi-hole.net` {data-toc-label='domain'} Get detailed information about domain (if available) @@ -175,6 +201,8 @@ Blocked: 0 Wildcard blocked: false ``` +--- + #### `>cacheinfo` {data-toc-label='cacheinfo'} Get DNS server cache size and usage information @@ -185,6 +213,8 @@ cache-live-freed: 0 cache-inserted: 15529 ``` +--- + #### `>dns-port` {data-toc-label='dns-port'} Get DNS port FTL is listening on @@ -195,6 +225,8 @@ Get DNS port FTL is listening on Note that the port can also be `0` if someone decides to disable the DNS server part of Pi-hole +--- + #### `>maxlogage` {data-toc-label='maxlogage'} Get timespan of the statistics shown on the dashboard (in seconds) @@ -203,6 +235,8 @@ Get timespan of the statistics shown on the dashboard (in seconds) 86400 ``` +--- + #### `>gateway` {data-toc-label='gateway'} Get the IP of the gateway of the default route and the corresponding interface From 2aa70a458f46b7f433e31a5ce152991150f72017 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 25 Jun 2022 10:05:51 +0000 Subject: [PATCH 5/6] Bump mkdocs-material from 8.3.6 to 8.3.8 Bumps [mkdocs-material](https://github.com/squidfunk/mkdocs-material) from 8.3.6 to 8.3.8. - [Release notes](https://github.com/squidfunk/mkdocs-material/releases) - [Changelog](https://github.com/squidfunk/mkdocs-material/blob/master/CHANGELOG) - [Commits](https://github.com/squidfunk/mkdocs-material/compare/8.3.6...8.3.8) --- updated-dependencies: - dependency-name: mkdocs-material dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index f6740b1..1305e49 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,5 @@ markdown-include==0.6.0 mkdocs==1.3.0 mkdocs-git-revision-date-localized-plugin==1.0.1 -mkdocs-material==8.3.6 +mkdocs-material==8.3.8 mkdocs-redirects==1.0.4 From 2ca99e9de77f38830f0b867bafaa9d1004b28acc Mon Sep 17 00:00:00 2001 From: Guy Gastineau Date: Mon, 27 Jun 2022 16:58:34 -0400 Subject: [PATCH 6/6] Fix error in 'Advanced examples' expression The section on character groups clearly states "To include a literal -, make it the first or last character, ..." In the example `Block domains without subdomains` the bounded character group `[\-]{1}` should be `[-]{1}` if the intention is to match a literal `-` as suggested by the accompanying description. Signed-off-by: Guy Gastineau --- docs/regex/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/regex/tutorial.md b/docs/regex/tutorial.md index 0ca66e9..c478b1b 100644 --- a/docs/regex/tutorial.md +++ b/docs/regex/tutorial.md @@ -119,7 +119,7 @@ Blocks domains containing only numbers (no letters) and ending in `.com` or `.ed ### Block domains without subdomains ``` -^[a-z0-9]+([\-]{1}[a-z0-9]+)*\.[a-z]{2,7}$ +^[a-z0-9]+([-]{1}[a-z0-9]+)*\.[a-z]{2,7}$ ``` A domain name shall not start or end with a dash but can contain any number of them. It must be followed by a TLD (we assume a valid TLD length of two to seven characters)