wirehole

<h1 align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/wirehole-logo-dark.png">
    <source media="(prefers-color-scheme: light)" srcset="assets/wirehole-logo-light.png">
    <img alt="WireHole — private VPN, filtered DNS, one clean tunnel" src="assets/wirehole-logo-light.png" width="760">
  </picture>
</h1>

> **Upgrading from an older WireHole?** The 2026 rewrite changed the
> layout. Do not just pull and restart. Read [UPGRADING.md](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](#what-you-need-first)
2. [Quick start](#quick-start)
3. [Open the web interfaces](#open-the-web-interfaces)
4. [Open the port on your router](#open-the-port-on-your-router)
5. [Add a VPN client](#add-a-vpn-client), then
   [check that it works](#check-that-it-works)

**Change how it behaves**

- [Full tunnel and split tunnel](#full-tunnel-and-split-tunnel)
- [The two VPN back ends](#the-two-vpn-back-ends)
- [Configuration](#configuration), for every setting
- [Keep working when your IP address changes](#keep-working-when-your-ip-address-changes)

**Live with it**

- [Operation](#operation): logs, updates, backups
- [Test that everything works](#test-that-everything-works)
- [Solve a problem](#solve-a-problem)
- [Questions people ask](#questions-people-ask)
- [Security](#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 a