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/Ubuntusudo apt updatesudo apt install ansible# On macOS with Homebrewbrew install ansible# Verify installationansible --version

Step 2: Create Your Ansible Structure

Create a basic directory structure for your Ansible project:

mkdir -p pihole-ansible/inventorymkdir -p pihole-ansible/playbookscd 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.100pihole2 ansible_host=192.168.1.101pihole3 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.ymlansible_python_interpreter: /usr/bin/python3ansible_become: yesansible_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/bashansible-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 AM0 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:

1. 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:

1. 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! 👻