diff --git a/README.md b/README.md index d8f5e1a..621bb62 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/guides/dns-over-https.md b/docs/guides/dns-over-https.md index 8ed90d0..9b2979e 100644 --- a/docs/guides/dns-over-https.md +++ b/docs/guides/dns-over-https.md @@ -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 + + +!!! warning + Keep in mind that this will install `cloudflared` as root. + + +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 * + +```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/) diff --git a/docs/main/prerequesites.md b/docs/main/prerequesites.md index aa77fa6..269e2a8 100644 --- a/docs/main/prerequesites.md +++ b/docs/main/prerequesites.md @@ -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