⚠️⚠️⚠️ Please note: This playbook has been deprecated in favor of ansible-adguard ⚠️⚠️⚠️
Automated, self-updating, Pi-hole stack using unbound as recursive DNS server
This Ansible playbook installs a self updating Pi-hole stack from scratch:
- You can choose between a Public Pi-hole or a Personal/Private one
- Both use unbound as recursive DNS server instead of public upstream DNS servers
- Both deploy (by default) the uber adlist/blocklist by OISD.nl
- Both add my (auto-updated) whitelist for your websurfing convenience
- If deploying a public Pi-hole, it includes LetsEncrypt to secure the admin interface with valid certificate over HTTPS
- If deploying a public Pi-hole, basic protection against DNS Amplification, SSH and bruteforce attacks is included using fail2ban
- The entire stack is based on Docker (so OpenVZ VPSes are NOT supported)
Tested on Ubuntu Server 18.04.2 LTS (Minimal) with Ansible 2.8 on Scaleway.com
Proposed Usecase
I designed this playbook for my own personal usecase and decided to make it public for those of you who have the same usecase and/or want to (re)use specific parts from my playbook.
I'm willing to learn how to make this playbook more robust and generic. Therefore I am accepting pull requests :)
I highly recommend checking the playbook before running so that you know what will be installed etc.
Remarks for Public installation
- Please do not set up a PUBLIC Pi-hole if you don't know what you're doing. You risk getting in all sorts of trouble. Most ISPs don't allow a public DNS resolver on their networks and will shut you down without notice. Why? Because it's generally a bad idea. You have been warned.
- Make sure to add an A (and if applicable, AAAA) record for your Pi-hole's hostname in your domainname's DNS, pointing to the IP address of your server.
- If certificate generation fails, click here for troubleshooting steps
Installation Instructions
- Install Ansible
- Clone repository using
git clone https://github.com/Freekers/automated-pihole.git
- Edit
hosts and .env file to reflect your setup, i.e. change domains, IP etc.
playbook.yml does NOT need to be changed!
- Install required roles from Ansible Galaxy roles using
ansible-galaxy install -r requirements.yml
- Start playbook using
ansible-playbook playbook.yml --ask-become-pass
When running the playbook on a remote target/server, make sure to copy your SSH key to remote target/server first (before running the playbook) using ssh-copy-id
Usage Instructions
Once everything has been installed, you can use regular docker and docker-compose commands to stop/start/restart containers.
The docker-compose.yml file will be located at /opt/automated-pihole after installation.
Uninstallation Instructions
sudo docker-compose -f /opt/automated-pihole/docker-compose.yml downrm -rf /opt/automated-pihole- Consult playbook.yml to manually review packages & firewall rules that are no longer needed
Disclaimer
- Even though this playbook configures and automatic updating Pi-hole, the Pi-Hole developers specifically have not included an auto-update option. It is best to read the release notes and determine if an update is appropriate for you, prior to updating. Sometimes updates can introduce breaking changes requiring manual intervention, such as editing/updating the docker-compose file. Therefore always keep an eye on the release notes.
- This playbook/script/repository is 100% unofficial and NOT affiliated with, funded, endorsed, or in any way associated with Pi-hole.
Acknowledgements
License
Unless otherwise specified, all code is released under the GNU General Public License v3.0. See the repository's LICENSE file for details.
Licenses for other components