From 2011b3cab35b2e74972a726638e0d396eae5c198 Mon Sep 17 00:00:00 2001 From: Dan Schaper Date: Thu, 2 Apr 2020 17:40:20 -0700 Subject: [PATCH 01/22] Add Netlfiy badge to README.md --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index 621bb62..cdce91c 100644 --- a/README.md +++ b/README.md @@ -70,3 +70,8 @@ Please make sure you fork the repo and change the clone URL in the example below ``` After these commands, the current branch is accessible through your favorite browser at + + + + Deploys by Netlify + From 249b9a556cb9875699226feb8a1b370484c9c3dc Mon Sep 17 00:00:00 2001 From: Dan Schaper Date: Thu, 2 Apr 2020 17:42:46 -0700 Subject: [PATCH 02/22] Hidden whitespace removal --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index cdce91c..8b7cf52 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,6 @@ Please make sure you fork the repo and change the clone URL in the example below After these commands, the current branch is accessible through your favorite browser at - - - Deploys by Netlify - + +Deploys by Netlify + From 603b2e4cc13933f588e15a1447fa063e91f9f83d Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Fri, 3 Apr 2020 09:32:16 +0300 Subject: [PATCH 03/22] Update README.md --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 8b7cf52..0b3035e 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,4 @@ Please make sure you fork the repo and change the clone URL in the example below After these commands, the current branch is accessible through your favorite browser at - -Deploys by Netlify - +[![Deploys by Netlify](https://www.netlify.com/img/global/badges/netlify-color-bg.svg)](https://www.netlify.com/) From 9d0421ad25cdb10094353bb4b46f636f43627705 Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Fri, 3 Apr 2020 09:35:46 +0300 Subject: [PATCH 04/22] Update build.yml --- .github/workflows/build.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index dfaf505..c732d12 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -34,7 +34,7 @@ jobs: - name: Upload docs uses: actions/upload-artifact@v1 - if: success() && github.ref == 'refs/heads/master' + if: success() && github.event_name != 'pull_request' && github.ref == 'refs/heads/master' with: name: docs path: ./site/ @@ -42,7 +42,7 @@ jobs: deploy: runs-on: ubuntu-latest needs: build - if: github.ref == 'refs/heads/master' + if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master' steps: - uses: actions/checkout@v2 From 2192071973ebac4d35a218b6347311af62cdefca Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Fri, 3 Apr 2020 09:37:19 +0300 Subject: [PATCH 05/22] Update build.yml --- .github/workflows/build.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index c732d12..dfaf505 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -34,7 +34,7 @@ jobs: - name: Upload docs uses: actions/upload-artifact@v1 - if: success() && github.event_name != 'pull_request' && github.ref == 'refs/heads/master' + if: success() && github.ref == 'refs/heads/master' with: name: docs path: ./site/ @@ -42,7 +42,7 @@ jobs: deploy: runs-on: ubuntu-latest needs: build - if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master' + if: github.ref == 'refs/heads/master' steps: - uses: actions/checkout@v2 From bef0effc9c7a6325b795e3737fd61cda300fe271 Mon Sep 17 00:00:00 2001 From: "dependabot-preview[bot]" <27856297+dependabot-preview[bot]@users.noreply.github.com> Date: Sat, 16 May 2020 14:51:34 +0300 Subject: [PATCH 06/22] Bump mkdocs from 1.1 to 1.1.2 (#312) Bumps [mkdocs](https://github.com/mkdocs/mkdocs) from 1.1 to 1.1.2. - [Release notes](https://github.com/mkdocs/mkdocs/releases) - [Commits](https://github.com/mkdocs/mkdocs/compare/1.1...1.1.2) Signed-off-by: dependabot-preview[bot] Co-authored-by: dependabot-preview[bot] <27856297+dependabot-preview[bot]@users.noreply.github.com> --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 2327a21..ea215c8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ markdown-include==0.5.1 -mkdocs==1.1 +mkdocs==1.1.2 mkdocs-git-revision-date-localized-plugin==0.5.2 mkdocs-material==5.1.6 From c86a8040ebd931f024c2af443a1aab4f7651e3dc Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Sat, 16 May 2020 19:57:25 +0300 Subject: [PATCH 07/22] Update build.yml (#314) Remove `--verbose` when running mkdocs since the warnings are hidden in all this text --- .github/workflows/build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index aa8fbb6..0c5fa5f 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -31,7 +31,7 @@ jobs: run: python3 -m pip install -r requirements.txt - name: Build docs - run: mkdocs build --clean --verbose + run: mkdocs build --clean - name: Upload docs uses: actions/upload-artifact@v1 From 2a05ee1e02aab350f00ea17762d5970b516d660c Mon Sep 17 00:00:00 2001 From: bcambl Date: Sat, 16 May 2020 21:03:17 -0600 Subject: [PATCH 08/22] Update supported versions for Fedora & CentOS Signed-off-by: bcambl --- docs/main/prerequesites.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/main/prerequesites.md b/docs/main/prerequesites.md index 0c53307..5218812 100644 --- a/docs/main/prerequesites.md +++ b/docs/main/prerequesites.md @@ -20,11 +20,11 @@ The following operating systems are **officially** supported: | Distribution | Release | Architecture | | ------------ | ---------------- | ------------------- | -| Raspbian | Stretch / Buster | ARM | +| Raspbian | Stretch / Buster | ARM | | Ubuntu | 16.x / 18.x | ARM / x86_64 | | Debian | 9 / 10 | ARM / x86_64 / i386 | -| Fedora | 28 / 29 | ARM / x86_64 | -| CentOS | 7 | x86_64 | +| Fedora | 31 / 32 | ARM / x86_64 | +| CentOS | 7 / 8 | x86_64 | ### IP Addressing From 57df57660f231346abec72d1e1381d3e28a21dc9 Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Sun, 17 May 2020 21:08:25 +0300 Subject: [PATCH 09/22] Update markdownlint-cli from ^0.22.0 to ^0.23.1 (#317) --- package-lock.json | 35 ++++++++++++++++++----------------- package.json | 2 +- 2 files changed, 19 insertions(+), 18 deletions(-) diff --git a/package-lock.json b/package-lock.json index 92fcac2..3ad97b7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -51,9 +51,9 @@ "dev": true }, "entities": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/entities/-/entities-2.0.0.tgz", - "integrity": "sha512-D9f7V0JSRwIxlRI2mjMqufDrRDnx8p+eEOz7aUM9SuvF8gsBzra0/6tbjl1m8eQHrZlYj6PxqE00hZ1SAIKPLw==", + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/entities/-/entities-2.0.2.tgz", + "integrity": "sha512-dmD3AvJQBUjKpcNkoqr+x+IF0SdRtPz9Vk0uTy4yWqga9ibB6s4v++QFWNohjiUGoMlF552ZvNyXDxz5iW0qmw==", "dev": true }, "esprima": { @@ -133,9 +133,9 @@ } }, "jsonc-parser": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-2.2.0.tgz", - "integrity": "sha512-4fLQxW1j/5fWj6p78vAlAafoCKtuBm6ghv+Ij5W2DrDx0qE+ZdEl2c6Ko1mgJNF5ftX1iEWQQ4Ap7+3GlhjkOA==", + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-2.2.1.tgz", + "integrity": "sha512-o6/yDBYccGvTz1+QFevz6l6OBZ2+fMVu2JZ9CIhzsYRX4mjaK5IyX9eldUdCmga16zlgQxyrj5pt9kzuj2C02w==", "dev": true }, "linkify-it": { @@ -173,18 +173,18 @@ } }, "markdownlint": { - "version": "0.19.0", - "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.19.0.tgz", - "integrity": "sha512-+MsWOnYVUH4klcKM7iRx5cno9FQMDAb6FC6mWlZkeXPwIaK6Z5Vd9VkXkykPidRqmLHU2wI+MNyfUMnUCBw3pQ==", + "version": "0.20.3", + "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.20.3.tgz", + "integrity": "sha512-J93s59tGvSFvAPWVUtEgxqPI0CHayTx1Z8poj1/4UJAquHGPIruWRMurkRldiNbgBiaQ4OOt15rHZbFfU6u05A==", "dev": true, "requires": { "markdown-it": "10.0.0" } }, "markdownlint-cli": { - "version": "0.22.0", - "resolved": "https://registry.npmjs.org/markdownlint-cli/-/markdownlint-cli-0.22.0.tgz", - "integrity": "sha512-qRg6tK5dXWqkaFvEstz9YSQal1ECMgofrSZgdBOaPWG8cD50pk8Hs0ZpBCJ6SCHPKF71pCdtuSL2u82sIx2XWA==", + "version": "0.23.1", + "resolved": "https://registry.npmjs.org/markdownlint-cli/-/markdownlint-cli-0.23.1.tgz", + "integrity": "sha512-UARWuPILksAcVLTosUv1F1tLognNYQ/qjLRIgWwQAYqdl3QQrTPurU/X9Z2jrdAJYlOim868QsufxjYJpH0K7Q==", "dev": true, "requires": { "commander": "~2.9.0", @@ -196,16 +196,17 @@ "jsonc-parser": "~2.2.0", "lodash.differencewith": "~4.5.0", "lodash.flatten": "~4.4.0", - "markdownlint": "~0.19.0", - "markdownlint-rule-helpers": "~0.7.0", + "markdownlint": "~0.20.3", + "markdownlint-rule-helpers": "~0.10.0", "minimatch": "~3.0.4", + "minimist": "~1.2.5", "rc": "~1.2.7" } }, "markdownlint-rule-helpers": { - "version": "0.7.0", - "resolved": "https://registry.npmjs.org/markdownlint-rule-helpers/-/markdownlint-rule-helpers-0.7.0.tgz", - "integrity": "sha512-xZByWJNBaCMHo7nYPv/5aO8Jt68YcMvyouFXhuXmJzbqCsQy8rfCj0kYcv22kdK5PwAgMdbHg0hyTdURbUZtJw==", + "version": "0.10.0", + "resolved": "https://registry.npmjs.org/markdownlint-rule-helpers/-/markdownlint-rule-helpers-0.10.0.tgz", + "integrity": "sha512-0e8VUTjNdQwS7hTyNan9oOLsy4a7KEsXo3fxKMDRFRk6Jn+pLB3iKZ3mj/m6ECrlOUCxPYYmgOmmyk3bSdbIvw==", "dev": true }, "mdurl": { diff --git a/package.json b/package.json index 1589c62..4c49f65 100644 --- a/package.json +++ b/package.json @@ -20,6 +20,6 @@ "test": "npm run markdownlint" }, "devDependencies": { - "markdownlint-cli": "^0.22.0" + "markdownlint-cli": "^0.23.1" } } From 6acfa4fed1781ca2e83a977cae047d271d20b149 Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Sun, 17 May 2020 21:11:42 +0300 Subject: [PATCH 10/22] Remove HTML tables (#318) --- .markdownlint.json | 3 +- docs/guides/whitelist-blacklist.md | 111 +++++++++++++---------------- 2 files changed, 52 insertions(+), 62 deletions(-) diff --git a/.markdownlint.json b/.markdownlint.json index 6326377..5883b5b 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -24,8 +24,7 @@ "img", "strong", "p", - "sub", - "table", "tbody", "th", "tr", "td" + "sub" ] }, "MD035": { diff --git a/docs/guides/whitelist-blacklist.md b/docs/guides/whitelist-blacklist.md index 58c7eab..e669673 100644 --- a/docs/guides/whitelist-blacklist.md +++ b/docs/guides/whitelist-blacklist.md @@ -10,73 +10,64 @@ The scripts will first parse `whitelist.txt` or `blacklist.txt` for any changes, Each script accepts the following parameters: - - - - - - - - - - - - - - - - - - - - - - - -
[domain]Fully qualified domain name you wish to add or remove. You can pass any number of domains.
-dRemoval mode. Domains will be removed from the list, rather than added
-nrUpdate blacklist without refreshing dnsmasq
-fForce delete cached blocklist content
-qQuiet mode. Console output is minimal. Useful for calling from another script (see gravity.sh)
+| Parameter | Description | +|------------|--------------------------------------------------------------------------------------------------| +| `[domain]` | Fully qualified domain name you wish to add or remove. You can pass any number of domains. | +| `-d` | Removal mode. Domains will be removed from the list, rather than added | +| `-nr` | Update blacklist without refreshing pihole-FTL | +| `-f` | Force delete cached blocklist content | +| `-q` | Quiet mode. Console output is minimal. Useful for calling from another script (see `gravity.sh`) | Domains passed are parsed by the script to ensure they are valid domains. If a domain is invalid it will be ignored. #### Example `pihole -w` usages - - - - - - - - - - - - - - - -
pihole -w domain1 [domain2...]Attempt to add one or more domains to the whitelist and reload dnsmasq.
pihole -w -nr domain1 [domain2...]Attempt to add one or more domains to the whitelist, but do not reload dnsmasq.
pihole -w -f domain1 [domain2...]Attempt to add one or more domains to the whitelist and force dnsmasq to reload
+* Attempt to add one or more domains to the whitelist and reload dnsmasq: -To remove domains from the whitelist: -Add `-d` as an additional argument (e.g `pihole -w -d domain1 [domain2...]`) + ```bash + pihole -w domain1 [domain2...] + ``` + +* Attempt to add one or more domains to the whitelist, but do not reload dnsmasq: + + ```bash + pihole -w -nr domain1 [domain2...] + ``` + +* Attempt to add one or more domains to the whitelist and force dnsmasq to reload: + + ```bash + pihole -w -f domain1 [domain2...] + ``` + +To remove domains from the whitelist add `-d` as an additional argument, e.g: + +```bash +pihole -w -d domain1 [domain2...] +``` #### Example `pihole -b` usages - - - - - - - - - - - - - - - -
pihole -b domain1 [domain2...]Attempt to add one or more domains to the blacklist and reload dnsmasq.
pihole -b -nr domain1 [domain2...]Attempt to add one or more domains to the blacklist, but do not reload dnsmasq.
pihole -b -f domain1 [domain2...]Attempt to add one or more domains to the blacklist and force dnsmasq to reload
+* Attempt to add one or more domains to the blacklist and reload dnsmasq: -To remove domains from the blacklist: -Add `-d` as an additional argument (e.g `pihole -b -d domain1 [domain2...]`) + ```bash + pihole -b domain1 [domain2...] + ``` + +* Attempt to add one or more domains to the blacklist, but do not reload dnsmasq: + + ```bash + pihole -b -nr domain1 [domain2...] + ``` + +* Attempt to add one or more domains to the blacklist and force dnsmasq to reload: + + ```bash + pihole -b -f domain1 [domain2...] + ``` + +To remove domains from the blacklist add `-d` as an additional argument, e.g: + +```bash +pihole -b -d domain1 [domain2...] +``` From 6f7978ab8c7162d053389d72157f88086cc59ed8 Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Thu, 14 May 2020 20:11:37 +0300 Subject: [PATCH 11/22] various tweaks Signed-off-by: Adam Warner --- docs/core/pihole-command.md | 33 +++++++----------------------- docs/guides/vpn/dual-operation.md | 2 +- docs/guides/whitelist-blacklist.md | 16 +++++++-------- docs/main/origins.md | 1 + docs/main/prerequesites.md | 8 ++++---- 5 files changed, 20 insertions(+), 40 deletions(-) diff --git a/docs/core/pihole-command.md b/docs/core/pihole-command.md index 1f99656..f8784ef 100644 --- a/docs/core/pihole-command.md +++ b/docs/core/pihole-command.md @@ -59,12 +59,8 @@ See [Regex Blocking](/ftldns/regex/overview/) for more information about using R **Basic Script Process**: * Each domain is validated using regex (except when using `-regex`), to ensure invalid domains and IDNs are not added -* A whitelisted domain gets added or removed from `/etc/pihole/whitelist.txt` -* A blacklisted domain gets added or removed from `/etc/pihole/blacklist.txt` - * On either list type, `gravity.sh` is then called to consolidate an updated copy of `gravity.list`, and the DNS server is reloaded -* A regex blacklisted domain gets added or removed from `/etc/pihole/regex.list` -* A wildcard domain gets converted into regex and added or removed from `/etc/pihole/regex.list` - * For both regex-based commands, `gravity.sh` is then called to restart the DNS server +* A domain gets added to or removed from the `domainlist` table in [`/etc/pihole/gravity.db`](/database/gravity/) +* The DNS server is then reloaded ### Debugger @@ -153,14 +149,12 @@ Gravity is one of the most important scripts of Pi-hole. Its main purpose is to **Basic Script Process**: -* It will determine Internet connectivity, and give time for `dnsmasq` to be resolvable on low-end systems if has just been restarted -* It extracts all URLs and domains from `/etc/pihole/adlists.list` +* It will determine Internet connectivity, and give time for `pihole-FTL` to be resolvable on low-end systems if has just been restarted +* It extracts all URLs and domains from the `adlists` table in [`/etc/pihole/gravity.db`](/database/gravity) * It runs through each URL, downloading it if necessary * `curl` checks the servers `Last-Modified` header to ensure it is getting a newer version * It will attempt to parse the file into a domains-only format if necessary -* Lists are merged, comments removed, sorted uniquely and stored as `list.preEventHorizon` -* Whitelisted entries within `/etc/pihole/whitelist.txt` are removed from `list.preEventHorizon` and saved into a temporary file -* Blacklisted, "localhost" and temporary file entries are added as separate `.list` files +* Lists are merged, comments removed, sorted uniquely and stored in the `gravity` table of [`/etc/pihole/gravity.db`](/database/gravity) * Gravity cleans up temporary content and reloads the DNS server ### Logging @@ -187,10 +181,7 @@ This command will query your whitelist, blacklist, wildcards and adlists for a s * User-specified options are handled * Using `idn`, it will convert [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) into [punycode](https://en.wikipedia.org/wiki/Punycode) -* The whitelist and the blacklist are searched -* The possible wildcard matches are then searched (`/etc/dnsmasq.d/03-pihole-wildcard.conf`) -* The adlists are then searched (`/etc/pihole/list.*.domains`) -* Output is determined by the specified options, ensuring that a file name is only printed once +* Database at [`/etc/pihole/gravity.db`](/database/gravity) is queried to return a list of adlists in which the queried domain exists. ### Update @@ -311,16 +302,6 @@ Example Usage | [`pihole -a -c`](https://discourse.pi-hole.net/t/the-pihole-co Set the specified temperature unit as the preferred type. This preference will affect the Web Interface, as well as Chronometer. -### Host Record - -| | | - -------------- | -------------- -Help Command | `pihole -a hostrecord --help` -Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh) -Example Usage | `pihole -a hostrecord home.domain.com 192.168.1.1` - -Add A & AAAA records to the DNS, to be associated with an IPv4/IPv6 address. - ### Email Address | | | @@ -339,4 +320,4 @@ Help Command | `pihole -a interface --help` Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh) Example Usage | [`pihole -a interface local`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#interface) -Specify interface listening behavior for `dnsmasq`. When using `pihole -a interface all`, please ensure you use a firewall to prevent your Pi-hole from becoming an unwitting host to [DNS amplification attackers](https://duckduckgo.com/?q=dns+amplification+attack). You may want to consider running [OpenVPN](https://github.com/pi-hole/pi-hole/wiki/Pi-hole---OpenVPN-server) to grant your mobile devices access to the Pi-hole. +Specify interface listening behavior for `pihole-FTL`. When using `pihole -a interface all`, please ensure you use a firewall to prevent your Pi-hole from becoming an unwitting host to [DNS amplification attackers](https://duckduckgo.com/?q=dns+amplification+attack). You may want to consider running [OpenVPN](https://github.com/pi-hole/pi-hole/wiki/Pi-hole---OpenVPN-server) to grant your mobile devices access to the Pi-hole. diff --git a/docs/guides/vpn/dual-operation.md b/docs/guides/vpn/dual-operation.md index f1df699..b0a81da 100644 --- a/docs/guides/vpn/dual-operation.md +++ b/docs/guides/vpn/dual-operation.md @@ -1,6 +1,6 @@ **Up until now, this wiki has been about a server set up on a cloud host, available on the public Internet. This section is aimed at a server set up in a private network like on a Raspberry Pi.** -So if blocking works using `eth0` but stops working for `tun0`, as described [here](https://github.com/pi-hole/pi-hole/issues/1553), you may want to run this command `pihole -a -i all`, which should get the behavior you want by opening dnsmasq up to listen on all ports. This is not recommended for cloud servers as they should _not_ be listening on `eth0`. +So if blocking works using `eth0` but stops working for `tun0`, as described [here](https://github.com/pi-hole/pi-hole/issues/1553), you may want to run this command `pihole -a -i all`, which should get the behavior you want by opening pihole-FTL up to listen on all ports. This is not recommended for cloud servers as they should _not_ be listening on `eth0`. If you want to set up your Pi-hole + OpenVPN such that you can use from both internal ((W)LAN) and external (VPN) networks, you have to apply some small changes. As an additional benefit, you will be able to reach all devices in the internal network (e.g. computers, networking-aware printers, etc.) through the VPN. diff --git a/docs/guides/whitelist-blacklist.md b/docs/guides/whitelist-blacklist.md index e669673..80728c2 100644 --- a/docs/guides/whitelist-blacklist.md +++ b/docs/guides/whitelist-blacklist.md @@ -4,9 +4,7 @@ ### How to Whitelist or Blacklist -There are scripts to aid users in adding or removing domains to the whitelist or blacklist. - -The scripts will first parse `whitelist.txt` or `blacklist.txt` for any changes, and if any additions or deletions are detected, it will reload `dnsmasq` so that they are effective immediately. +There are scripts to aid users in adding or removing domains to the whitelist or blacklist from the CLI Each script accepts the following parameters: @@ -22,19 +20,19 @@ Domains passed are parsed by the script to ensure they are valid domains. If a d #### Example `pihole -w` usages -* Attempt to add one or more domains to the whitelist and reload dnsmasq: +* Attempt to add one or more domains to the whitelist and reload pihole-FTL: ```bash pihole -w domain1 [domain2...] ``` -* Attempt to add one or more domains to the whitelist, but do not reload dnsmasq: +* Attempt to add one or more domains to the whitelist, but do not reload pihole-FTL: ```bash pihole -w -nr domain1 [domain2...] ``` -* Attempt to add one or more domains to the whitelist and force dnsmasq to reload: +* Attempt to add one or more domains to the whitelist and force pihole-FTL to reload: ```bash pihole -w -f domain1 [domain2...] @@ -48,19 +46,19 @@ pihole -w -d domain1 [domain2...] #### Example `pihole -b` usages -* Attempt to add one or more domains to the blacklist and reload dnsmasq: +* Attempt to add one or more domains to the blacklist and reload pihole-FTL: ```bash pihole -b domain1 [domain2...] ``` -* Attempt to add one or more domains to the blacklist, but do not reload dnsmasq: +* Attempt to add one or more domains to the blacklist, but do not reload pihole-FTL: ```bash pihole -b -nr domain1 [domain2...] ``` -* Attempt to add one or more domains to the blacklist and force dnsmasq to reload: +* Attempt to add one or more domains to the blacklist and force pihole-FTL to reload: ```bash pihole -b -f domain1 [domain2...] diff --git a/docs/main/origins.md b/docs/main/origins.md index 45a7e06..5663768 100755 --- a/docs/main/origins.md +++ b/docs/main/origins.md @@ -11,6 +11,7 @@ Pi-hole being a **advertising-aware DNS/Web server**, makes use of the following - [`lighttpd`](https://www.lighttpd.net/) - web server designed and optimized for high performance - [`php`](https://www.php.net/) - a popular general-purpose web scripting language - [AdminLTE Dashboard](https://github.com/ColorlibHQ/AdminLTE) - premium admin control panel based on Bootstrap 3.x +- [`sqlite3`](https://www.sqlite.org/index.html) - SQL Database engine While quite outdated at this point, [this original blog post about Pi-hole](https://jacobsalmela.com/2015/06/16/block-millions-ads-network-wide-with-a-raspberry-pi-hole-2-0/) goes into **great detail** about how Pi-hole was originally set up and how it works. Syntactically, it's no longer accurate, but the same basic principles and logic still apply to Pi-hole's current state. diff --git a/docs/main/prerequesites.md b/docs/main/prerequesites.md index 5218812..93d16bf 100644 --- a/docs/main/prerequesites.md +++ b/docs/main/prerequesites.md @@ -40,15 +40,15 @@ Due to the complexity of different ways of setting an IP address across differen | Service | Port | Protocol | Notes | | --------------------|:-------------|:---------| --------------------| -| dnsmasq | 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. | -| dnsmasq | 67 (DHCP) | IPv4 UDP | The DHCP server is an optional feature that requires additional ports. | -| dnsmasq | 547 (DHCPv6) | IPv6 UDP | The DHCP server is an optional feature that requires additional ports. | +| 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. | | lighttpd | 80 (HTTP) | TCP | If you have another Web server already running, such as Apache, Pi-hole's Web server will not work. You can either disable the other Web server or change the port on which `lighttpd` listens, which allows you keep both Web servers running. | | pihole-FTL | 4711-4720 | TCP | FTL is our API engine and uses port 4711 on the localhost interface. This port should not be accessible from any other interface.| !!! info The use of lighttpd on port _80_ is optional if you decide not to install the Web dashboard during installation. - The use of dnsmasq on ports _67_ or _547_ is optional, but required if you use the DHCP functions of Pi-hole. + The use of pihole-FTL on ports _67_ or _547_ is optional, but required if you use the DHCP functions of Pi-hole. ### Firewalls From 87f37386a345901767457e9df4298d17a2bf4cf2 Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Sun, 17 May 2020 11:57:22 +0300 Subject: [PATCH 12/22] Link to the guides OpenVPN page instead of the wiki --- docs/core/pihole-command.md | 2 +- docs/guides/vpn/overview.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/pihole-command.md b/docs/core/pihole-command.md index f8784ef..528503e 100644 --- a/docs/core/pihole-command.md +++ b/docs/core/pihole-command.md @@ -320,4 +320,4 @@ Help Command | `pihole -a interface --help` Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh) Example Usage | [`pihole -a interface local`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#interface) -Specify interface listening behavior for `pihole-FTL`. When using `pihole -a interface all`, please ensure you use a firewall to prevent your Pi-hole from becoming an unwitting host to [DNS amplification attackers](https://duckduckgo.com/?q=dns+amplification+attack). You may want to consider running [OpenVPN](https://github.com/pi-hole/pi-hole/wiki/Pi-hole---OpenVPN-server) to grant your mobile devices access to the Pi-hole. +Specify interface listening behavior for `pihole-FTL`. When using `pihole -a interface all`, please ensure you use a firewall to prevent your Pi-hole from becoming an unwitting host to [DNS amplification attackers](https://duckduckgo.com/?q=dns+amplification+attack). You may want to consider running [OpenVPN](/guides/vpn/overview/) to grant your mobile devices access to the Pi-hole. diff --git a/docs/guides/vpn/overview.md b/docs/guides/vpn/overview.md index b7e0184..aee7c87 100644 --- a/docs/guides/vpn/overview.md +++ b/docs/guides/vpn/overview.md @@ -14,7 +14,7 @@ Via this VPN, you can: - access your admin interface remotely - encrypt your Internet traffic -If you don't want a full-tunnel, we provide a wiki of how to [set up your server to exclusively route DNS traffic, but nothing else via the VPN](only-dns-via-vpn.md). On another optional page, we describe how to set up Pi-hole + VPN in such a way that it is [usable both locally (no VPN) and from remote (through VPN)](dual-operation.md) while preserving full functionality. +If you don't want a full-tunnel, we provide a page of how to [set up your server to exclusively route DNS traffic, but nothing else via the VPN](only-dns-via-vpn.md). On another optional page, we describe how to set up Pi-hole + VPN in such a way that it is [usable both locally (no VPN) and from remote (through VPN)](dual-operation.md) while preserving full functionality. In the end, you will have access to a VPN that uses Pi-hole for DNS and tunnels some or all of your network traffic From b616d6a8bdabc9a3b401c7b11aa68901a36cdecb Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Sun, 17 May 2020 12:04:39 +0300 Subject: [PATCH 13/22] Switch to relative links This is so that mkdocs can warn if pages are missing and also for consistency with the other links --- docs/core/pihole-command.md | 12 ++++++------ docs/guides/benchmark.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/core/pihole-command.md b/docs/core/pihole-command.md index 528503e..86d34db 100644 --- a/docs/core/pihole-command.md +++ b/docs/core/pihole-command.md @@ -54,12 +54,12 @@ Example Usage | [`pihole -regex '^example.com$' '.*\.example2.net'`](https://d Administrators need to be able to manually add and remove domains for various purposes, and these commands serve that purpose. -See [Regex Blocking](/ftldns/regex/overview/) for more information about using Regex. +See [Regex Blocking](../ftldns/regex/overview.md) for more information about using Regex. **Basic Script Process**: * Each domain is validated using regex (except when using `-regex`), to ensure invalid domains and IDNs are not added -* A domain gets added to or removed from the `domainlist` table in [`/etc/pihole/gravity.db`](/database/gravity/) +* A domain gets added to or removed from the `domainlist` table in [`/etc/pihole/gravity.db`](../database/gravity/index.md) * The DNS server is then reloaded ### Debugger @@ -150,11 +150,11 @@ Gravity is one of the most important scripts of Pi-hole. Its main purpose is to **Basic Script Process**: * It will determine Internet connectivity, and give time for `pihole-FTL` to be resolvable on low-end systems if has just been restarted -* It extracts all URLs and domains from the `adlists` table in [`/etc/pihole/gravity.db`](/database/gravity) +* It extracts all URLs and domains from the `adlists` table in [`/etc/pihole/gravity.db`](../database/gravity/index.md) * It runs through each URL, downloading it if necessary * `curl` checks the servers `Last-Modified` header to ensure it is getting a newer version * It will attempt to parse the file into a domains-only format if necessary -* Lists are merged, comments removed, sorted uniquely and stored in the `gravity` table of [`/etc/pihole/gravity.db`](/database/gravity) +* Lists are merged, comments removed, sorted uniquely and stored in the `gravity` table of [`/etc/pihole/gravity.db`](../database/gravity/index.md) * Gravity cleans up temporary content and reloads the DNS server ### Logging @@ -181,7 +181,7 @@ This command will query your whitelist, blacklist, wildcards and adlists for a s * User-specified options are handled * Using `idn`, it will convert [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) into [punycode](https://en.wikipedia.org/wiki/Punycode) -* Database at [`/etc/pihole/gravity.db`](/database/gravity) is queried to return a list of adlists in which the queried domain exists. +* Database at [`/etc/pihole/gravity.db`](../database/gravity/index.md) is queried to return a list of adlists in which the queried domain exists. ### Update @@ -320,4 +320,4 @@ Help Command | `pihole -a interface --help` Script Location | [`/opt/pihole/webpage.sh`](https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/webpage.sh) Example Usage | [`pihole -a interface local`](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738#interface) -Specify interface listening behavior for `pihole-FTL`. When using `pihole -a interface all`, please ensure you use a firewall to prevent your Pi-hole from becoming an unwitting host to [DNS amplification attackers](https://duckduckgo.com/?q=dns+amplification+attack). You may want to consider running [OpenVPN](/guides/vpn/overview/) to grant your mobile devices access to the Pi-hole. +Specify interface listening behavior for `pihole-FTL`. When using `pihole -a interface all`, please ensure you use a firewall to prevent your Pi-hole from becoming an unwitting host to [DNS amplification attackers](https://duckduckgo.com/?q=dns+amplification+attack). You may want to consider running [OpenVPN](../guides/vpn/overview.md) to grant your mobile devices access to the Pi-hole. diff --git a/docs/guides/benchmark.md b/docs/guides/benchmark.md index c1d4ec1..4560e3f 100644 --- a/docs/guides/benchmark.md +++ b/docs/guides/benchmark.md @@ -29,7 +29,7 @@ The long-term database can be disabled by setting DBFILE= ``` -in `/etc/pihole/pihole-FTL.conf` and running `sudo pihole restartdns` (see also [here](/ftldns/configfile/#dbfile)). +in `/etc/pihole/pihole-FTL.conf` and running `sudo pihole restartdns` (see also [here](../ftldns/configfile.md#dbfile)). ### 2.2 Increase DNS cache size From ab6ba5f437c8a7ee1582b49bb275c6a74b3240ba Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Wed, 20 May 2020 22:30:48 +0300 Subject: [PATCH 14/22] Remove obsolete affiliate link (#319) --- docs/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index b3be7d5..6b236d0 100755 --- a/docs/index.md +++ b/docs/index.md @@ -46,7 +46,6 @@ If you'd rather not donate (_which is okay!_), there are other ways you can help - [Digital Ocean](https://www.digitalocean.com/?refcode=344d234950e1) _new account credits with our affiliate link_ - [Amazon](https://www.amazon.com/exec/obidos/redirect-home/pihole09-20) _affiliate link_ -- [Vultr](https://www.vultr.com/?ref=7190426) _affiliate link_ - Spreading the word about our software, and how you have benefited from it ### Contributing via GitHub From f5c69c4d6dccaa803cb480a451d6c147ee46dc6a Mon Sep 17 00:00:00 2001 From: iatacs19 <33841205+iatacs19@users.noreply.github.com> Date: Thu, 21 May 2020 14:21:40 -0400 Subject: [PATCH 15/22] Update dns-over-https.md Add command for creating configuration file --- docs/guides/dns-over-https.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/guides/dns-over-https.md b/docs/guides/dns-over-https.md index 793d9ba..f0bc295 100644 --- a/docs/guides/dns-over-https.md +++ b/docs/guides/dns-over-https.md @@ -57,7 +57,11 @@ Create a `cloudflared` user to run the daemon: sudo useradd -s /usr/sbin/nologin -r -M cloudflared ``` -Proceed to create a configuration file for `cloudflared` by copying the following in to `/etc/default/cloudflared`. This file contains the command-line options that get passed to cloudflared on startup: +Proceed to create a configuration file for `cloudflared`: +```bash +sudo nano /etc/default/cloudflared +``` +Edit configuration file by copying the following in to `/etc/default/cloudflared`. This file contains the command-line options that get passed to cloudflared on startup: ```bash # Commandline args for cloudflared From 46f3e8105ff438ce2a63040a8d18d6fbb19ad6a1 Mon Sep 17 00:00:00 2001 From: iatacs19 <33841205+iatacs19@users.noreply.github.com> Date: Thu, 21 May 2020 20:08:43 -0400 Subject: [PATCH 16/22] Update docs/guides/dns-over-https.md Co-authored-by: Dan Schaper --- docs/guides/dns-over-https.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guides/dns-over-https.md b/docs/guides/dns-over-https.md index f0bc295..52c439f 100644 --- a/docs/guides/dns-over-https.md +++ b/docs/guides/dns-over-https.md @@ -58,9 +58,11 @@ sudo useradd -s /usr/sbin/nologin -r -M cloudflared ``` Proceed to create a configuration file for `cloudflared`: + ```bash sudo nano /etc/default/cloudflared ``` + Edit configuration file by copying the following in to `/etc/default/cloudflared`. This file contains the command-line options that get passed to cloudflared on startup: ```bash From 434157593cd1f239a3cc05494862f549e24df0c4 Mon Sep 17 00:00:00 2001 From: "dependabot-preview[bot]" <27856297+dependabot-preview[bot]@users.noreply.github.com> Date: Sat, 23 May 2020 13:31:05 +0300 Subject: [PATCH 17/22] Bump mkdocs-material from 5.1.6 to 5.2.1 (#321) Bumps [mkdocs-material](https://github.com/squidfunk/mkdocs-material) from 5.1.6 to 5.2.1. - [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/5.1.6...5.2.1) Signed-off-by: dependabot-preview[bot] Co-authored-by: dependabot-preview[bot] <27856297+dependabot-preview[bot]@users.noreply.github.com> --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index ea215c8..8b1e8b7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ markdown-include==0.5.1 mkdocs==1.1.2 mkdocs-git-revision-date-localized-plugin==0.5.2 -mkdocs-material==5.1.6 +mkdocs-material==5.2.1 From c7a15d5b5b5f1aeafd36e991f92993180e9c0361 Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Sun, 24 May 2020 07:43:39 +0300 Subject: [PATCH 18/22] CSS cleanup (#322) These don't seem to be needed with the latest mkdocs-material version. --- docs/extra.css | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/docs/extra.css b/docs/extra.css index eabe03b..c2c63d7 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -19,23 +19,6 @@ input { color: #532ba8; } -.md-logo img { - width: 48px; - height: 48px; -} - -@media only screen and (min-width: 76.25em) { - .md-logo img { - width: 24px; - height: 24px; - } -} - .text-center { text-align: center !important; } - -/* needed because images have `max-width: 100%` in the theme */ -img { - height: auto; -} From eea7e43f93eef6f091cafe77f7305d94e732a61a Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Mon, 25 May 2020 01:27:21 +0100 Subject: [PATCH 19/22] Add overrides directory and include netlify deploy badge in footer Signed-off-by: Adam Warner --- mkdocs.yml | 1 + overrides/partials/footer.html | 59 ++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 overrides/partials/footer.html diff --git a/mkdocs.yml b/mkdocs.yml index 722cb52..8289fa1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,6 +6,7 @@ copyright: 'Copyright © 2020 Pi-hole LLC' remote_branch: gh-pages theme: name: 'material' + custom_dir: overrides # icon: # repo: fontawesome/brands/github-alt favicon: 'images/favicon.ico' diff --git a/overrides/partials/footer.html b/overrides/partials/footer.html new file mode 100644 index 0000000..2751945 --- /dev/null +++ b/overrides/partials/footer.html @@ -0,0 +1,59 @@ +{% import "partials/language.html" as lang with context %} + \ No newline at end of file From f91ee8c7c5fb176f4cd0241f6fabb56f6ba95b53 Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Mon, 25 May 2020 01:45:16 +0100 Subject: [PATCH 20/22] Update overrides/partials/footer.html Co-authored-by: Dan Schaper --- overrides/partials/footer.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/overrides/partials/footer.html b/overrides/partials/footer.html index 2751945..dd4036f 100644 --- a/overrides/partials/footer.html +++ b/overrides/partials/footer.html @@ -49,11 +49,11 @@ Material for MkDocs
- + This site is powered by Netlify {% include "partials/social.html" %} - \ No newline at end of file + From 1e25dbfaba389c5c5240120ccdbc4edd77d1894c Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Mon, 25 May 2020 11:15:20 +0300 Subject: [PATCH 21/22] Update footer.html --- overrides/partials/footer.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/overrides/partials/footer.html b/overrides/partials/footer.html index dd4036f..85f5cb6 100644 --- a/overrides/partials/footer.html +++ b/overrides/partials/footer.html @@ -49,8 +49,8 @@ Material for MkDocs
- - This site is powered by Netlify + + This site is powered by Netlify {% include "partials/social.html" %} From 594813bad8c3b1feaa363f175c7fe1db94e0603e Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Mon, 25 May 2020 13:49:18 +0100 Subject: [PATCH 22/22] Revert "Update footer.html" --- overrides/partials/footer.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/overrides/partials/footer.html b/overrides/partials/footer.html index 85f5cb6..dd4036f 100644 --- a/overrides/partials/footer.html +++ b/overrides/partials/footer.html @@ -49,8 +49,8 @@ Material for MkDocs
- - This site is powered by Netlify + + This site is powered by Netlify {% include "partials/social.html" %}