{"id":25650638,"url":"https://github.com/sbarbett/pihole-ansible","last_synced_at":"2026-03-02T08:30:51.899Z","repository":{"id":278997465,"uuid":"937434606","full_name":"sbarbett/pihole-ansible","owner":"sbarbett","description":"Collection of modules and roles for the PiHole v6 API","archived":false,"fork":false,"pushed_at":"2025-07-01T01:13:50.000Z","size":91,"stargazers_count":22,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-01T11:08:22.132Z","etag":null,"topics":["ad-blocking","ansible","dns","infrastructure-as-code","pihole"],"latest_commit_sha":null,"homepage":"https://shane.barbetta.me","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sbarbett.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-23T03:22:58.000Z","updated_at":"2025-07-01T01:12:30.000Z","dependencies_parsed_at":"2025-02-23T04:21:33.313Z","dependency_job_id":"89d43274-1425-4921-8065-75a06c4824c0","html_url":"https://github.com/sbarbett/pihole-ansible","commit_stats":null,"previous_names":["sbarbett/pihole-ansible"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/sbarbett/pihole-ansible","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbarbett%2Fpihole-ansible","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbarbett%2Fpihole-ansible/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbarbett%2Fpihole-ansible/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbarbett%2Fpihole-ansible/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sbarbett","download_url":"https://codeload.github.com/sbarbett/pihole-ansible/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbarbett%2Fpihole-ansible/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29995912,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ad-blocking","ansible","dns","infrastructure-as-code","pihole"],"created_at":"2025-02-23T15:17:12.390Z","updated_at":"2026-03-02T08:30:51.883Z","avatar_url":"https://github.com/sbarbett.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🍓 pihole-ansible\n\nThis collection provides Ansible modules and roles for managing PiHole v6 via a custom API client. This collection is built on top of the [pihole6api](https://github.com/sbarbett/pihole6api) Python library, which handles authentication and requests.\n\n## Overview\n\nThis collection includes:\n\n- **Modules:**\n  - `local_a_record`: Manage local A records.\n  - `local_aaaa_record`: Manage local AAAAA records. (see `local_a_record` configuration and examples )\n  - `local_cname`: Manage local CNAME records.\n  - `dhcp_config`: Enable, disable and configure the DHCP client.\n  - `dhcp_remove_lease`: Delete existing leases.\n  - `listening_mode`: Toggle the PiHole's listening mode.\n  - `block_list`: Manage block lists.\n  - `allow_list`: Manage allow lists.\n  - `groups`: Manage groups.\n  - `clients`: Manage clients.\n\n- **Roles:**\n  - `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. ([README](https://github.com/sbarbett/pihole-ansible/blob/main/roles/manage_local_records/README.md))\n  - `manage_lists`: A role that iterates over one or more PiHole hosts and manages a batch of allow and block lists as defined by the user. ([README](https://github.com/sbarbett/pihole-ansible/blob/main/roles/manage_lists/README.md))\n  - `manage_groups_clients`: A role that iterates over one or more PiHole hosts and manages a batch of groups and clients as defined by the user. ([README](https://github.com/sbarbett/pihole-ansible/blob/main/roles/manage_groups_clients/README.md))\n\n## Getting Started\n\n### Prerequisites\n\n- **Ansible:** Version 2.9 or later.\n- **Python:** The control node requires Python 3.x.\n- **pihole6api Library**\n\n### Installation\n\nInstall the collection via Ansible Galaxy:\n\n```bash\nansible-galaxy collection install sbarbett.pihole\n```\n\nYou can also build it locally:\n\n```bash\ngit clone https://github.com/sbarbett/pihole-ansible\nansible-galaxy collection build\nansible-galaxy collection install sbarbett-pihole-x.x.x.tar.gz\n```\n\n#### `pihole6api` Dependency\n\nThe `pihole6api` library is required for this Ansible collection to function. The installation method depends on how you installed Ansible.\n\n```bash\npip install pihole6api\n```\n\nHowever, some Linux distributions (Debian, macOS, Fedora, etc.) **restrict system-wide `pip` installs** due to [PEP 668](https://peps.python.org/pep-0668/). In that case, use one of the methods below.\n\n**Installing in a Virtual Environment (Recommended):**\n\nIf you want an isolated environment that won’t interfere with system-wide packages, install both `pihole6api` and Ansible in a virtual environment:\n\n```bash\npython -m venv venv\nsource venv/bin/activate\npip install pihole6api ansible\n```\n\nTo confirm that `ansible` and `pihole6api` are installed correctly within the environment, run:\n\n```bash\nwhich python \u0026\u0026 which ansible\npython -c \"import pihole6api; print(pihole6api.__file__)\"\n```\n\nTo exit the virtual environment:\n\n```bash\ndeactivate\n```\n\n**Using `pipx`:**\n\nIf Ansible is installed via `pipx`, inject `pihole6api` into Ansible’s environment:\n\n```bash\npipx inject ansible pihole6api --include-deps\n```\n\nVerify installation:\n\n```bash\npipx runpip ansible show pihole6api\n```\n\nSince Ansible does not automatically detect `pipx` environments, you must explicitly set the Python interpreter in your Ansible configuration:\n\nEdit `ansible.cfg`:\n\n```\n[defaults]\ninterpreter_python = ~/.local/pipx/venvs/ansible/bin/python\n```\n\nFor more information on `pipx` see [the official documentation](https://github.com/pypa/pipx) and [the Ansible install guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html).\n\n**Installing for System-Wide Ansible (Generally Not Recommended):**\n\nIf 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:\n\n```bash\nsudo pip install --break-system-packages pihole6api\n```\n\nVerify installation:\n\n```bash\npython3 -c \"import pihole6api; print(pihole6api.__file__)\"\n\n```\n\n## Usage Examples\n\n### Modules\n\n* [Enable and Configure the PiHole DHCP Client](https://github.com/sbarbett/pihole-ansible/blob/main/examples/configure-dhcp-client.yml)\n* [Disable the PiHole DHCP Client](https://github.com/sbarbett/pihole-ansible/blob/main/examples/disable-dhcp-client.yml)\n* [Remove a DHCP Lease](https://github.com/sbarbett/pihole-ansible/blob/main/examples/remove-dhcp-lease.yml)\n* [Create a Local A Record](https://github.com/sbarbett/pihole-ansible/blob/main/examples/create-a-record.yml)\n* [Remove a Local A Record](https://github.com/sbarbett/pihole-ansible/blob/main/examples/delete-a-record.yml)\n* [Create a Local CNAME](https://github.com/sbarbett/pihole-ansible/blob/main/examples/create-cname.yml)\n* [Remove a Local CNAME](https://github.com/sbarbett/pihole-ansible/blob/main/examples/delete-cname.yml)\n* [Create an Allow List](https://github.com/sbarbett/pihole-ansible/blob/main/examples/create-allow-list.yml)\n* [Create a Block List](https://github.com/sbarbett/pihole-ansible/blob/main/examples/create-block-list.yml)\n* [Manage Allow Lists](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-allow-lists.yml)\n* [Manage Block Lists](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-block-lists.yml)\n* [Manage Groups](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-groups.yml)\n* [Manage Clients](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-clients.yml)\n\n### Roles\n\nRoles are designed to orchestrate changes across multiple PiHole instances.\n\n* [Manage Local Records](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-records.yml)\n* [Manage Lists](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-lists.yml)\n* [Manage Groups and Clients](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-groups-clients.yml)\n\n## Documentation\n\n* Each module includes embedded documentation. You can review the options by using `ansible-doc sbarbett.module_name`.\n* Detailed information for each role is provided in its own `README` file within the role directory.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbarbett%2Fpihole-ansible","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsbarbett%2Fpihole-ansible","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbarbett%2Fpihole-ansible/lists"}