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.

This page covers the most common issues encountered when deploying Pi-hole on Ubuntu with this toolset, along with diagnostic commands and fixes drawn from the known behavior of deploy.sh.

​
Common Issues

Cause: The VM’s network adapter is not configured for external network access. deploy.sh pings 8.8.8.8 during Step 1 (Network Prep) and exits with a fatal error if there is no response.The exact check in the script:
if ! ping -c 1 8.8.8.8 > /dev/null 2>&1; then
    echo "FATAL ERROR: No Internet connection detected."
    exit 1
fi
Fix:
  1. In VirtualBox or VMware, open the VM’s network settings and switch the adapter to Bridged or NAT
  2. Start the VM and verify internet access before running the script: 
    ping -c 1 8.8.8.8
  3. If the ping succeeds, re-run the script: sudo ./deploy.sh
A Host-Only adapter alone has no route to the internet. You must add a second NAT adapter if you want to install via Host-Only networking.
Cause: Either apt-get update failed in Step 2, or DNS was not resolving install.pi-hole.net when the curl command ran in Step 3. The script exits with an error if command -v pihole returns nothing after the install:
if ! command -v pihole &> /dev/null; then
    echo "Pi-hole installation FAILED."
    exit 1
fi
Fix:
  1. Check that /etc/resolv.conf contains Google’s nameserver: 
    cat /etc/resolv.conf
    Expected output: nameserver 8.8.8.8
  2. If the file is missing or wrong, manually set it: 
    echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
  3. Verify DNS resolution: 
    nslookup install.pi-hole.net 8.8.8.8
  4. Re-run the installer: 
    sudo ./deploy.sh
Cause: systemd-resolved is still running and holding port 53. deploy.sh stops and disables it during Step 1, but if the script failed before completing that step, or if systemd-resolved was restarted manually, the port will remain occupied.Diagnose:
sudo ss -tulnp | grep :53
If systemd-resolved appears in the output, it is still using port 53.Fix:
sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved
Then verify the port is free:
sudo ss -tulnp | grep :53
Restart Pi-hole’s DNS service:
sudo systemctl restart pihole-FTL
Cause: Unbound is an experimental feature in deploy.sh v4.1 and is known to not work correctly in the bash script deployment. This is a documented issue — the author is working on a fix for a future version.Symptoms: DNS queries time out or fail; websites do not load after enabling Unbound in Step 4.5.Fix (disable Unbound as upstream in Pi-hole):
  1. Open the Pi-hole web admin: http://<pi-hole-ip>/admin
  2. Go to Settings → DNS
  3. Uncheck Custom 1 (127.0.0.1#5335)
  4. Check a standard upstream provider (e.g., Google — 8.8.8.8)
  5. Save settings
Check Unbound service status:
sudo systemctl status unbound
Check Unbound logs for errors:
sudo journalctl -u unbound -n 50
The Ansible/Docker deployment method does not have this issue — Unbound runs correctly as a container using the mvance/unbound image, which is pre-configured and isolated from the host OS.
Cause: UFW is blocking port 80, or you are using the wrong IP address to access the admin panel.Fix:
  1. Ensure UFW allows port 80: 
    sudo ufw allow 80/tcp
sudo ufw reload
  2. Find the correct Pi-hole IP address: 
    hostname -I
  3. Access the admin panel at: 
    http://<pi-hole-ip>/admin
  4. Check UFW rules to confirm port 80 is open: 
    sudo ufw status verbose
Cause: The password set during Step 4 of deploy.sh was forgotten or not recorded.Fix — interactive prompt:
pihole setpassword
You will be prompted to type and confirm the new password.Fix — set password directly:
pihole setpassword "newpassword"
Replace newpassword with your desired password. The change takes effect immediately — no restart required.
Cause: The Netplan file at /etc/netplan/99-pihole-static.yaml has incorrect permissions (must be 0600), or the wrong interface name was entered during Step 6 of deploy.sh.Fix — correct file permissions:
sudo chmod 600 /etc/netplan/99-pihole-static.yaml
sudo netplan apply
Check available network interfaces:
ip -o link show
Test Netplan configuration before applying:
sudo netplan try
This applies the config temporarily and reverts automatically after 120 seconds if you do not confirm — useful for avoiding a locked-out situation.Check the generated Netplan file:
cat /etc/netplan/99-pihole-static.yaml
Verify the interface name, IP address, and gateway are all correct.
Original Netplan configs are backed up to /etc/netplan/backup/ by deploy.sh. You can restore them with:
sudo cp /etc/netplan/backup/*.yaml /etc/netplan/
sudo netplan apply
Cause: UFW was enabled without port 22 being allowed first. This should not happen with deploy.sh (which allows port 22 before enabling UFW), but it can occur if UFW is manually reset or re-enabled.Fix (requires console or VNC access to the VM):Connect to the machine via VirtualBox/VMware console (not SSH), then:
sudo ufw allow 22/tcp
sudo ufw reload
Verify SSH is now accessible:
sudo ufw status verbose
Always ensure ufw allow 22/tcp is run before ufw enable when configuring firewalls on remote or VM systems. deploy.sh does this correctly in Step 5, but manual changes can break this order.
Cause: Log2Ram does not start immediately after installation — it activates on the next system reboot. This is by design: Log2Ram mounts /var/log to a RAM tmpfs on boot.Fix:
sudo reboot
After reboot, verify Log2Ram is active:
systemctl status log2ram
You should see active (running) and a log entry confirming it has mounted the log directory to RAM.
Cause: The run_dns_sync.sh launcher script contains incorrect credentials or URL. deploy.sh pre-populates PIHOLE_PASSWORD from the password entered during Step 4, but if the password was changed after installation, or if the URL is wrong, the sync will fail.Fix:
  1. Open the launcher script: 
    nano /opt/pihole-dns-manager/run_dns_sync.sh
  2. Verify and update these two lines: 
    export PIHOLE_URL="http://127.0.0.1"
export PIHOLE_PASSWORD="your-current-password"
  3. Save and run the sync: 
    cd /opt/pihole-dns-manager
./run_dns_sync.sh
  4. DNS entries are defined in: 
    nano /opt/pihole-dns-manager/entries.txt
    Format: IP Domain (one entry per line, lines starting with # are comments)

​
Diagnostic Commands

Use these commands to gather information about the state of your Pi-hole deployment. 
# Check Pi-hole status
pihole status

# Check pihole-FTL service
systemctl status pihole-FTL

# Check Unbound
systemctl status unbound

# Check port usage (DNS, web admin, Unbound)
sudo ss -tulnp | grep -E ':53|:80|:5335'

# Check UFW rules
sudo ufw status verbose

# Check resolv.conf
cat /etc/resolv.conf

# Follow Pi-hole query log in real time
pihole tail

# Test DNS resolution through Pi-hole
nslookup google.com 127.0.0.1

# Test a domain that should be blocked (if blocklists are active)
nslookup doubleclick.net 127.0.0.1

# Check Log2Ram status
systemctl status log2ram

# View recent Unbound log entries
sudo journalctl -u unbound -n 50

# List all Netplan configs
ls -la /etc/netplan/

# Check current IP and interface
ip -4 addr show

# Check default route / gateway
ip route | grep default

Build docs developers (and LLMs) love

Get started for freeTalk to us