Merge pull request #13 from pi-hole/tweak/guides/vpn

Complete migration of VPN tutorial

docs/guides/vpn/android-client.md

@@ -0,0 +1,22 @@
+1. Install the official OpenVPN App
+  See [App Store](https://play.google.com/store/apps/details?id=net.openvpn.openvpn)
+
+2. Create a new certificate as described [here](clients.md#create-certificate)
+
+3. Copy the mentioned file (`/root/android.ovpn`) to your Android device (e.g. SD card) and import it in the app:
+
+ ![](Android-Import-1.png)
+
+ ![](Android-Import-2.png)
+
+ ![](Android-Import-3.png)
+
+ ![](Android-Import-4.png)
+
+4. Connect to your OpenVPN server
+
+ ![](Android-Connected.png)
+
+5. You are ready to go!
+
+ ![](Android-Pi-hole.png)

docs/guides/vpn/clients.md

@@ -1,11 +1,46 @@
-**See bottom of this page for how to generate additional client certificates**
-
 ### Connect from a client
 There are various tutorials available for all operating systems for how to connect to an OpenVPN server.
 
-### Android
+### Create certificate
+Log into your OpenVPN server and use the road warrior installer to create a new certificate for your client:
+```
+bash openvpn-install.sh 
+```
 
-See special page [here](https://github.com/pi-hole/pi-hole/wiki/OpenVPN-server:-Connect-from-a-client-(Android)).
+```
+Looks like OpenVPN is already installed
+
+What do you want to do?
+   1) Add a cert for a new user
+   2) Revoke existing user cert
+   3) Remove OpenVPN
+   4) Exit
+Select an option [1-4]: 1
+
+Tell me a name for the client cert
+Please, use one word only, no special characters
+Client name: android
+Generating a 2048 bit RSA private key
+.....+++
+..................................+++
+writing new private key to '...'
+-----
+Using configuration from /etc/openvpn/easy-rsa/openssl-1.0.cnf
+Check that the request matches the signature
+Signature ok
+The Subject's Distinguished Name is as follows
+commonName            :ASN.1 12:'android'
+Certificate is to be certified until Jan 25 15:07:37 2027 GMT (3650 days)
+
+Write out database with 1 new entries
+Data Base Updated
+
+Client android added, configuration is available at /root/android.ovpn
+```
+
+**WARNING** Anyone who gets his hands on this configuration/certificate file can obtain full access to your VPN. Make sure that you use only trusted paths for transferring the file (e.g. *never* send it via an un-encrypted channel, e.g. email or FTP). Best strategy is to use a USB thumb drive to avoid any network transport at all. Make sure to delete the certificate on the USB drive afterwards.
+
+**NOTICE** If one of your certificates has been compromised, remove it using option `2` (see above) and generate a new certificate. This will effectively lock out anyone who might have gotten access to the certificate.
 
 ### Linux
 I'll demonstrate the procedure here for Ubuntu Linux (which trivially extends to Linux Mint, etc.)
@@ -27,58 +62,15 @@ You will need:
 * TA Key: `/etc/openvpn/ta.key`
 
 Further details can be found in the screenshots provided below:
-![](http://www.dl6er.de/pi-hole/openVPN/conn_type.png)
-![](http://www.dl6er.de/pi-hole/openVPN/keys.png)
-![](http://www.dl6er.de/pi-hole/openVPN/general.png)
-![](http://www.dl6er.de/pi-hole/openVPN/security.png)
-![](http://www.dl6er.de/pi-hole/openVPN/tls.png)
+![](NetworkManager3.png)
+![](NetworkManager4.png)
+![](NetworkManager5.png)
+![](NetworkManager6.png)
+![](NetworkManager7.png)
 
 Your whole network traffic will now securely be transferred to your Pi-hole.
-![](http://www.dl6er.de/pi-hole/openVPN/VPNclients.png)
+![](VPNclients.png)
 
 ### Windows
 
-You will have to install additional software. See https://openvpn.net/index.php/open-source/downloads.html
-
----
-
-### Optional: Add more client certificates
-
-You have to generate an individual certificate for each client. This can be done very conveniently like shown below:
-<pre>
-<b>sudo bash openvpn-install.sh</b>
-
-Looks like OpenVPN is already installed
-
-What do you want to do?
-   <b>1) Add a new user</b>
-   2) Revoke an existing user
-   3) Remove OpenVPN
-   4) Exit
-Select an option [1-4]: <b>1</b>
-
-Tell me a name for the client certificate
-Please, use one word only, no special characters
-Client name: thinkpad2
-Generating a 2048 bit RSA private key
-.......................+++
-....+++
-writing new private key to '/etc/openvpn/easy-rsa/pki/private/thinkpad2.key.kHwbBkvK9b'
------
-Using configuration from /etc/openvpn/easy-rsa/openssl-1.0.cnf
-Check that the request matches the signature
-Signature ok
-The Subject's Distinguished Name is as follows
-commonName            :ASN.1 12:'thinkpad2'
-Certificate is to be certified until Feb 28 10:24:26 2027 GMT (3650 days)
-
-Write out database with 1 new entries
-Data Base Updated
-
-<b>Client thinkpad2 added, configuration is available at /root/thinkpad2.ovpn</b>
-</pre>
-Copy the file `/root/thinkpad2.ovpn` to your new client.
-
-**WARNING** Anyone who gets his hands on this configuration/certificate file can obtain full access to your VPN. Make sure that you use only trusted paths for transferring the file (e.g. *never* send it via an un-encrypted channel, e.g. email or FTP). Best strategy is to use an USB thumbdrive to avoid any network transport at all. Make sure to delete the certificate on the USB drive afterwards.
-
-**NOTICE** If one of your certificates has been compromised, remove it using option `2` (see above) and generate a new certificate. This will effectively lock out anyone who might have gotten access to the certificate.
+You will have to install additional software. See https://openvpn.net/index.php/open-source/downloads.html

docs/guides/vpn/dual-operation.md

@@ -1,64 +1,70 @@
-### Optional: Only route DNS via VPN
+**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 setup in a private network like on a Raspberry Pi.**
 
-With this setup you will force connected clients to use only the DNS provided by the VPN connection, i.e. the Pi-hole. Do this only if you **don't** want to tunnel all traffic from the client thru the VPN, but only its DNS queries.
+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 behaviour 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`.
+
+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 additional benefit, you will be able to reach all devices in the internal network (e.g. computers, networking-aware printers, etc.) through the VPN.
+
+This setup assumes that your local network is in the range **192.168.2.0** (i.e. device addresses are in the range of 192.168.2.1 - 192.168.2.254). If this is not the case for you, you have to adjust the settings, accordingly, e.g.
+
+- devices in 192.168.0.1 - 192.168.0.254 -> `route 192.168.0.0`
+- devices in 192.168.123.1 - 192.168.123.254 -> `route 192.168.123.0`
+
+Edit your `/etc/openvpn/server.conf`:
 
-Edit your `/etc/openvpn/server.conf` and remove (comment) the following line:
 ```
-# push "redirect-gateway def1 bypass-dhcp"
+push "route 192.168.2.0 255.255.255.0"
+push "dhcp-option DNS <b>192.168.2.123</b>"
 ```
 
-### Using a client config file
+As you can see, we change the address of the DNS server to the local IP address of our Pi-hole (which is **192.168.2.123** in this example).
 
-This works pretty much out of the box with common `client.ovpn` files, like this provided one: [client.ovpn](http://www.dl6er.de/pi-hole/openVPN/client.ovpn)
+Afterwards, we change the interface of `Pi-hole` to `eth0` (your local network adapter instead of the VPN adapter `tun0`). This can conveniently be done by using `pihole -r` + `Reconfigure`.
 
-Remember to replace the locations of your keys and the address/host name of your server.
+After a restart of the OpenVPN server, all clients should be able to see all devices within your (at home) local network. This is an example running on a distant server, which is connected through the VPN and can successfully communicate with all internal devices:
 
-### Using the Network Manager
-
-When using the Network Manager, you will have to do some additional setting on the client side of things:
-
-![](http://www.dl6er.de/pi-hole/openVPN/local.png)
-
-#### Alternative 1: Disable Network Manager's internal DNS server
-
-Edit `/etc/NetworkManager/NetworkManager.conf`:
 ```
-# dns=dnsmasq
-```
-and restart the Network Manager:
-```
-sudo restart network-manager
+me@client ~ $ ifconfig
+eth0      Link encap:Ethernet  HWaddr e0:xx:xx:xx:xx:xx  
+          inet addr:134.x.x.x  Bcast:134.x.x.x  Mask:255.x.x.x
+          inet6 addr: X:X:X:X::X/64 Scope:Link
+          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
+          RX packets:3623911 errors:0 dropped:0 overruns:0 frame:0
+          TX packets:2803670 errors:0 dropped:0 overruns:0 carrier:0
+          collisions:0 txqueuelen:1000 
+          RX bytes:1921375471 (1.9 GB)  TX bytes:1227835028 (1.2 GB)
+
+lo        Link encap:Local Loopback  
+          inet addr:127.0.0.1  Mask:255.0.0.0
+          inet6 addr: ::1/128 Scope:Host
+          UP LOOPBACK RUNNING  MTU:65536  Metric:1
+          RX packets:553426 errors:0 dropped:0 overruns:0 frame:0
+          TX packets:553426 errors:0 dropped:0 overruns:0 carrier:0
+          collisions:0 txqueuelen:1 
+          RX bytes:113417383 (113.4 MB)  TX bytes:113417383 (113.4 MB)
+
+tun0      Link encap:UNSPEC  HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00  
+          inet addr:10.8.0.2  P-t-P:10.8.0.2  Mask:255.255.255.0
+          UP POINTOPOINT RUNNING NOARP MULTICAST  MTU:1500  Metric:1
+          RX packets:274676 errors:0 dropped:0 overruns:0 frame:0
+          TX packets:331178 errors:0 dropped:0 overruns:0 carrier:0
+          collisions:0 txqueuelen:100 
+          RX bytes:43745313 (43.7 MB)  TX bytes:43956250 (43.9 MB)
+
+me@client ~ $ ping 192.168.2.123
+PING 192.168.2.123 (192.168.2.123) 56(84) bytes of data.
+64 bytes from 192.168.2.123: icmp_seq=1 ttl=64 time=18.9 ms
+64 bytes from 192.168.2.123: icmp_seq=2 ttl=64 time=18.9 ms
+64 bytes from 192.168.2.123: icmp_seq=3 ttl=64 time=18.9 ms
+64 bytes from 192.168.2.123: icmp_seq=4 ttl=64 time=18.7 ms
+64 bytes from 192.168.2.123: icmp_seq=5 ttl=64 time=18.7 ms
+64 bytes from 192.168.2.123: icmp_seq=6 ttl=64 time=19.0 ms
+^C
+--- 192.168.2.123 ping statistics ---
+6 packets transmitted, 6 received, 0% packet loss, time 5007ms
+rtt min/avg/max/mdev = 18.740/18.894/19.017/0.189 ms
 ```
 
-When connecting your DNS server will now be properly picked up and used by your client.
 
-#### Alternative 2: Set DNS server address of your Pi-hole manually on the main interface
-
-You can also set the address of the DNS server manually (use the device which actually connects to the internet, e.g. `eth0`):
-
-![](http://www.dl6er.de/pi-hole/openVPN/manualDNS.png)
-
-After doing either alternative, you should see:
-```
-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)
-```
-
-The web interface of your Pi-hole will be visible at `http://pi.hole/admin/` (even with the recommended firewall configuration mentioned on another subpage)
-
-![](http://www.dl6er.de/pi-hole/openVPN/VPNdashboard.png)
-
----
-## Troubleshooting
-
-If your new DNS server configuration has not been activated (try restarting the interface / system) you will see
-```
-host pi.hole
-Host pi.hole not found: 3(NXDOMAIN)
-```
-
-If you are not connected to your VPN network you will see
-```
-host pi.hole
-;; connection timed out; no servers could be reached
-```
+### Important last step
+The undocumented `pihole -a -i all` command is simply what runs when you choose _Listen on all interfaces, permit all origins (make sure your Pi-hole is firewalled)_, which if you've read this far in the tutorial, you should understand that we don't want you to knowingly or unknowing set up an open resolver.
+![screenshot](listening-behavior.png)

docs/guides/vpn/dynDNS.md

@@ -0,0 +1,21 @@
+If you operate your Pi-hole + OpenVPN at home, it is very likely that you are sitting behind a NAT / dynamically changing IP address. In this case, you should set up a dynamic DNS record, which allows you to reach your server. You can exchange the address that has been configured during the setup of OpenVPN like this:
+
+```
+vim /etc/openvpn/client-common.txt
+```
+
+Look for the `remote` line and adjust it accordingly (remove IP address, add host name), e.g.
+
+```
+remote home.mydomain.de 1194
+```
+
+This change has to be repeated in each client config file (`*.conf`) that you have been created up till now.
+
+If you have set up a DDNS domain for your IP address, you will likely need to add a host-record to Pi-hole's settings.
+
+```
+pihole -a hostrecord home.mydomain.de 192.168.1.10
+```
+
+If you don't do this, clients (like the Android OpenVPN client) will not able to connect to the VPN server when *inside the internal network* (while it will work from outside).  Afterwards, the client will be able to connect to the VPN server both from inside and outside you local network.

docs/guides/vpn/firewall.md

@@ -7,10 +7,10 @@ sudo iptables -L --line-numbers
 ```
 
 If you get something like
-<pre>
+```
 Chain INPUT (policy ACCEPT)
 num  target     prot opt source               destination
-<b>1    ACCEPT     tcp  --  anywhere             anywhere             tcp dpt:http</b>
+1    ACCEPT     tcp  --  anywhere             anywhere             tcp dpt:http
 2    ACCEPT     tcp  --  anywhere             anywhere             tcp dpt:domain
 3    ACCEPT     udp  --  anywhere             anywhere             udp dpt:domain
 
@@ -19,7 +19,7 @@ num  target     prot opt source               destination
 
 Chain OUTPUT (policy ACCEPT)
 num  target     prot opt source               destination
-</pre>
+```
 you have to first explicitly delete the first INPUT rule using:
 ```
 sudo iptables -D INPUT 1
@@ -66,12 +66,12 @@ sudo iptables -P INPUT DROP
 ```
 
 Optional: If you want to allow access to the Pi-hole from within the VPN *and* from the local network, you will have to explicitly allow your local network as well (assuming the local network is within the address space 192.168.**178**.1 - 192.168.**178**.254):
-<pre>
-sudo iptables -A INPUT -s 192.168.<b>178</b>.0/24 -p tcp --destination-port 53 -j ACCEPT
-sudo iptables -A INPUT -s 192.168.<b>178</b>.0/24 -p udp --destination-port 53 -j ACCEPT
-sudo iptables -A INPUT -s 192.168.<b>178</b>.0/24 -p tcp --destination-port 80 -j ACCEPT
-sudo iptables -A INPUT -s 192.168.<b>178</b>.0/24 -p udp --destination-port 80 -j ACCEPT
-</pre>
+```
+sudo iptables -A INPUT -s 192.168.178.0/24 -p tcp --destination-port 53 -j ACCEPT
+sudo iptables -A INPUT -s 192.168.178.0/24 -p udp --destination-port 53 -j ACCEPT
+sudo iptables -A INPUT -s 192.168.178.0/24 -p tcp --destination-port 80 -j ACCEPT
+sudo iptables -A INPUT -s 192.168.178.0/24 -p udp --destination-port 80 -j ACCEPT
+```
 See also [this](https://discourse.pi-hole.net/t/pihole-vpn-with-iptables/2384) thread on Discourse.
 
 ---

docs/guides/vpn/only-dns-via-vpn.md

@@ -17,7 +17,7 @@ Remember to replace the locations of your keys and the address/host name of your
 
 When using the Network Manager, you will have to do some additional setting on the client side of things:
 
-![](http://www.dl6er.de/pi-hole/openVPN/local.png)
+![](NetworkManager1.png)
 
 #### Alternative 1: Disable Network Manager's internal DNS server
 
@@ -36,7 +36,7 @@ When connecting your DNS server will now be properly picked up and used by your
 
 You can also set the address of the DNS server manually (use the device which actually connects to the internet, e.g. `eth0`):
 
-![](http://www.dl6er.de/pi-hole/openVPN/manualDNS.png)
+![](NetworkManager2.png)
 
 After doing either alternative, you should see:
 ```
@@ -46,7 +46,7 @@ pi.hole has IPv6 address A:B:C:D:E:F (outside address of your VPN server)
 
 The web interface of your Pi-hole will be visible at `http://pi.hole/admin/` (even with the recommended firewall configuration mentioned on another subpage)
 
-![](http://www.dl6er.de/pi-hole/openVPN/VPNdashboard.png)
+![](VPNdashboard.png)
 
 ---
 ## Troubleshooting

docs/guides/vpn/overview.md

@@ -1,29 +1,21 @@
->This tutorial is tailored for setting up OpenVPN on a cloud-hosted virtual server (such as [Digital Ocean](http://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](https://github.com/pi-hole/pi-hole/wiki/OpenVPN-server:-Dual-operation:-LAN-&-VPN-at-the-same-time).
+>This tutorial is tailored for setting up OpenVPN on a cloud-hosted virtual server (such as [Digital Ocean](http://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
+### 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 walkthrough 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](http://www.digitalocean.com/?refcode=344d234950e1).
+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](http://www.digitalocean.com/?refcode=344d234950e1).
 
-**This tutorial walks you through the installation of Pi-hole combined with an VPN server for secure access from remote clients**.  Via this VPN, you can:
+**This tutorial walks you through the installation of Pi-hole combined with an VPN server for secure access from remote clients**.
+
+Via this VPN, you can:
 
 - use the DNS server and full filtering capabilities of your Pi-hole from everywhere around the globe
 - 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](https://github.com/pi-hole/pi-hole/wiki/OpenVPN-server:-Only-route-DNS-via-VPN).  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)](https://github.com/pi-hole/pi-hole/wiki/OpenVPN-server:-Dual-operation:-LAN-&-VPN-at-the-same-time), while preserving full functionality.
+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.
 
-## End Result
-
-You will have access to a VPN that uses Pi-hole for DNS and tunnels some or all of your network traffic
-
-1. [Install OpenVPN + Pi-hole](https://github.com/pi-hole/pi-hole/wiki/OpenVPN-server:-Installation)
-2. [Configure OpenVPN to use Pi-hole for DNS queries](https://github.com/pi-hole/pi-hole/wiki/OpenVPN-server:-Setup-OpenVPN-server)
-3. [Configure your client devices](https://github.com/pi-hole/pi-hole/wiki/OpenVPN-server:-Connect-from-a-client)
-4. [(optional) Secure the server with firewall rules (`iptables`)](https://github.com/pi-hole/pi-hole/wiki/OpenVPN-server:-Firewall-configuration-(using-iptables))
-5. [(optional) Route _only_ DNS via the VPN](https://github.com/pi-hole/pi-hole/wiki/OpenVPN-server:-Only-route-DNS-via-VPN)
-6. [(optional) Dual operation: simultaneous LAN and VPN](https://github.com/pi-hole/pi-hole/wiki/OpenVPN-server:-Dual-operation:-LAN-&-VPN-at-the-same-time)
-7. [(optional) Set up Dynamic DNS host name](https://github.com/pi-hole/pi-hole/wiki/Set-up-a-dynamic-DNS-host-name)
+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
 
 ---
->Note that 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).
+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).

docs/guides/vpn/setup-openvpn-server.md

@@ -2,7 +2,7 @@
 
 First, find the IP of your `tun0` interface:
 
-On jessie
+On Jessie
 ```
 ifconfig tun0 | grep 'inet addr'
 ```
@@ -65,8 +65,3 @@ Client name: iphone7
 ```
 
 This will generate a `.ovpn` file, which needs to be copied to your client machine (often times using the OpenVPN app).  This process also generates a few other files found in `/etc/openvpn/easy-rsa/pki/`, which make public key authentication possible; you only need to worry about the `.ovpn` file, though.
-
-***
-### Next Steps
-
-Next, [configure your client devices](https://github.com/pi-hole/pi-hole/wiki/OpenVPN-server:-Connect-from-a-client) to use the VPN.

mkdocs.yml

@@ -57,9 +57,12 @@ pages:
     - 'Installation': 'guides/vpn/installation.md'
     - 'Setup OpenVPN Server': 'guides/vpn/setup-openvpn-server.md'
     - 'Firewall Configuration': 'guides/vpn/firewall.md'
-    - 'Connecting clients': 'guides/vpn/clients.md'
+    - 'Connecting clients': 
+      - 'General': 'guides/vpn/clients.md'
+      - 'Android': 'guides/vpn/android-client.md'
     - 'Optional: Only route DNS via VPN': 'guides/vpn/only-dns-via-vpn.md'
     - 'Optional: Dual operation: LAN & VPN at the same time': 'guides/vpn/dual-operation.md'
+    - 'Optional: Dynamic DNS': 'guides/vpn/dynDNS.md'
 extra:
   social:
     - type: globe