freekers / ansible-adguard

Ansible playbook to setup AdGuard Home with Unbound, including DoH, DoT & Let's Encrypt, based on Docker

Ansible-AdGuard Automated setup for online use

Intended Usecase

This Anible playbook deploys a self updating AdGuard Home stack based on Docker, featuring:

• Unbound as recursive DNS server instead of public upstream DNS servers
• DNS over HTTPS (DoH)
• DNS over TLS (DoT)
• IPv4
• Admin interface over HTTPS
• Automatic SSL certificate for DoH & DoT
• Self-updating, powered by Docker & Watchtower

Disclaimer

Please do not set up a public DNS resolver, i.e. an AdGuard Home instance facing the internet, if you don't know what you're doing. You risk getting in all sorts of trouble. Most ISPs don't allow public DNS resolvers on their networks and will shut you down without notice, because it's generally a bad idea..

If all you're looking for is an adblocking DNS service, please consider using AdGuard's own public DNS service instead.

Prerequisites

1. Your Linux server must be reachable over the internet on the following ports:

• 53 (UDP/TCP) for plain DNS resolution
• 80 (TCP) for ZeroSSL's validation method
• 443 (TCP) for AdGuard Home's webinterface & DoH
• 853 (TCP) for DoT

2. You must own a Fully Qualified Domain Name (FQDN), such as yourdomain.com.
   This is required to generate a valid SSL Certificate used for DoH & DoT.

3. You must setup an A (and AAAA record if IPv6 DNS resolution is desired) for your domain, pointing to the IP address of your Linux server.
   This is required to generate a valid ZeroSSL SSL Certificate and used for DoH & DoT.\

4. You must create 3 cnames: traefik, adguard and portainer this is needed for traefik as a reverse proxy provider. So you will connect to: adguard.example.com but you can also use traefik.example.com and portainer.example.com.

Installation Instructions

1. Install Ansible, for example: sudo apt-add-repository -y ppa:ansible/ansible && sudo apt install ansible on the machine that will initiate the playbook. Or run THIS Terraform script to automaticilly create a free linux ARM server with Oracle Cloud)

2. Clone repository using git clone https://github.com/Freekers/ansible-adguard.git

3. Install requirements ansible-galaxy install -r requirements/requirements.yml

4. Change all the needed stuff in vars folder. But in specific: docker.yml & firewall.yml & user-management.yml

   4.1 if you want to configure an external server edit: inventories/inventory.yml with the server ip you want to configure.

5. If you want to configure a complete server: ansible-playbook ansible-playbook.yml -i inventory/inventory.yml -e "hostname=adguard.website.com [email protected]"

   5.1 or if you want just to install adguard and not configure a whole server: ansible-playbook ansible-playbook.yml -e "hostname=adguard.website.com [email protected]" -t adguard

   5.2 If you want to run this on your local computer use: ansible-playbook --connection=local --inventory 127.0.0.1, ansible-playbook.yml -e "hostname=adguard.website.com [email protected]"

6. After installation, it can take up to 5 minutes before your AdGuard Home instance will be accessible. This is due to ZeroSSL's certificate creation process. AdGuard Home will not start before a valid SSL certificate has been generated, so please be patient! For more information, please refer to the 'Usage Instructions' section below.

Supported distros:

• Ubuntu 18.04 & 20.04 && 22.04
• Debian 9 & 10
• RockyLinux 8 & 9

You can also switch to blocky just change the docker-compose file found in: /roles/docker/templates/docker-compose.yml.j2.

Usage Instructions

After installation, you can access the AdGuard Home admin interface of your instance by navigating to yourdomain.com. You should automatically be redirected to the login screen of your AdGuard Home instance.
Please remember that it can take up to 5 minutes before your AdGuard Home instance will be accessible after installation due to ZeroSSL's certificate creation process. AdGuard Home will not start before a valid SSL certificate has been generated, so please be patient!

Refer to the setup page within the AdGuard Home's Admin interface to setup your devices to use your AdGuard Home instance as DNS server.

The docker-compose.yml file will be located at /srv/docker. You can use regular docker and docker-compose commands to stop/start/restart containers.

If needed, for manual configuration of AdGuard Home, please refer to their official documententation.
If needed, for manual configuration of Unbound, please refer to their official documententation.
If needed, for manual configuration of Watchtower, please refer to their official documententation.

Uninstallation Instructions

1. sudo docker-compose -f /srv/docker/docker-compose.yml down
2. rm -rf /srv/docker
3. Consult playbook.yml to manually review packages & firewall rules that are no longer needed (Optional)

Acknowledgements

• ansible-role-docker Ansible role by geerlingguy
• AdGuard Home Docker image by AdguardTeam
• unbound Docker image by obi12341
• watchtower Docker image by containrrr
• oisd.nl Blocklist by sjhgvr

License

Unless otherwise specified, all code in this repository is released under the GNU Affero General Public License v3.0. See the repository's LICENSE file for details.

ansible-adguard's Issues

Ran playbook, no luck

I followed the instructions and am not able to connect to the adguard interface after initial setup. Certificates were successfully created but every time I visit adguard.mydomain.com I get the Cloudflare notice saying web server down, any ideas as to why? Pretty new to this sorry if this is a noob mistake.

Couple of issues installing on Ubuntu 20.04.6 LTS

Hey, thanks for this cool project! I'm trying to execute the playbook on Ubuntu 20.04.6 LTS and ran into the following problems:

TASK [robertdebock.selinux : assert | Test if selinux_reboot is set correctly] *****************************************
fatal: [127.0.0.1 -> localhost]: FAILED! => {"msg": "The conditional check 'selinux_reboot is boolean' failed. The error was: template error while templating string: no test named 'boolean'. String: {% if selinux_reboot is boolean %} True {% else %} False {% endif %}"}

I temporarily removed the role to be able to proceed.

---

failed: [127.0.0.1] (item={'username': '<removed>', 'name': '<removed>', 'email': '<removed>', 'groups': 'sudo, adm, ubuntu'}) => {"ansible_loop_var": "item", "changed": false, "item": {"email": "<removed>", "groups": "sudo, adm, ubuntu", "name": "<removed>", "username": "<removed>"}, "msg": "Group ubuntu does not exist"}

To fix this, I removed the ubuntu group under user-management.yml.

---

TASK [user-management : Add authorized keys] ***************************************************************************
[WARNING]: Unable to find 'ssh-keys/DevSecNinja.key.pub' in expected paths (use -vvvvv to see paths)
fatal: [127.0.0.1]: FAILED! => {"msg": "An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: ssh-keys/DevSecNinja.key.pub. could not locate file in lookup: ssh-keys/DevSecNinja.key.pub"}

Added my public key to the ssh-keys folder. Might be useful to document this in the readme.

---

It seems DNS is broken here since I can't resolve any domains like google.com anymore:

TASK [geerlingguy.docker : Ensure dependencies are installed.] *********************************************************
fatal: [127.0.0.1]: FAILED! => {"cache_update_time": 1688294248, "cache_updated": false, "changed": false, "msg": "'/usr/bin/apt-get -y -o \"Dpkg::Options::=--force-confdef\" -o \"Dpkg::Options::=--force-confold\"       install 'apt-transport-https'' failed: E: Failed to fetch http://azure.archive.ubuntu.com/ubuntu/pool/universe/a/apt/apt-transport-https_2.0.9_all.deb  Temporary failure resolving 'azure.archive.ubuntu.com'\nE: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?\n", "rc": 100, "stderr": "E: Failed to fetch http://azure.archive.ubuntu.com/ubuntu/pool/universe/a/apt/apt-transport-https_2.0.9_all.deb  Temporary failure resolving 'azure.archive.ubuntu.com'\nE: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?\n", "stderr_lines": ["E: Failed to fetch http://azure.archive.ubuntu.com/ubuntu/pool/universe/a/apt/apt-transport-https_2.0.9_all.deb  Temporary failure resolving 'azure.archive.ubuntu.com'", "E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?"], "stdout": "Reading package lists...\nBuilding dependency tree...\nReading state information...\nThe following NEW packages will be installed:\n  apt-transport-https\n0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.\nNeed to get 1,704 B of archives.\nAfter this operation, 162 kB of additional disk space will be used.\nErr:1 http://azure.archive.ubuntu.com/ubuntu focal-updates/universe amd64 apt-transport-https all 2.0.9\n  Temporary failure resolving 'azure.archive.ubuntu.com'\n", "stdout_lines": ["Reading package lists...", "Building dependency tree...", "Reading state information...", "The following NEW packages will be installed:", "  apt-transport-https", "0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.", "Need to get 1,704 B of archives.", "After this operation, 162 kB of additional disk space will be used.", "Err:1 http://azure.archive.ubuntu.com/ubuntu focal-updates/universe amd64 apt-transport-https all 2.0.9", "  Temporary failure resolving 'azure.archive.ubuntu.com'"]}

I guess this comes from the name: Disable internal DNS task since it disables the stub listener. Would it be better to install the packages before disabling the stub listener? Or disabling it just before the Deploy Stack using Docker Compose task to get the port 53 binding to work. Although that task also needs DNS to function since it needs to pull containers.

---

Host became unreachable after this step (both SSH and HTTPS). Even after a reboot, I couldn't connect anymore (connection refused on SSH):

TASK [cleanup : Remove dependencies that are no longer required Debian]

Hope this helps!

The conditional check 'ansible_default_ipv6.address

Hi, I am having a problem with the installation.
I don't have IPv6 in my cloud VM and once the playbook fails to check IPv6 it does not proceed further.

VM arch: KVM
OS: Ubuntu 20.04 LTS
Ansible Version: 2.9.6

"The conditional check 'ansible_default_ipv6.address | length > 0' failed.

Nice to see you hopping onto adguard as well, may I ask what your reasons are :)?

I did try and install it on Oracle Cloud but I am getting an error:

TASK [Prepare Docker for IPv6] **************************************************************************************************************************************
fatal: [127.0.0.1]: FAILED! => {"msg": "The conditional check 'ansible_default_ipv6.address | length > 0' failed. The error was: error while evaluating conditional (ansible_default_ipv6.address | length > 0): 'dict object' has no attribute 'address'\n\nThe error appears to be in '/home/ubuntu/ansible-adguard/playbook.yml': line 86, column 5, but may\nbe elsewhere in the file depending on the exact syntax problem.\n\nThe offending line appears to be:\n\n\n  - name: Prepare Docker for IPv6\n    ^ here\n"}

I never used ansible before but it appears that this recurring line is failing:
when: ansible_default_ipv6.address | length > 0

a short summary

After some small hints like:

• errors in documentation (wrong path for example)
• problems with using sudo
  (sudo visudo
  And append a line as follows:

ansibleUserName ALL=(ALL) NOPASSWD:ALL)

• adding my IP to whitelist (middlewares.yml ) for portainer
• changing the hostname from adfree to adguard (AdGuardHome.yaml)
• make a uniform formating in the docker-compose.yml
• and some other small things ...

it is now finally running ... halfway

... unfortunately some things still do not work and slowly, I begin to despair.

What is not working:

• traefik dashbord - 404 page not found
• DoT (enabled on my android mobilephone - Private DNS) seams to be working, but its shown as simple DNS request in Adguard.
• The thing with the proxy IP is for me critical, cause all the deny list are useless when the container only sees the docker ip

I cant understand why (traefik) in this project is not working like a normal reverse proxy with x-forwarded-for enabled
Adguard needs the real IP for blocking unwanted clients.

br,
rowie

Ansible Playbook Error

Experiencing this error after running ansible-playbook playbook.yml --ask-become-pass

ERROR! no action detected in task. This often indicates a misspelled module name, or incorrect module path.

The error appears to have been in '/home/pirate/ansible-adguard/playbook.yml': line 216, column 5, but may
be elsewhere in the file depending on the exact syntax problem.

The offending line appears to be:


  - name: Deploy Stack using Docker Compose
    ^ here

Running:
Raspbian GNU/Linux 10 (buster)
Docker version 20.10.2, build 2291f61
docker-compose version 1.26.1, build 634eb50

Documentation improvements

Hi,

did you test your new stuff?

1st of all your howto is wrong:

ansible-playbook --connection=local --inventory 127.0.0.1, ansible-playbook.yml -e "hostname=adguard.website.com emailaddress=[email protected]"

cause the correct filename is ansible-playbook.yaml

2nd.

packages doesn´t exist in /roles .... next error

3rd:

what is the correct url for cloning the repo?

https://github.com/Freekers/ansible-adguard.git ??
https://github.com/bruvv/ansible-adguard-unbound.git ??

Maybe i am to stupid to run your commands as described but when i try it like your howto nothing is working. New ubuntu server 22.04 --- clean and open as described!

block DNS Amplification Attack by iptables

When having a public DNS server it's important to have it setup relative save.
That can be done with 3 easy iptable commands:

iptables -A INPUT -p udp --dport 53 -m string --from 40 --algo bm --hex-string '|0000FF0001|' -m recent --set --name dnsanyquery 
iptables -A INPUT -p udp --dport 53 -m string --from 40 --algo bm --hex-string '|0000FF0001|' -m recent --name dnsanyquery --rcheck --seconds 60 --hitcount 3 -j DROP
iptables -A INPUT -p tcp --dport 53 -m string --from 52 --algo bm --hex-string '|0000FF0001|' -m recent --set --name dnsanyquery 
iptables -A INPUT -p tcp --dport 53 -m string --from 52 --algo bm --hex-string '|0000FF0001|' -m recent --name dnsanyquery --rcheck --seconds 60 --hitcount 3 -j DROP

More info from your website ;)
https://freek.ws/2017/03/18/blocking-dns-amplification-attacks-using-iptables/