pi-hole/docs
1
0
Fork 0
mirror of https://github.com/pi-hole/docs.git synced 2024-12-06 19:27:12 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge branch 'master' into patch-1

Browse Source
This commit is contained in:
XhmikosR
2020-02-28 23:07:20 +02:00
committed by GitHub
parent 1710b6e3e6 704bf81ae8
commit 9438964c3d
4 changed files with 134 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2 -2
View File
@@ -12,7 +12,7 @@ The Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) is a
This repo is the source for the official [Pi-hole documentation](https://docs.pi-hole.net/).
### How to contribute.
### How to contribute
To add a new link on the navigation panel you need to edit the `mkdocs.yml` file in the root of the repo. There is a guide for building the navbar [on the mkdocs wiki](https://www.mkdocs.org/user-guide/configuration/#nav)
@@ -24,7 +24,7 @@ To add a new document or guide.
EG. `docs/guides/url-friendly.md`
- Edit your document using Markdown, there are loads of resources available for the correct syntax.
### Testing your changes.
### Testing your changes
When working on this repo, it is advised that you review your changes locally before committing them. The `mkdocs serve` command can be used to live preview your changes (as you type) on your local machine.
docs/guides/dns-over-https.md
+104 -11
View File
@@ -47,9 +47,11 @@ sudo chmod +x /usr/local/bin/cloudflared
cloudflared -v
```
#### Configuring `cloudflared` to run on startup
### Configuring `cloudflared` to run on startup
Create a cloudflared user to run the daemon:
#### Manual way
Create a `cloudflared` user to run the daemon:
```bash
sudo useradd -s /usr/sbin/nologin -r -M cloudflared
@@ -71,6 +73,10 @@ sudo chown cloudflared:cloudflared /usr/local/bin/cloudflared
Then create the `systemd` script by copying the following into `/etc/systemd/system/cloudflared.service`. This will control the running of the service and allow it to run on startup:
```bash
sudo nano /etc/systemd/system/cloudflared.service
```
```ini
[Unit]
Description=cloudflared DNS over HTTPS proxy
@@ -97,38 +103,125 @@ sudo systemctl start cloudflared
sudo systemctl status cloudflared
```
Now test that it is working! Run the following `dig` command, a response should be returned similar to the one below:
#### Automatic way
<!-- markdownlint-disable code-block-style -->
!!! warning
Keep in mind that this will install `cloudflared` as root.
<!-- markdownlint-enable code-block-style -->
Proceed to create a configuration file for `cloudflared` in `/etc/cloudflared` named `config.yml`:
```bash
dig @127.0.0.1 -p 5053 google.com
sudo mkdir /etc/cloudflared/
sudo nano /etc/cloudflared/config.yml
```
Copy the following configuration:
; <<>> DiG 9.10.3-P4-Ubuntu <<>> @127.0.0.1 -p 5053 google.com
```yaml
proxy-dns: true
proxy-dns-port: 5053
proxy-dns-upstream:
- https://1.1.1.1/dns-query
- https://1.0.0.1/dns-query
```
Now install the service via `cloudflared`'s [service command](https://developers.cloudflare.com/argo-tunnel/reference/arguments/#service-command):
```bash
sudo cloudflared service install
```
Start the `systemd` service and check its status:
```bash
sudo systemctl start cloudflared
sudo systemctl status cloudflared
```
Now test that it is working! Run the following `dig` command, a response should be returned similar to the one below:
```text
pi@raspberrypi:~ $ dig @127.0.0.1 -p 5053 google.com
; <<>> DiG 9.11.5-P4-5.1-Raspbian <<>> @127.0.0.1 -p 5053 google.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 65181
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 12157
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1536
; EDNS: version: 0, flags:; udp: 4096
; COOKIE: 22179adb227cd67b (echoed)
;; QUESTION SECTION:
;google.com. IN A
;; ANSWER SECTION:
google.com. 299 IN A 243.65.127.221
google.com. 191 IN A 172.217.22.14
;; Query time: 3 msec
;; Query time: 0 msec
;; SERVER: 127.0.0.1#5053(127.0.0.1)
;; MSG SIZE rcvd: 65
;; WHEN: Wed Dec 04 09:29:50 EET 2019
;; MSG SIZE rcvd: 77
```
### Configuring Pi-hole
Finally, configure Pi-hole to use the local `cloudflared` service as the upstream DNS server:
Finally, configure Pi-hole to use the local `cloudflared` service as the upstream DNS server by specifying `127.0.0.1#5053` as the Custom DNS:
![Screenshot of Pi-hole configuration](../images/DoHConfig.png)
(don't forget to hit Return or click on `Save`)
### Updating `cloudflared`
#### Manual way
```bash
# stop the service
sudo systemctl stop cloudflared
# fetch and copy the latest version
wget https://bin.equinox.io/c/VdrWdbjqyF/cloudflared-stable-linux-arm.tgz
tar -xvzf cloudflared-stable-linux-arm.tgz
sudo cp ./cloudflared /usr/local/bin
sudo chmod +x /usr/local/bin/cloudflared
sudo systemctl start cloudflared
# verify the service is working fine
sudo systemctl status cloudflared
```
#### Automatic way
```bash
sudo cloudflared update
sudo systemctl restart cloudflared
```
### Uninstalling `cloudflared`
#### If installed the manual way
*Courtesy of <https://discourse.pi-hole.net/t/uninstall-cloudflare/21459/3>*
```bash
sudo systemctl stop cloudflared
sudo systemctl disable cloudflared
sudo systemctl daemon-reload
sudo deluser cloudflared
sudo rm /etc/default/cloudflared
sudo rm /etc/systemd/system/cloudflared.service
sudo rm /usr/local/bin/cloudflared
```
#### If installed with `cloudflare service install`
```bash
sudo cloudflared service uninstall
sudo systemctl daemon-reload
```
After the above, don't forget to change the DNS back to something else in Pi-hole's DNS settings!
[^guide]: Based on [this guide by Ben Dews | bendews.com](https://bendews.com/posts/implement-dns-over-https/)
docs/guides/upstream-dns-providers.md
+14 -10
View File
@@ -28,15 +28,17 @@ Built-in features include a phishing filter, this is the OpenDNS version the Pi-
- 208.67.222.222
- 208.67.220.220
- 208.67.222.220
- 208.67.220.222
- 2620:119:35::35 (IPv6)
- 2620:119:53::53 (IPv6)
[More information on OpenDNS Home](https://use.opendns.com/) + [OpenDNS Wiki Page](https://en.wikipedia.org/wiki/OpenDNS)
[More information on OpenDNS Home](https://use.opendns.com/) + [OpenDNS Wikipedia Page](https://en.wikipedia.org/wiki/OpenDNS)
OpenDNS also provides the OpenDNS FamilyShield (free)- option. The service blocks pornographic content, including our “Pornography,” “Tasteless,” and “Sexuality” categories, in addition to proxies and anonymizers (which can render filtering useless). It also blocks phishing and some malware.
- 208.67.222.123
- 208.67.220.123
- 0000:0000:0000:0000:0000:ffff:d043:de7b (ipv6)
- 0000:0000:0000:0000:0000:ffff:d043:dc7b (ipv6)
[More information on OpenDNS FamilyShield](https://www.opendns.com/setupguide/#familyshield) + [OpenDNS FamilyShield introduction Blog](https://umbrella.cisco.com/blog/2010/06/23/introducing-familyshield-parental-controls/)
@@ -62,8 +64,8 @@ DNS.WATCH offers Fast, free and uncensored DNS resolution.
- 84.200.69.80
- 84.200.70.40
- 2001:1608:10:25::1c04:b12f (ipv6)
- 2001:1608:10:25::9249:d69b (ipv6)
- 2001:1608:10:25::1c04:b12f (IPv6)
- 2001:1608:10:25::9249:d69b (IPv6)
[More information on DNS.WATCH](https://dns.watch/)
@@ -73,24 +75,26 @@ Quad9 is a free, recursive, anycast DNS platform that provides end users robust
- 9.9.9.9
- 149.112.112.112
- 2620:fe::fe (ipv6)
- 2620:fe::fe (IPv6)
- 2620:fe::9 (IPv6)
[More information on Quad9](https://www.quad9.net/about/)
### CloudFlare DNS
CloudFlare will never log your IP address (the way other companies identify you). The independent DNS monitor DNSPerf ranks 1.1.1.1 the fastest DNS service in the world.
CloudFlare will never log your IP address (the way other companies identify you). The independent DNS monitor [DNSPerf](https://www.dnsperf.com/) ranks Cloudflare's DNS the fastest DNS service in the world.
- 1.1.1.1
- 1.0.0.1
- 2606:4700:4700::1111 (IPv6)
- 2606:4700:4700::1001 (IPv6)
[More information on Cloudflare DNS](https://cloudflare-dns.com/dns/#explanation)
### Custom
With custom, you'll choose your favorite DNS provider.
If you care about Internet independence and privacy, we suggest having a look at the [OpenNIC DNS Project](https://servers.opennic.org/)
With custom, you'll choose your favorite DNS provider. If you care about Internet independence and privacy, we suggest having a look at the [OpenNIC DNS Project](https://servers.opennic.org/).
### More information
There are even more public DNS server, you can find many (with some extra information) on the [lifewire.com website](https://www.lifewire.com/free-and-public-dns-servers-2626062). A benchmark of these DNS servers (by Gibson Research Center) is available [here](https://www.grc.com/dns/Benchmark.htm)
There are even more public DNS server, you can find many (with some extra information) on [this](https://www.lifewire.com/free-and-public-dns-servers-2626062) Lifewire page. A benchmark of these DNS servers (by Gibson Research Center) is available [here](https://www.grc.com/dns/Benchmark.htm).
docs/main/prerequesites.md
+14 -8
View File
@@ -44,7 +44,7 @@ Due to the complexity of different ways of setting an IP address across differen
| 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. |
| 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 | TCP | FTL is our API engine and uses port 4711 on the localhost interface. This port should not be accessible from any other interface.|
| 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.
@@ -53,6 +53,8 @@ Due to the complexity of different ways of setting an IP address across differen
### Firewalls
Below are some examples of firewall rules that will need to be set on your Pi-hole server in order to use the functions available. These are only shown as guides, the actual commands used will be found with your distribution's documentation.
Because Pi-hole was designed to work inside a local network, the following rules will block the traffic from the Internet for security reasons. `192.168.0.0/16` is the most common local network IP range for home users but it can be different in your case, for example other common local network IPs are `10.0.0.0/8` and `172.16.0.0/12`.
**Check your local network settings before applying these rules.**
#### IPTables
@@ -61,18 +63,22 @@ IPTables uses two sets of tables. One set is for IPv4 chains, and the second is
IPTables (IPv4)
```bash
iptables -I INPUT 1 -p tcp -m tcp --dport 80 -j ACCEPT
iptables -I INPUT 1 -p tcp -m tcp --dport 53 -j ACCEPT
iptables -I INPUT 1 -p udp -m udp --dport 53 -j ACCEPT
iptables -I INPUT 1 -p tcp -m tcp --dport 67 -j ACCEPT
iptables -I INPUT 1 -p udp -m udp --dport 67 -j ACCEPT
iptables -I INPUT 1 -p tcp -m tcp --dport 4711 -i lo -j ACCEPT
iptables -I INPUT 1 -s 192.168.0.0/16 -p tcp -m tcp --dport 80 -j ACCEPT
iptables -I INPUT 1 -s 127.0.0.0/8 -p tcp -m tcp --dport 53 -j ACCEPT
iptables -I INPUT 1 -s 127.0.0.0/8 -p udp -m udp --dport 53 -j ACCEPT
iptables -I INPUT 1 -s 192.168.0.0/16 -p tcp -m tcp --dport 53 -j ACCEPT
iptables -I INPUT 1 -s 192.168.0.0/16 -p udp -m udp --dport 53 -j ACCEPT
iptables -I INPUT 1 -s 192.168.0.0/16 -p tcp -m tcp --dport 67 -j ACCEPT
iptables -I INPUT 1 -s 192.168.0.0/16 -p udp -m udp --dport 67 -j ACCEPT
iptables -I INPUT 1 -p tcp -m tcp --dport 4711:4720 -i lo -j ACCEPT
iptables -I INPUT -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
```
IP6Tables (IPv6)
```bash
ip6tables -I INPUT -p udp -m udp --sport 546:547 --dport 546:547 -j ACCEPT
ip6tables -I INPUT -s fe80::/10 -p udp -m udp --sport 546:547 --dport 546:547 -j ACCEPT
ip6tables -I INPUT -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
```
#### FirewallD