# Ansible Role: AdGuard Home

Install [AdGuard Home](https://github.com/AdguardTeam/AdGuardHome) privacy
protecting and ad-blocking DNS 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`:

```yaml
# Version of AdGuard Home to install. 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, turni 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 conig 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 someething 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:

```yaml
- 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:

1. Run the role with `adguardhome_user` set to `root`.
2. Go through the setup wizard available on port `3000`.
3. 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`.

## License

This project is licensed under the MIT License.

## Author Information

[Jim Myhrberg](https://jimeh.me/)