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.

The DNS Manager tool (tools/piholedns) installs a Python-based utility that syncs local DNS records to Pi-hole from a plain-text entries.txt file. It is useful for assigning friendly hostnames to devices on your network — for example, resolving nas.home or myserver.local to their static IP addresses — without manually editing Pi-hole’s web interface each time.

​
Installation

There are two ways to install the DNS Manager: Option 1 — Via deploy.sh (recommended) During the interactive setup you will be prompted at Step 4.9: 
Step 4.9: Python DNS Manager
   Install DNS Manager tool? [y/n]:
Type y and press Enter. The tool is installed as part of the main deployment. Option 2 — Standalone If you have already run deploy.sh and skipped this step, install the tool separately: 
cd pihole-ubuntu-deploy/tools
sudo ./piholedns

​
What Gets Installed

The installer performs the following steps:
  1. Updates apt and installs python3, python3-venv, python3-pip, and git.
  2. Clones the pihole_dns repository from Codeberg into /opt/pihole-dns-manager/: 
    git clone https://codeberg.org/ben/pihole_dns.git /opt/pihole-dns-manager
    If the directory already exists, it runs git pull instead.
  3. Creates an isolated Python virtual environment inside the directory.
  4. Installs the requests library via pip.
  5. Generates a run_dns_sync.sh launcher script with your Pi-hole URL and password pre-configured.
  6. Creates a default entries.txt file if one does not already exist.

​
Directory Structure After Install

/opt/pihole-dns-manager/
  venv/            # Python virtual environment
  pihole_dns.py    # main DNS sync script
  entries.txt      # your DNS records
  run_dns_sync.sh  # launcher with PIHOLE_URL and PIHOLE_PASSWORD set

​
entries.txt Format

Each line defines one DNS record in the format IP Domain. Lines beginning with # are treated as comments and ignored. 
# Format: IP Domain
127.0.0.1  pihole.local
192.168.1.100  myserver.local
192.168.1.101  nas.home

​
Usage

1

Edit your DNS records

Open entries.txt in your preferred editor:
nano /opt/pihole-dns-manager/entries.txt
Add, modify, or remove records using the IP Domain format shown above. Save and close the file.
2

Sync records to Pi-hole

Run the launcher script to apply your changes:
cd /opt/pihole-dns-manager && ./run_dns_sync.sh
The script activates the virtual environment, connects to Pi-hole’s API, and synchronises all records from entries.txt.

​
run_dns_sync.sh

The installer generates the following launcher script at /opt/pihole-dns-manager/run_dns_sync.sh. The Pi-hole admin password captured during deploy.sh is embedded automatically: 
#!/bin/bash
export PIHOLE_URL="http://127.0.0.1"
export PIHOLE_PASSWORD="<your_password>"
echo "Syncing DNS records..."
cd /opt/pihole-dns-manager
source venv/bin/activate
python3 pihole_dns.py "$@"
The run_dns_sync.sh script contains your Pi-hole admin password in plain text. Restrict its permissions to the owning user to prevent other users from reading it:
chmod 700 /opt/pihole-dns-manager/run_dns_sync.sh

​
Post-Deployment Installation

If you installed the DNS Manager using the standalone tools/piholedns script rather than via deploy.sh, the PIHOLE_PASSWORD field in the launcher will be empty. Update it manually before running a sync: 
nano /opt/pihole-dns-manager/run_dns_sync.sh
Replace the empty PIHOLE_PASSWORD value with your Pi-hole admin password, save the file, then restrict its permissions with chmod 700.

Build docs developers (and LLMs) love

Get started for freeTalk to us