🍓 pihole-ansible

This collection provides Ansible modules and roles for managing PiHole v6 via a custom API client. This collection is built on top of the pihole6api Python library, which handles authentication and requests.

Overview

This collection includes:

• Modules:

  • local_a_record: Manage local A records.
  • local_cname: Manage local CNAME records.
  • dhcp_config: Enable, disable and configure the DHCP client.
  • dhcp_remove_lease: Delete existing leases.
  • listening_mode: Toggle the PiHole's listening mode.

• Roles:

  • manage_local_records: A role that iterates over one or more PiHole hosts and manages a batch of local DNS records (both A and CNAME) as defined by the user. For more details, please see the role's README.

In future releases, additional roles and modules will be added to further extend the capabilities of this collection.

Getting Started

Prerequisites

• Ansible: Version 2.9 or later.
• Python: The control node requires Python 3.x.
• pihole6api Library

Installation

Install the collection via Ansible Galaxy:

ansible-galaxy collection install sbarbett.pihole

You can also build it locally:

git clone https://github.com/sbarbett/pihole-ansible
ansible-galaxy collection build
ansible-galaxy collection install sbarbett-pihole-x.x.x.tar.gz

pihole6api Dependency

The pihole6api library is required for this Ansible collection to function. The installation method depends on how you installed Ansible.

pip install pihole6api

However, some Linux distributions (Debian, macOS, Fedora, etc.) restrict system-wide pip installs due to PEP 668. In that case, use one of the methods below.

Installing in a Virtual Environment (Recommended):

If you want an isolated environment that won’t interfere with system-wide packages, install both pihole6api and Ansible in a virtual environment:

python -m venv venv
source venv/bin/activate
pip install pihole6api ansible

To confirm that ansible and pihole6api are installed correctly within the environment, run:

which python && which ansible
python -c "import pihole6api; print(pihole6api.__file__)"

To exit the virtual environment:

deactivate

Using pipx:

If Ansible is installed via pipx, inject pihole6api into Ansible’s environment:

pipx inject ansible pihole6api --include-deps

Verify installation:

pipx runpip ansible show pihole6api

Since Ansible does not automatically detect pipx environments, you must explicitly set the Python interpreter in your Ansible configuration:

Edit ansible.cfg:

[defaults]
interpreter_python = ~/.local/pipx/venvs/ansible/bin/python

For more information on pipx see the official documentation and the Ansible install guide.

Installing for System-Wide Ansible (Generally Not Recommended):

If Ansible was installed via a package manager (apt, dnf, brew) and a virtual environment or pipx is not a feasible or desired solution, run pip with --break-system-packages to bypass PEP 668 restrictions:

sudo pip install --break-system-packages pihole6api

Verify installation:

python3 -c "import pihole6api; print(pihole6api.__file__)"

Usage Examples

• Enable and Configure the PiHole DHCP Client
• Disable the PiHole DHCP Client
• Remove a DHCP Lease
• Create a Local A Record
• Remove a Local A Record
• Create a Local CNAME
• Remove a Local CNAME
• Manage Local Records Across Multiple PiHoles

Documentation

• Each module includes embedded documentation. You can review the options by using ansible-doc sbarbett.module_name.
• Detailed information for the manage_local_records role is provided in its own README file within the role directory.

License

MIT