Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/damianiglesias/pihole-ubuntu-deploy/llms.txt

Use this file to discover all available pages before exploring further.

A DNS server must have a fixed IP address — if the IP changes, every device on the network loses DNS resolution. Pi-hole Ubuntu Deploy configures a static IP using Ubuntu’s Netplan network configuration system, ensuring your Pi-hole remains reachable at the same address even after reboots and router restarts.

​
How deploy.sh Handles It

deploy.sh automates the entire static IP configuration process interactively during installation.
1

List available network interfaces

The script enumerates all non-loopback interfaces so you can identify the correct one:
ip -o link show | awk -F': ' '{print $2}' | grep -v "lo"
2

Prompt for interface selection

You are asked to provide the interface name to configure:
Type interface name (e.g. enp0s8):
3

Detect the current IP address

The script reads the IP currently assigned to the selected interface:
ip -4 addr show $SELECTED_IF 2>/dev/null | grep -oP '(?<=inet\s)\d+(\.\d+){3}' | head -n1
4

Detect the current gateway

The default gateway is read from the kernel routing table:
ip route | grep default | awk '{print $3}' | head -n1
If no gateway is found, 192.168.1.1 is used as a fallback.
5

Confirm static assignment

The detected IP and interface are displayed and you are prompted to confirm:
Set this IP as STATIC? [y/n]:
6

Back up existing Netplan configs

Before writing anything new, all existing YAML files are saved:
mkdir -p /etc/netplan/backup
cp /etc/netplan/*.yaml /etc/netplan/backup/ 2>/dev/null
7

Write the new Netplan configuration

A new file /etc/netplan/99-pihole-static.yaml is created with the detected values and permissions are locked down immediately:
chmod 600 /etc/netplan/99-pihole-static.yaml
8

Apply the configuration

Netplan applies the new static address without a reboot:
netplan apply

​
Generated Netplan Configuration

deploy.sh writes the following YAML template, substituting your detected interface name, IP address, and gateway at runtime: 
network:
  version: 2
  renderer: networkd
  ethernets:
    enp0s8:                           # your interface name
      dhcp4: false
      addresses: [192.168.1.100/24]   # your current IP
      routes: [{to: default, via: 192.168.1.1}]  # your gateway
      nameservers: {addresses: [8.8.8.8, 127.0.0.1]}
The nameservers line includes 127.0.0.1 (Pi-hole) as the secondary DNS server. This ensures the Pi-hole server itself also routes its own DNS queries through Pi-hole, keeping its own traffic ad-filtered and logged.

​
Manual Static IP Setup

If you skipped static IP configuration during the deploy.sh run, you can apply it at any time by following these steps.
1

Find your network interface

ip -o link show | awk -F': ' '{print $2}' | grep -v "lo"
Note the interface name (e.g., enp0s8, eth0, ens18).
2

Find your current IP address

Replace <interface> with your interface name from the previous step:
ip -4 addr show <interface>
Look for the inet line — the address before the / is your IP (e.g., 192.168.1.100).
3

Find your default gateway

ip route | grep default | awk '{print $3}' | head -n1
The address printed is your gateway (e.g., 192.168.1.1).
4

Create the Netplan file

Open a new Netplan configuration file in your editor:
sudo nano /etc/netplan/99-pihole-static.yaml
Paste and adjust the following, replacing the interface name, IP, and gateway with your own values:
network:
  version: 2
  renderer: networkd
  ethernets:
    enp0s8:
      dhcp4: false
      addresses: [192.168.1.100/24]
      routes: [{to: default, via: 192.168.1.1}]
      nameservers: {addresses: [8.8.8.8, 127.0.0.1]}
5

Set correct file permissions

Netplan enforces strict permission requirements on its configuration files:
sudo chmod 600 /etc/netplan/99-pihole-static.yaml
6

Apply the configuration

sudo netplan apply
Permissions on Netplan files must be set to 600 or Netplan will refuse to apply them and log a warning. deploy.sh sets this automatically with chmod 600, but if you create the file manually you must set it yourself.

​
Verification

After applying the static IP — whether via deploy.sh or manually — confirm the address is active and the host has network connectivity: 
ip -4 addr show enp0s8
ping -c 3 8.8.8.8
The ip command should show your chosen static address, and the ping should complete successfully, confirming that routing and DNS are functioning.

Build docs developers (and LLMs) love

Get started for freeTalk to us