README

Upgrading from an older WireHole? The 2026 rewrite changed the
 layout. Do not just pull and restart. Read UPGRADING.md -
 one script keeps your devices working.

 What is this?

WireHole is a docker-compose project that combines WireGuard, Pi-hole, and
Unbound to create a full or split tunnel VPN that is easy to deploy and
manage. This setup gives you a VPN with advertisement blocking through
Pi-hole, and better DNS privacy and caching through Unbound.

The stack gives you these functions:

- A VPN server. Your devices connect to your own server. Your traffic
  does not go through a public VPN provider.
- Advertisement blocking. Pi-hole blocks the advertisement domains and
  the tracker domains for every connected device.
- Private DNS. Unbound asks the authoritative name servers directly.
  Your DNS queries do not go to Google or to Cloudflare.
- DNSSEC validation. Unbound proves that an answer is authentic.

 Where to find things

New here? Read the first four sections in order. That is all you need to get
running. Everything after them is reference material for later.

Set it up

1. What you need first
2. Quick start
3. Open the web interfaces
4. Open the port on your router
5. Add a VPN client, then
   check that it works

Change how it behaves

- Full tunnel and split tunnel
- The two VPN back ends
- Configuration, for every setting
- Keep working when your IP address changes

Live with it

- Operation: logs, updates, backups
- Test that everything works
- Solve a problem
- Questions people ask
- Security

 How the stack works


   Your device                Your server
  +-----------+     +------------------------------------------+
  |           |     |                                          |
  | WireGuard |=====| VPN server - Pi-hole - Unbound --- Internet
  |  client   | VPN |             (filter)   (resolver)   (root servers)
  |           |     |                                          |
  +-----------+     +------------------------------------------+


1. Your device sends all DNS queries to Pi-hole.
2. Pi-hole blocks the queries for the advertisement domains.
3. Pi-hole sends the other queries to Unbound.
4. Unbound asks the authoritative name servers and validates the answer.

 What you need first

You do not need to be an expert, but you do need four things. Get all four
ready before you start. The setup takes about 20 minutes.

1. A computer that stays on, running Linux. This computer is your server.
It can be a Raspberry Pi (model 3 or later), an old desktop computer, a home
server, or a rented server from a hosting company. It must run Linux.

A VPN needs parts of the Linux kernel that Docker Desktop does not give you,
so a Mac or a Windows PC cannot host this stack, even with Docker installed.
Those machines make fine clients. They just cannot be the server.

WSL2 on Windows is also not a good host. WSL2 puts Linux behind a private
network, so your other devices cannot reach the VPN port. Windows can forward
TCP ports into

Top issues