Automating Pi-hole Updates with Ansible

Photo by Ant Rozetsky on Unsplash Automating Pi-hole Updates with Ansible Managing multiple Pi-hole instances can become a time-consuming task, especially when it comes to regular updates. In this article, we’ll explore how to use Ansible to automate the process of updating Pi-hole installations across your network. This approach will save you time and ensure consistency across all your Pi-hole servers. What is Pi-hole? Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole. It intercepts DNS requests on your network and blocks requests to known advertising and tracking domains, preventing ads from being downloaded. This not only improves your browsing experience but also: Reduces bandwidth usage Increases browsing speed Enhances privacy by blocking tracking domains Works on all devices on your network without needing to install software on each device Pi-hole is typically installed on a Raspberry Pi (hence the name), but it can run on virtually any Linux distribution with minimal resources. It’s an excellent solution for home networks or small businesses looking to reduce ad traffic. Why Ansible for Pi-hole Management? When you’re managing one Pi-hole, manual updates are straightforward. However, as your infrastructure grows or if you maintain Pi-hole instances across different locations, the manual approach becomes: Time-consuming Error-prone Difficult to track Inconsistent Ansible provides a solution with these benefits: Automation : Execute the same tasks across multiple servers with a single command Idempotency : Run playbooks multiple times without causing issues Consistency : Ensure all systems are updated using the same procedure Documentation : Your playbooks serve as living documentation of your update process Scalability : Easily add new Pi-hole instances to your inventory Setting Up the Environment Let’s break down the process into clear steps: Step 1: Install Ansible First, ensure you have Ansible installed on your control node: # On Debian/Ubuntu sudo apt update sudo apt install ansible # On macOS with Homebrew brew install ansible # Verify installation ansible --version Step 2: Create Your Ansible Structure Create a basic directory structure for your Ansible project: mkdir -p pihole-ansible/inventory mkdir -p pihole-ansible/playbooks cd pihole-ansible Step 3: Configure Your Inventory Create an inventory file that lists your Pi-hole servers: # inventory/hosts [pizeros] pihole1 ansible_host=192.168.1.100 pihole2 ansible_host=192.168.1.101 pihole3 ansible_host=192.168.1.102 [pizeros:vars] ansible_user=pi Step 4: Create the Group Variables Create a group variables file to apply settings to all Pi-hole instances: # inventory/group_vars/pizeros.yml ansible_python_interpreter: /usr/bin/python3 ansible_become: yes ansible_become_method: sudo Step 5: Create the Update Playbook Create a playbook that handles the Pi-hole update process: # playbooks/update_pihole.yml --- - hosts: pizeros become: true become_method: sudo become_user: root tasks: - name: Update package lists apt: update_cache: yes changed_when: false - name: Upgrade all packages apt: upgrade: dist autoremove: yes autoclean: yes - name: Update Pi-hole command: pihole -up register: pihole_update_result changed_when: "'Everything is already up to date' not in pihole_update_result.stdout" - name: Display Pi-hole update results debug: var: pihole_update_result.stdout_lines Step 6: Create a Convenience Script For even easier updates, create a simple shell script: # update.sh #!/bin/bash ansible-playbook -i inventory/hosts playbooks/update_pihole.yml Make it executable: chmod +x update.sh Running the Update Process Now that everything is set up, you can update all your Pi-hole instances with a single command: ./update.sh Or, if you prefer to run the playbook directly: ansible-playbook -i inventory/hosts playbooks/update_pihole.yml Understanding the Playbook in Detail Let’s break down what our update playbook does: 1. Package Updates - name: Update package lists apt: update_cache: yes changed_when: false - name: Upgrade all packages apt: upgrade: dist autoremove: yes autoclean: yes These tasks: Update the APT package cache Perform a full distribution upgrade Remove unnecessary packages Clean the APT cache 2. Pi-hole Specific Update - name: Update Pi-hole command: pihole -up register: pihole_update_result changed_when: "'Everything is already up to date' not in pihole_update_result.stdout" This task: Runs the Pi-hole update command (pihole -up) Captures the output in a variable Only registers as “changed” if an actual update occurred

Mar 17, 2025 - 00:40

Photo by Ant Rozetsky on Unsplash

Automating Pi-hole Updates with Ansible

Managing multiple Pi-hole instances can become a time-consuming task, especially when it comes to regular updates. In this article, we’ll explore how to use Ansible to automate the process of updating Pi-hole installations across your network. This approach will save you time and ensure consistency across all your Pi-hole servers.

What is Pi-hole?

Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole. It intercepts DNS requests on your network and blocks requests to known advertising and tracking domains, preventing ads from being downloaded. This not only improves your browsing experience but also:

Reduces bandwidth usage
Increases browsing speed
Enhances privacy by blocking tracking domains
Works on all devices on your network without needing to install software on each device

Pi-hole is typically installed on a Raspberry Pi (hence the name), but it can run on virtually any Linux distribution with minimal resources. It’s an excellent solution for home networks or small businesses looking to reduce ad traffic.

Why Ansible for Pi-hole Management?

When you’re managing one Pi-hole, manual updates are straightforward. However, as your infrastructure grows or if you maintain Pi-hole instances across different locations, the manual approach becomes:

Time-consuming
Error-prone
Difficult to track
Inconsistent

Ansible provides a solution with these benefits:

Automation : Execute the same tasks across multiple servers with a single command
Idempotency : Run playbooks multiple times without causing issues
Consistency : Ensure all systems are updated using the same procedure
Documentation : Your playbooks serve as living documentation of your update process
Scalability : Easily add new Pi-hole instances to your inventory

Setting Up the Environment

Let’s break down the process into clear steps:

Step 1: Install Ansible

First, ensure you have Ansible installed on your control node:

# On Debian/Ubuntu
sudo apt update
sudo apt install ansible

# On macOS with Homebrew
brew install ansible

# Verify installation
ansible --version

Step 2: Create Your Ansible Structure

Create a basic directory structure for your Ansible project:

mkdir -p pihole-ansible/inventory
mkdir -p pihole-ansible/playbooks
cd pihole-ansible

Step 3: Configure Your Inventory

Create an inventory file that lists your Pi-hole servers:

# inventory/hosts
[pizeros]
pihole1 ansible_host=192.168.1.100
pihole2 ansible_host=192.168.1.101
pihole3 ansible_host=192.168.1.102

[pizeros:vars]
ansible_user=pi

Step 4: Create the Group Variables

Create a group variables file to apply settings to all Pi-hole instances:

# inventory/group_vars/pizeros.yml
ansible_python_interpreter: /usr/bin/python3
ansible_become: yes
ansible_become_method: sudo

Step 5: Create the Update Playbook

Create a playbook that handles the Pi-hole update process:

# playbooks/update_pihole.yml
---
- hosts: pizeros
  become: true
  become_method: sudo
  become_user: root
  tasks:
    - name: Update package lists
      apt:
        update_cache: yes
      changed_when: false
- name: Upgrade all packages
      apt:
        upgrade: dist
        autoremove: yes
        autoclean: yes
    - name: Update Pi-hole
      command: pihole -up
      register: pihole_update_result
      changed_when: "'Everything is already up to date' not in pihole_update_result.stdout"
    - name: Display Pi-hole update results
      debug:
        var: pihole_update_result.stdout_lines

Step 6: Create a Convenience Script

For even easier updates, create a simple shell script:

# update.sh
#!/bin/bash
ansible-playbook -i inventory/hosts playbooks/update_pihole.yml

Make it executable:

chmod +x update.sh

Running the Update Process

Now that everything is set up, you can update all your Pi-hole instances with a single command:

./update.sh

Or, if you prefer to run the playbook directly:

ansible-playbook -i inventory/hosts playbooks/update_pihole.yml

Understanding the Playbook in Detail

Let’s break down what our update playbook does:

1. Package Updates

- name: Update package lists
  apt:
    update_cache: yes
  changed_when: false
- name: Upgrade all packages
  apt:
    upgrade: dist
    autoremove: yes
    autoclean: yes

These tasks:

Update the APT package cache
Perform a full distribution upgrade
Remove unnecessary packages
Clean the APT cache

2. Pi-hole Specific Update

- name: Update Pi-hole
  command: pihole -up
  register: pihole_update_result
  changed_when: "'Everything is already up to date' not in pihole_update_result.stdout"

This task:

Runs the Pi-hole update command (pihole -up)
Captures the output in a variable
Only registers as “changed” if an actual update occurred

3. Result Display

- name: Display Pi-hole update results
  debug:
    var: pihole_update_result.stdout_lines

This task displays the full output of the Pi-hole update process, making it easy to review what happened.

Advanced Customizations

Once you have the basic update process working, you can enhance your Ansible setup with these additional features:

Schedule Regular Updates

Use cron on your control node to schedule regular updates:

# Run updates every Sunday at 3:00 AM
0 3 * * 0 /path/to/pihole-ansible/update.sh > /path/to/logs/pihole-update.log 2>&1

Add Health Checks

Enhance your playbook with health checks after updates:

- name: Check Pi-hole status
  command: pihole status
  register: pihole_status
  changed_when: false
- name: Verify DNS resolution is working
  command: dig @localhost google.com
  register: dns_test
  changed_when: false
  failed_when: "'ANSWER SECTION' not in dns_test.stdout"

Add Notification System

Add tasks to notify you when updates are complete:

- name: Send update completion notification
  mail:
    host: smtp.gmail.com
    port: 587
    username: your_email@gmail.com
    password: "{{ email_password }}"
    to: admin@example.com
    subject: "Pi-hole update completed"
    body: "Updates have been applied to all Pi-hole instances.\n\n{{ pihole_update_result.stdout }}"
  when: pihole_update_result.changed
  no_log: true
  vars:
    ansible_python_interpreter: /usr/bin/python3
  delegate_to: localhost

Note: Store sensitive information like passwords in an encrypted Ansible vault.

Troubleshooting Common Issues

When using this automation, you might encounter some issues:

SSH Connection Problems

If you have SSH connection issues:

Verify your inventory has the correct IP addresses and usernames

Test the connection manually:

ansible pizeros -i inventory/hosts -m ping

Ensure SSH key authentication is set up:

ssh-copy-id pi@your_pihole_ip

Update Failures

If Pi-hole updates fail:

Ensure your Pi-hole instances have internet connectivity

Review Pi-hole logs for specific errors:

- name: Check Pi-hole logs   
  command: cat /var/log/pihole.log   
  register: pihole_logs   
  changed_when: false

Check disk space on your Pi-hole instances:

- name: Check available disk space
  shell: df -h /   
  register: disk_space   
  changed_when: false

Conclusion

Using Ansible to automate Pi-hole updates significantly improves manual processes, especially when managing multiple instances. This approach not only saves time but also ensures consistent updates across your entire network.

The playbooks and configurations in this article provide a solid foundation that you can customize to meet your specific needs. As you become more familiar with Ansible, you can expand your automation to include other aspects of Pi-hole management such as configuration changes, blocklist updates, or even full system backups.

Remember that automation is an investment that pays dividends over time. The initial setup may take some effort, but the long-term benefits of time savings and consistency are well worth it.

Happy automating and see you in the next article!