->  ->
->  + + + +--- + + + +--- + + Afterwards, modify your `ddclient` config file to look like: -``` + +```bash protocol=dyndns2 use=if, if=eth0 use=web, web=checkip.dyndns.org @@ -81,4 +91,5 @@ password='password1234' meine.domain.de ``` + where you replace `strato-login-name` by your Strato login name (most likely your domain name, like `maxmustermann.de`), `password1234` by the password you configured above (see third screenshot), and `meine.domain.de` by the subdomain you created and enabled dynamic DNS for. diff --git a/docs/guides/vpn/firewall.md b/docs/guides/vpn/firewall.md index b39c180..09ae866 100644 --- a/docs/guides/vpn/firewall.md +++ b/docs/guides/vpn/firewall.md @@ -12,7 +12,7 @@ It's recommended that you [clear out your entire firewall](https://serverfault.c Enter this command, which will allow all traffic through the VPN `tun0` interface. -``` +```bash iptables -I INPUT -i tun0 -j ACCEPT ``` @@ -20,7 +20,7 @@ iptables -I INPUT -i tun0 -j ACCEPT These commands will allow DNS and HTTP needed for name resolution (using Pi-hole as a resolver) and accessing the Web interface, respectively. -``` +```bash iptables -A INPUT -i tun0 -p tcp --destination-port 53 -j ACCEPT iptables -A INPUT -i tun0 -p udp --destination-port 53 -j ACCEPT iptables -A INPUT -i tun0 -p tcp --destination-port 80 -j ACCEPT @@ -28,7 +28,7 @@ iptables -A INPUT -i tun0 -p tcp --destination-port 80 -j ACCEPT You will also want to enable SSH and VPN access from anywhere. -``` +```bash iptables -A INPUT -p tcp --destination-port 22 -j ACCEPT iptables -A INPUT -p tcp --destination-port 1194 -j ACCEPT iptables -A INPUT -p udp --destination-port 1194 -j ACCEPT @@ -36,19 +36,19 @@ iptables -A INPUT -p udp --destination-port 1194 -j ACCEPT The next crucial setting is to explicitly allow TCP/IP to do "three way handshakes": -``` +```bash iptables -I INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT ``` Also, we want to allow any loopback traffic, i.e. the server is allowed to talk to itself without any limitations using 127.0.0.0/8: -``` +```bash iptables -I INPUT -i lo -j ACCEPT ``` Finally, reject access from anywhere else (i.e. if no rule has matched up to this point): -``` +```bash iptables -P INPUT DROP ``` @@ -58,7 +58,7 @@ Since you're `:head-desk:`ing with `iptables`, you can also use this opportunity > Why doesn't Pi-hole just use a certificate to prevent this? The answer is [here](https://discourse.pi-hole.net/t/slow-loading-websites/3408/12). -``` +```bash iptables -A INPUT -p udp --dport 80 -j REJECT --reject-with icmp-port-unreachable iptables -A INPUT -p tcp --dport 443 -j REJECT --reject-with tcp-reset iptables -A INPUT -p udp --dport 443 -j REJECT --reject-with icmp-port-unreachable @@ -70,7 +70,7 @@ Depending on the systems you have connecting, you may benefit from appending `-- If your server is reachable via IPv6, you'll need to run the same commands but using `ip6tables`: -``` +```bash ip6tables -A INPUT -i tun0 -p tcp --destination-port 53 -j ACCEPT ip6tables -A INPUT -i tun0 -p udp --destination-port 53 -j ACCEPT ip6tables -A INPUT -i tun0 -p tcp --destination-port 80 -j ACCEPT @@ -84,15 +84,16 @@ ip6tables -A INPUT -p tcp --dport 443 -j REJECT --reject-with tcp-reset ip6tables -A INPUT -p udp --dport 443 -j REJECT --reject-with icmp6-port-unreachable ip6tables -P INPUT DROP ``` + View the rules you just created -``` +```bash iptables -L --line-numbers ``` and they should look something like this: -``` +```text Chain INPUT (policy DROP) num target prot opt source destination 1 ACCEPT all -- anywhere anywhere @@ -124,7 +125,7 @@ num target prot opt source destination Similarly, `ip6tables -L --line-numbers` should look like this: -``` +```text Chain INPUT (policy DROP) num target prot opt source destination 1 ACCEPT all anywhere anywhere @@ -153,14 +154,14 @@ Connect to the VPN as a client and verify you can resolve DNS names as well as a If things look good, you may want to save your rules so you can revert to them if you ever make changes to the firewall. Save them with these commands: -``` +```bash iptables-save > /etc/pihole/rules.v4 ip6tables-save > /etc/pihole/rules.v6 ``` Similarly, you can restore these rules: -``` +```bash iptables-restore < /etc/pihole/rules.v4 ip6tables-restore < /etc/pihole/rules.v6 ``` diff --git a/docs/guides/vpn/installation.md b/docs/guides/vpn/installation.md index 56a67d6..348896c 100644 --- a/docs/guides/vpn/installation.md +++ b/docs/guides/vpn/installation.md @@ -10,17 +10,19 @@ For security purposes, it is recommended that the CA machine should be separate This is less convenient, so many users will simply decide to install Pi-hole and OpenVPN on a single machine, which is what this guide will walkthrough. - ### Install the OpenVPN server First, download the OpenVPN installer; make it executable, and then run it: -``` + +```bash wget https://git.io/vpn -O openvpn-install.sh chmod 755 openvpn-install.sh ./openvpn-install.sh ``` + Enter your server's IP address and accept all the defaults, unless you require special needs: -``` + +```text Welcome to this quick OpenVPN "road warrior" installer I need to ask you a few questions before starting the setup @@ -54,17 +56,20 @@ Client name: pihole Okay, that was all I needed. We are ready to setup your OpenVPN server now Press any key to continue... ``` + Let the installer run... -``` + +```text Finished! Your client configuration is available at /root/pihole.ovpn If you want to add more clients, you simply need to run this script again! ``` + ### Install Pi-hole Next, install Pi-hole and choose `tun0` as the interface and `10.8.0.1/24` as the IP address. You can accept the rest of the defaults, or configure Pi-hole to your liking. The interface selection is the most important step; if you don't choose `tun0` (at least to begin with), it will not work properly. -``` +```bash curl -sSL https://install.pi-hole.net | bash ``` diff --git a/docs/guides/vpn/only-dns-via-vpn.md b/docs/guides/vpn/only-dns-via-vpn.md index 378f7b1..77f902c 100644 --- a/docs/guides/vpn/only-dns-via-vpn.md +++ b/docs/guides/vpn/only-dns-via-vpn.md @@ -4,7 +4,7 @@ With this setup, you will force connected clients to use **only the DNS provided Edit your `/etc/openvpn/server/server.conf` and remove (comment out) the following line: -``` +```ini # push "redirect-gateway def1 bypass-dhcp" ``` @@ -23,11 +23,14 @@ When using the Network Manager, you will have to do some additional setting on t #### Alternative 1: Disable Network Manager's internal DNS server Edit `/etc/NetworkManager/NetworkManager.conf`: -``` + +```ini # dns=dnsmasq ``` + and restart the Network Manager: -``` + +```bash sudo restart network-manager ``` @@ -40,7 +43,8 @@ You can also set the address of the DNS server manually (use the device which ac  After doing either alternative, you should see: -``` + +```text pi.hole has address W.X.Y.Z (outside address of your VPN server) pi.hole has IPv6 address A:B:C:D:E:F (outside address of your VPN server) ``` @@ -50,16 +54,19 @@ The web interface of your Pi-hole will be visible at `http://pi.hole/admin/` (ev  --- + ## Troubleshooting If your new DNS server configuration has not been activated (try restarting the interface / system) you will see -``` + +```text host pi.hole Host pi.hole not found: 3(NXDOMAIN) ``` If you are not connected to your VPN network you will see -``` + +```text host pi.hole ;; connection timed out; no servers could be reached ``` diff --git a/docs/guides/vpn/overview.md b/docs/guides/vpn/overview.md index a77d933..fdab36a 100644 --- a/docs/guides/vpn/overview.md +++ b/docs/guides/vpn/overview.md @@ -1,6 +1,7 @@ >This tutorial is tailored for setting up OpenVPN on a cloud-hosted virtual server (such as [Digital Ocean](https://www.digitalocean.com/?refcode=344d234950e1)). If you wish to have this working on your home network, you will need to tailor Pi-hole to listen on `eth0` (or similar), which we explain in [this section of the tutorial](dual-operation.md). ### High-level Overview + Using a VPN is a responsible, respectful, and safe way to access your Pi-hole's capabilities remotely. Setting up a DNS server has become a simple task with Pi-hole's automated installer, which has resulted in many people knowingly--or unknowingly--creating an open resolver, which aids in DNS Amplification Attacks. We do not encourage open resolvers but there are always people wanting access to their ad-blocking capabilities outside of their home network, whether it's on their cellular network or on an unsecured wireless network. This article aims to provide a step-by-step walk-through on setting up a server running Pi-hole and OpenVPN so you can connect to your Pi-hole's DNS from anywhere. This guide should work for a private server installed on your private network, but it will also work for cloud servers, such as those created on [Digital Ocean](https://www.digitalocean.com/?refcode=344d234950e1). @@ -18,4 +19,5 @@ If you don't want a full-tunnel, we provide a wiki of how to [set up your server 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 --- + This manual is partially based on this [HowTo](https://discourse.pi-hole.net/t/pi-hole-with-openvpn-vps-debian/861) on [Discourse](https://discourse.pi-hole.net). diff --git a/docs/guides/vpn/setup-openvpn-server.md b/docs/guides/vpn/setup-openvpn-server.md index ba2e0d1..466a486 100644 --- a/docs/guides/vpn/setup-openvpn-server.md +++ b/docs/guides/vpn/setup-openvpn-server.md @@ -3,17 +3,20 @@ First, find the IP of your `tun0` interface: On Jessie -``` + +```bash ifconfig tun0 | grep 'inet addr' ``` + On Stretch -``` + +```bash ip a ``` Edit the OpenVPN config file: -``` +```bash vim /etc/openvpn/server/server.conf ``` @@ -29,6 +32,7 @@ This `push` directive is setting a [DHCP option](https://www.incognito.com/tutor It's [suggested to have Pi-hole be the only resolver](https://discourse.pi-hole.net/t/why-should-pi-hole-be-my-only-dns-server/3376) as it defines the upstream servers. Setting a non-Pi-hole resolver here [may have adverse effects on ad blocking](https://discourse.pi-hole.net/t/why-should-pi-hole-be-my-only-dns-server/3376) but it _can_ provide failover connectivity in the case of Pi-hole not working if that is something you are concerned about. Furthermore, you might want to enable logging for your OpenVPN server. In this case, add the following lines to your server's config file: + ``` log /var/log/openvpn.log verb 3 @@ -37,7 +41,8 @@ verb 3 ### Restart OpenVPN to apply the changes Depending on your operating system, one of these commands should work to restart the service. -``` + +```bash systemctl restart openvpn-server@server service openvpn-server@server restart ``` @@ -50,12 +55,13 @@ You can repeat this process for as many clients as you need. In this example, w Run the OpenVPN installer again -``` +```bash ./openvpn-install.sh ``` Choose `1) Add a new user` and enter a client name -``` + +```text Looks like OpenVPN is already installed What do you want to do? diff --git a/docs/guides/vpn/troubleshooting.md b/docs/guides/vpn/troubleshooting.md index bd2e640..bf03b0a 100644 --- a/docs/guides/vpn/troubleshooting.md +++ b/docs/guides/vpn/troubleshooting.md @@ -1,15 +1,20 @@ ### CRL expired + OpenVPN 2.4 and newer check the validity of the Certificate Revocation List (CRL). This can result in a sudden malfunction of `openvpn` after an update even though no configuration files have changed. This error manifests in the following, not very helpful, error on the client side: + ``` Wed Apr 24 11:19:07 2019 VERIFY OK: depth=0, CN=server Wed Apr 24 11:19:07 2019 Connection reset, restarting [0] Wed Apr 24 11:19:07 2019 SIGUSR1[soft,connection-reset] received, process restarting Wed Apr 24 11:19:07 2019 Restart pause, 5 second(s) ``` + Android clients simply report: "Transport error, trying to reconnect..." + >  On the OpenVPN server, the following messages are logged: + ``` Wed Apr 24 11:19:07 2019 aaa.bbb.ccc.ddd:pppp TLS: Initial packet from [AF_INET]aaa.bbb.ccc.ddd:pppp, sid=57719cb8 77945ae9 Wed Apr 24 11:19:07 2019 aaa.bbb.ccc.ddd:pppp VERIFY ERROR: depth=0, error=CRL has expired: CN=client1 @@ -20,7 +25,9 @@ Wed Apr 24 11:19:07 2019 aaa.bbb.ccc.ddd:pppp TLS Error: TLS handshake failed Wed Apr 24 11:19:07 2019 aaa.bbb.ccc.ddd:pppp Fatal TLS error (check_tls_errors_co), restarting Wed Apr 24 11:19:07 2019 aaa.bbb.ccc.ddd:pppp SIGUSR1[soft,tls-error] received, client-instance restarting ``` + The error is `CRL has expired` and can be solved using the following commands: + ``` sudo -s cd /etc/openvpn diff --git a/docs/guides/whitelist-blacklist.md b/docs/guides/whitelist-blacklist.md index 5d4fc08..58c7eab 100644 --- a/docs/guides/whitelist-blacklist.md +++ b/docs/guides/whitelist-blacklist.md @@ -2,10 +2,9 @@ [This extension for Google Chrome](https://chrome.google.com/webstore/detail/adamone-assistant/fdmpekabnlekabjlimjkfmdjajnddgpc) can help you in finding out which domains you need to whitelist. - ### How to Whitelist or Blacklist -There are scripts to aid users in adding or removing domains to the 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. @@ -16,11 +15,11 @@ Each script accepts the following parameters:
[domain]-d-nrpihole -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 | @@ -61,19 +59,18 @@ Domains passed are parsed by the script to ensure they are valid domains. If a d To remove domains from the whitelist: Add `-d` as an additional argument (e.g `pihole -w -d domain1 [domain2...]`) - -##### Example `pihole -b` usages +#### 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 | @@ -82,4 +79,4 @@ Add `-d` as an additional argument (e.g `pihole -w -d domain1 [domain2...]`)
Network-wide ad blocking via your own Linux hardware
@@ -24,17 +25,20 @@ The Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) is a
-----
## Pi-hole is free, but powered by your support
+
There are many reoccurring costs involved with maintaining free, open source, and privacy respecting software; expenses which [our volunteer developers](https://github.com/orgs/pi-hole/people) pitch in to cover out-of-pocket. This is just one example of how strongly we feel about our software, as well as the importance of keeping it maintained.
Make no mistake: **your support is absolutely vital to help keep us innovating!**
### Donations
+
Sending a donation using our links below is **extremely helpful** in offsetting a portion of our monthly expenses:
-- Donate via PayPal or Stripe
+- [Donate via PayPal or Stripe](https://pi-hole.net/donate/)
- [Bitcoin, Bitcoin Cash, Ethereum, Litecoin](https://commerce.coinbase.com/checkout/dd304d04-f324-4a77-931b-0db61c77a41b)
### Alternative support
+
If you'd rather not donate (_which is okay!_), there are other ways you can help support us:
- [Pi-hole Swag Store](https://pi-hole.net/shop/)
@@ -44,6 +48,7 @@ If you'd rather not donate (_which is okay!_), there are other ways you can help
- Spreading the word about our software, and how you have benefited from it
### Contributing via GitHub
+
We welcome _everyone_ to contribute to issue reports, suggest new features, and create pull requests.
If you have something to add - anything from a typo through to a whole new feature, we're happy to check it out! Just make sure to fill out our template when submitting your request; the questions that it asks will help the volunteers quickly understand what you're aiming to achieve.
diff --git a/docs/main/basic-install.md b/docs/main/basic-install.md
index 6ebed49..c68a7d1 100644
--- a/docs/main/basic-install.md
+++ b/docs/main/basic-install.md
@@ -1,7 +1,8 @@
## One-Step Automated Install
+
Those who want to get started quickly and conveniently, may install Pi-hole using the following command:
-```BASH
+```bash
curl -sSL https://install.pi-hole.net | bash
```
@@ -11,14 +12,16 @@ curl -sSL https://install.pi-hole.net | bash
If you would prefer to review the code before installation, we provide these alternative installation methods.
#### Alternative 1: Clone our repository and run
-```BASH
+
+```bash
git clone --depth 1 https://github.com/pi-hole/pi-hole.git Pi-hole
cd "Pi-hole/automated install/"
sudo bash basic-install.sh
```
#### Alternative 2: Manually download the installer and run
-```BASH
+
+```bash
wget -O basic-install.sh https://install.pi-hole.net
sudo bash basic-install.sh
```
diff --git a/docs/main/contact.md b/docs/main/contact.md
index 368def6..8c201ca 100755
--- a/docs/main/contact.md
+++ b/docs/main/contact.md
@@ -4,9 +4,7 @@ description: Pi-hole contacts and social media
last_updated: Sun Jan 13 18:33:27 2019 UTC
---
-
-
-While we are primarily reachable on our Discourse User Forum, we can also be found on a variety of social media outlets. **Please be sure to check the FAQ's** before starting a new discussion, as we do not have the spare time to reply to every request for assistance.
+While we are primarily reachable on our [Discourse User Forum](https://discourse.pi-hole.net/), we can also be found on a variety of social media outlets. **Please be sure to check the FAQ's** before starting a new discussion, as we do not have the spare time to reply to every request for assistance.
- [Frequently Asked Questions](https://discourse.pi-hole.net/c/faqs)
- [Feature Requests](https://discourse.pi-hole.net/c/feature-requests?order=votes)
@@ -17,4 +15,4 @@ While we are primarily reachable on our