OpenVPN and PiHole wrapped up in a docker-compose setup

Overview

Run OpenVPN and Pi-hole together with Docker Compose. This repository gives you a small, ready-to-use setup where:

• OpenVPN listens on 1194/udp
• Pi-hole is used as the DNS server for VPN clients
• the Pi-hole dashboard is only reachable from inside the VPN at http://pi.hole
• you can generate, revoke and manage certificates with a simple script

The main configuration for this is inspired by mr-bolle/docker-openvpn-pihole, pknw1/openvpn-pihole-docker and kylemanna/docker-openvpn.

---

• Quick start
  • Clone this repository
  • Start the services
• Managing certificates
  • Generating .ovpn files
  • Revoking .ovpn files
  • Renewing certificates
• Configuration
  • OpenVPN
  • PiHole
• FAQ & Recipes
  • Launching multiple OpenVPN instances
• Troubleshooting
  • Port 53 is already in use
• Contributing

Quick start

Clone this repository:

git clone https://github.com/simonwep/openvpn-pihole.git
cd openvpn-pihole

Caution

If you share your VPN with others, it's highly recommended changing the admin password for the PiHole dashboard in the compose.yml file now. Otherwise you can keep it at password as the PiHole is only reachable from inside the VPN.

Start the services

Warning

If you're using a VPS make sure to open 1194/udp.

After you've installed all the pre-requisites, you can run (make sure you're using the latest docker version):

sudo docker compose up -d

After this is done you'll find two new folders inside of this repository - the /openvpn folder will contain all of your certificates as well as an easy-rsa configuration file. /pihole will contain the content of /etc/pihole and /etc/dnsmasq.d.

If you want to migrate settings or your query-database, you can now copy it into the corresponding folder in /pihole :) You'll also be able to import your config as usual in the docker dashboard.

Note

The PiHole admin dashboard can only be reached through the vpn under http://pi.hole.

Managing certificates

Generating .ovpn files

Note

Before you generate any client certificate, you must update the host in client configuration to the IP address to your public IP or domain name. This file will be used as base-configuration for each .ovpn file.

./clients.sh add <password> <names...>

Revoking .ovpn files

./clients.sh remove <name>

Warning

Revoked certificates won't kill active connections, you'll have to restart the service if you want the user to immediately disconnect:

sudo docker compose restart openvpn

Renewing certificates

Depending on the configuration of easy-rsa the certificates will expire at some point. By default, that is after two years, to renew it, you can simply remove the pki folder that contains the certificate authority. After restarting the service, a new CA will be generated.

sudo docker compose down
sudo rm -rf ./openvpn/pki
sudo docker compose up -d

Keep in mind that after that you have to re-generate all .ovpn-files.

Configuration

OpenVPN

Configuration files (such as server.conf and client.conf) are stored in openvpn/config. They are mounted into the container, so they can be changed without rebuilding the image.

PiHole

The PiHole version is pinned to avoid unexpected breaking changes, but you can change the version in compose.yml if you want to update it.

FAQ & Recipes

Launching multiple OpenVPN instances

First copy the openvpn directory including openvpn/config (copy just the config folder!), then add another service to compose.yml.

Example assuming we want to name our second OpenVPN instance openvpn-tcp-443:

mkdir openvpn-tcp-443
cp -r openvpn/config openvpn-tcp-443

You can now make changes to our new config files in openvpn-tcp-443/config. Change proto to tcp and port to 443, you'll also need to comment out explicit-exit-notify 1 as this is only compatible with proto udp (update both server.conf and client.conf!).

Now add our new service:

# ... other services
    openvpn-tcp-443:
        container_name: openvpn-tcp-443
        build: ./openvpn-docker
        ports:
            - 443:443/tcp
        volumes:
            - ./openvpn/pki:/etc/openvpn/pki # Keep the PKI
            - ./openvpn-tcp-443/clients:/etc/openvpn/clients
            - ./openvpn-tcp-443/config:/etc/openvpn/config # !! We're using our second configuration
        cap_add:
            - NET_ADMIN
        restart: unless-stopped
# ... other services

Keep in mind that if you want to generate a client-config for that service we've just made you'll have to use the openvpn-tcp-443 container e.g. sudo docker exec openvpn-tcp-443 bash /opt/app/bin/genclient.sh <name>.

Troubleshooting

Port 53 is already in use

ERROR: for pihole Cannot start service pihole: driver failed programming external connectivity on endpoint pihole (...): Error starting userland proxy: listen tcp 0.0.0.0:53: bind: address already in use

You'll need to disable the local dns-server, see this and this ask ubuntu thread. You can stop, disable and mask the systemd-resolved service using the following commands:

sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved
sudo systemctl mask systemd-resolved

Contributing

Check out the contribution guidelines :)