Bring documentation into compilable state by adding missing files

Signed-off-by: DL6ER <dl6er@dl6er.de>

docs/guides/vpn/installation.md

@@ -0,0 +1,70 @@
+## Install an operating system
+
+Once you have your preferred OS up and running.  You may already have a server set up on your network, or you may prefer to make a [Digital Ocean](http://www.digitalocean.com/?refcode=344d234950e1) droplet.  In either case, you'll use the quick OpenVPN "road warrior" installer.  The cloud-hosted server option is convenient if you don't want to host the hardware at home, but you'll need to take additional steps to secure the server as it's available on the public Internet.  Failure to do so is [not only irresponsible, but you also put yourself and others at risk](https://www.us-cert.gov/ncas/alerts/TA13-088A).
+
+## Install OpenVPN + Pi-hole
+
+### A note about security
+
+For security purposes, it is recommended that the CA machine should be separate from the machine running OpenVPN. If you lose control of your CA private key, you can no longer trust any certificates from this CA. Anyone with access to this CA private key can sign new certificates without your knowledge, which then can connect to your OpenVPN server without needing to modify anything on the VPN server. Place your CA files on a storage which can be offline as much as possible, only to be activated when you need to get a new certificate for a client or server.
+
+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:
+```
+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:
+```
+Welcome to this quick OpenVPN "road warrior" installer
+
+I need to ask you a few questions before starting the setup
+You can leave the default options and just press enter if you are ok with them
+
+First I need to know the IPv4 address of the network interface you want OpenVPN
+listening to.
+IP address: 10.8.0.1
+
+Which protocol do you want for OpenVPN connections?
+   1) UDP (recommended)
+   2) TCP
+Protocol [1-2]: 1
+
+What port do you want OpenVPN listening to?
+Port: 1194
+
+Which DNS do you want to use with the VPN?
+   1) Current system resolvers
+   2) Google
+   3) OpenDNS
+   4) NTT
+   5) Hurricane Electric
+   6) Verisign
+DNS [1-6]: 1
+
+Finally, tell me your name for the client certificate
+Please, use one word only, no special characters
+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...
+```
+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.  You can accept all 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.
+
+```
+curl -sSL https://install.pi-hole.net | bash
+```

docs/guides/vpn/overview.md

@@ -0,0 +1,29 @@
+>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).
+
+# 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).
+
+**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.
+
+## 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)
+
+---
+>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).

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

@@ -0,0 +1,72 @@
+### Change OpenVPN's resolvers
+
+First, find the IP of your `tun0` interface:
+
+On jessie
+```
+ifconfig tun0 | grep 'inet addr'
+```
+On Stretch
+```
+ip a
+```
+
+Edit the OpenVPN config file:
+
+```
+vim /etc/openvpn/server.conf
+```
+
+Set this line to use your Pi-hole's IP address, which you determined from the `ifconfig` command and comment out or remove the other line (if it exists):
+
+```
+push "dhcp-option DNS 10.8.0.1"
+#push "dhcp-option DNS 8.8.8.8"
+```
+
+This `push` directive is setting a [DHCP option](https://www.incognito.com/tips-and-tutorials/dhcp-options-in-plain-english/), which tells client's connecting to the VPN that they should use Pi-hole as their primary DNS server.
+
+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.
+
+### Restart OpenVPN to apply the changes
+
+Depending on your operating system, one of these commands should work to restart the service.
+```
+systemctl restart openvpn
+service openvpn restart
+```
+
+## Create a client config file (`.ovpn`)
+
+Now that the server is configured, you'll want to connect some clients so you can make use of your Pi-hole wherever you are.  Doing so requires the use of a certificate.  You generate these and the resulting `.ovpn` file by running the installer and choosing `1) Add a new user` for each client that will connect to the VPN.
+
+You can repeat this process for as many clients as you need.  In this example, we'll "Add a new user" by naming the `.ovpn` file the same as the client's hostname but you may want to adopt your own naming strategy.
+
+Run the OpenVPN installer again
+
+```
+./openvpn-install.sh
+```
+
+Choose `1) Add a new user` and enter a client name
+```
+Looks like OpenVPN is already installed
+
+What do you want to do?
+   1) Add a new user
+   2) Revoke an existing user
+   3) Remove OpenVPN
+   4) Exit
+Select an option [1-4]: 1
+
+Tell me a name for the client certificate
+Please, use one word only, no special characters
+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.