jimeh.adguardhome

Overview Versions Insights

Ansible Role: AdGuard Home

GitHub Workflow Status GitHub Ansible Quality Score

Install AdGuard Home privacy protecting and ad-blocking DNS server with Ansible.

Requirements

Ansible >= 2.9 (might work on previous versions)

Supported Operating Systems

Tested on:

Ubuntu 16.04 and 18.04
Debian stretch and buster
EL 7 and 8 derived distributions

It will likely work on other Debian and RHEL derived distros and versions than what's listed above.

Role Variables

Configurable role variables are all defined in defaults/main.yml:

# Version of AdGuard Home to install (without "v" prefix). If set to "latest",
# lookup the latest release via GitHub API.
adguardhome_version: "latest"

# When desired version is "latest", use GITHUB_TOKEN environment variable when
# looking up the latest release via GitHub's API. If you get rate limit errors
# from GitHub's API, turn this on and set the GITHUB_TOKEN environment variable
# to a Personal Access Token with "repo" and "user" scopes.
adguardhome_use_github_token: false

# User to run AdGuard Home under. Must initially be "root" if no config file is
# on disk. After going through the setup wizard, or manually adding a config
# file, this can be set to something else, like "adguard" for example.
adguardhome_user: root
adguardhome_group: "{{ adguardhome_user }}"

# When setting adguardhome_user to something other than "root", this determines
# if the user will be created as a system user or not. Rule of thumb is if the
# user is logged in to by humans, it probably is not a system user.
adguardhome_system_user: true

# Default paths.
adguardhome_bin_dir: "/opt/{{ adguardhome_service_name }}/bin"
adguardhome_config_dir: "/opt/{{ adguardhome_service_name }}/config"
adguardhome_config_name: AdGuardHome.yml
adguardhome_data_dir: "/opt/{{ adguardhome_service_name }}"
adguardhome_tmp_dir: /tmp

# Enable and start systemd service unit?
adguardhome_service_name: "adguardhome"
adguardhome_service_enable: true
adguardhome_service_start: true

# Disable DNSStubResolver if systemd-resolved servicee is running.
adguardhome_disable_systemd_dnsstubresolver: true

Example Playbook

The following example will install the latest available release of AdGuard Home:

- hosts: all
  roles:
    - { role: jimeh.adguardhome }

If you did not already have a configuration file in place, AdGuard Home will now be running with it's setup wizard on port 3000. Once you've gone through the setup wizard, the admin interface should be accessible on ports 80 and 443.

Non-root User

You can run AdGuard Home as a non-root user once you have a config file for in place. Without a config file, it will simply refuse to start if not running as root.

If you don't already have a config file from a different install of AdGuard Home, the best approach is:

Run the role with adguardhome_user set to root.
Go through the setup wizard available on port 3000.
Run the role again, this time setting adguardhome_user to a non-root user. If the specified user does not exist, it will be created.

Personally I run AdGuard Home under a user called adguard.