Network Architecture — Pi-hole Ubuntu Deploy Reference

Pi-hole Ubuntu Deploy has been tested in two VM network configurations. The right choice depends on whether you want Pi-hole to serve your entire LAN or only the host machine.

VPN and NAT configurations are not covered in v1 of the project. The author notes that bridged networking is the simplest approach for full LAN coverage, and more complex topologies will be addressed in a future version.

Bash Script Deployment

When using deploy.sh to install Pi-hole directly on the OS, the VM’s network adapter mode determines which devices can reach the Pi-hole DNS server.

Bridged Adapter
Host-Only Adapter

In Bridged mode, the VM is treated as a first-class device on your physical LAN. It receives its own IP address from your router (or a static IP assigned by deploy.sh), and any device on the network can point its DNS to Pi-hole.How it works:

[Router / DHCP]
      |
──────┬──────────────────────
      │           LAN (192.168.x.x)
  [VM / Pi-hole]   [PC]   [Phone]   [TV]
  192.168.1.50

Advantages:

All LAN devices can use Pi-hole as their DNS server
No port forwarding or VPN required
Static IP assigned directly to the VM interface via Netplan
Recommended for production deployments

Setup:

Set your VM’s network adapter to Bridged in VirtualBox/VMware
Run sudo ./deploy.sh and select Static IP when prompted
Set Pi-hole’s IP (192.168.1.x) as the DNS server in your router’s DHCP settings

After enabling a static IP via deploy.sh, point your router’s primary DNS server to the Pi-hole IP. All DHCP clients will then automatically use Pi-hole for ad blocking.

In Host-Only mode, the VM is isolated to a private network that only the host machine can reach. It cannot access the broader LAN and other devices cannot reach it.How it works:

[Host Machine]
      |
[Host-Only vNIC]  (192.168.56.x — VirtualBox default)
      |
[VM / Pi-hole]
192.168.56.10

Advantages:

Safe for development and testing — no risk of breaking LAN DNS
Easy SSH access from the host for script development
Pi-hole web admin accessible from the host at http://192.168.56.10/admin

Limitations:

Only the host machine uses Pi-hole; other LAN devices are unaffected
Pi-hole cannot reach the internet directly (use a second NAT adapter for internet access during install)

This is the configuration the author used to develop and test the script. If you’re testing deploy.sh over SSH, Host-Only with a second NAT adapter for internet is the recommended setup.

Ansible / Docker Deployment

When using the Ansible playbook, Pi-hole and Unbound run as Docker containers inside a custom bridge network. The host OS acts as the gateway, publishing container ports to the physical network interface.

Docker Network: `pihole_net`

The playbook creates a dedicated Docker bridge network named pihole_net with a /16 subnet:

Docker Bridge: pihole_net (172.20.0.0/16)
┌─────────────────────────────────────────┐
│                                         │
│   [pihole container]  172.20.0.2        │
│   [unbound container] 172.20.0.5        │
│                                         │
└──────────────┬──────────────────────────┘
               │ Published ports
         [Host OS / VM]
         Port 53  → pihole:53
         Port 80  → pihole:80
         Port 5335 → unbound:5335

Container	Image	Fixed IP	Role
`pihole`	`pihole/pihole:latest`	`172.20.0.2`	DNS sinkhole + web admin
`unbound`	`mvance/unbound:latest`	`172.20.0.5`	Recursive DNS resolver

DNS Forwarding Between Containers

Pi-hole is configured with PIHOLE_DNS_1: '172.20.0.5#5335' — it forwards all upstream queries to the Unbound container on port 5335, keeping both containers within the private pihole_net network and avoiding any external dependency for recursion.

Port Reference

All ports used by Pi-hole Ubuntu Deploy — both for the direct OS install and the Docker method.

Port	Protocol	Service	Direction
22	TCP	SSH access	Inbound
53	TCP + UDP	DNS queries	Inbound
80	TCP	Pi-hole web admin	Inbound
5335	UDP	Unbound recursive resolver (if enabled)	Internal

In the Ansible playbook, UFW only opens port 53 over TCP (task 9 loops over TCP only). UDP port 53 is handled by Docker’s port publishing, which bypasses UFW by default on Linux. For deploy.sh, ufw allow 53 opens both TCP and UDP.

DNS Query Flow

The resolution chain differs depending on whether Unbound is enabled.

Without Unbound
With Unbound

DNS queries are resolved by an external upstream (Google or Cloudflare). Blocked domains return 0.0.0.0.

Client
  │
  ▼  port 53
Pi-hole
  │
  ├──► BLOCKED → returns 0.0.0.0 (ad/tracker domain)
  │
  └──► Upstream DNS (8.8.8.8 or 1.1.1.1)
           │
           └──► Returns IP to Pi-hole → Client

This is the default configuration after running deploy.sh without enabling Unbound.

When Unbound is enabled (either via deploy.sh step 4.5 or automatically in the Ansible playbook), Pi-hole forwards non-blocked queries to Unbound, which performs iterative resolution directly from root nameservers — no third-party upstream involved.

Client
  │
  ▼  port 53
Pi-hole (127.0.0.1 or 172.20.0.2)
  │
  ├──► BLOCKED → returns 0.0.0.0
  │
  └──► Unbound (127.0.0.1:5335 or 172.20.0.5:5335)
           │
           └──► Root nameservers (iterative resolution)
                    │
                    └──► Returns IP → Pi-hole → Client

Unbound is not fully working in the bash script (deploy.sh) v4.1. This is a known issue. The Ansible/Docker method works correctly because Unbound runs in its own container with a pre-configured image. See Troubleshooting for workarounds.

Static IP and Netplan

A static IP is critical for a DNS server. If the Pi-hole machine’s IP changes (e.g., due to DHCP lease renewal), all devices on the network that point to Pi-hole as their DNS server will lose connectivity until the address is updated. deploy.sh handles this at Step 6 by writing a Netplan configuration that:

Detects the current interface IP and default gateway automatically
Locks that IP as static by disabling DHCP (dhcp4: false)
Sets nameservers to 8.8.8.8 (external fallback) and 127.0.0.1 (Pi-hole itself)
Backs up all existing Netplan YAML files to /etc/netplan/backup/ before writing

network:
  version: 2
  renderer: networkd
  ethernets:
    enp0s8:
      dhcp4: false
      addresses: [192.168.1.50/24]
      routes: [{to: default, via: 192.168.1.1}]
      nameservers: {addresses: [8.8.8.8, 127.0.0.1]}

The file is written with chmod 600 permissions as required by netplan apply.

After applying the static IP, update your router’s DNS server setting to point to the Pi-hole IP. This ensures all DHCP clients on the network automatically use Pi-hole for DNS without any per-device configuration.

Get Started

Deployment Methods

Optional Components

Operations

Reference

Network Architecture — Pi-hole Ubuntu Deploy Reference

Bash Script Deployment

Ansible / Docker Deployment

Docker Network: `pihole_net`

DNS Forwarding Between Containers

Port Reference

DNS Query Flow

Static IP and Netplan

Build docs developers (and LLMs) love

Get Started

Deployment Methods

Optional Components

Operations

Reference

Documentation Index

​Bash Script Deployment

​Ansible / Docker Deployment

​Docker Network: pihole_net

​DNS Forwarding Between Containers

​Port Reference

​DNS Query Flow

​Static IP and Netplan

Build docs developers (and LLMs) love

Bash Script Deployment

Ansible / Docker Deployment

Docker Network: `pihole_net`

DNS Forwarding Between Containers

Port Reference

DNS Query Flow

Static IP and Netplan