305 lines
10 KiB
Markdown
305 lines
10 KiB
Markdown
---
|
||
navigation: true
|
||
title: Adguard Home
|
||
main:
|
||
fluid: false
|
||
---
|
||
:ellipsis{left=0px width=40rem top=10rem blur=140px}
|
||
# Adguard Home
|
||
|
||
::alert{type="info"}
|
||
🎯 __Goals:__
|
||
- Install and deploy Adguard
|
||
- Expose Adguard
|
||
- Secure DNS queries with SSL/TLS
|
||
- Configure client devices
|
||
::
|
||
|
||
[AdGuard Home](https://github.com/AdguardTeam/AdGuardHome) is a DNS server that blocks ads and tracking at the system level. Once configured, it will protect ALL your home devices without the need for any client-side software.
|
||
|
||
It works as a DNS server that redirects tracking domains to a “black hole,” preventing your devices from connecting to them.
|
||
|
||
In practice, once it's in place, all you need to do is set your devices to use Adguard as their DNS server.
|
||
|
||
**Quick reminder of how DNS works:**
|
||
|
||
When you visit a site or use an app, it makes requests to various domains to load content—ads in particular. Your device doesn’t know the IP addresses of these domains, so it contacts a _Domain Name Server_ (DNS), which returns the current IP address.
|
||
|
||
By default, your device uses your ISP's DNS server, which is usually configured in your router or, for mobile devices, at the carrier’s CGNAT level. You can change this in your browser settings, your device’s system settings, or even directly in your router, depending on your ISP.
|
||
|
||
Adguard will act as a middleman between your device and the upstream DNS servers. If you configure your devices to use Adguard:
|
||
|
||
- If the domain is not in a blocklist, Adguard queries the upstream DNS servers and returns the correct IP to your device.
|
||
- If the domain *is* in a blocklist, Adguard will block the request and return nothing, so the associated content won’t load.
|
||
|
||
This is how ads and malicious domains are blocked—Adguard blocks only the bad domains, allowing the rest of the page to load normally.
|
||
|
||
|
||
|
||
## Installation
|
||
---
|
||
Folder structure:
|
||
|
||
```console
|
||
root
|
||
└── docker
|
||
└── adguard
|
||
├── confdir
|
||
├── workdir
|
||
├── compose.yaml
|
||
└── .env
|
||
```
|
||
|
||
::alert{type="info"}
|
||
:::list{type="info"}
|
||
- We will also mount the `/docker/swag/config/etc/letsencrypt` folder to access Swag's SSL certificate.
|
||
:::
|
||
::
|
||
|
||
Open Dockge and click `compose`
|
||
|
||
Name the stack `adguardhome` and paste the configuration below:
|
||
|
||
```yaml
|
||
---
|
||
services:
|
||
adguardhome:
|
||
container_name: adguard
|
||
image: adguard/adguardhome
|
||
restart: unless-stopped
|
||
ports:
|
||
- 53:53/udp
|
||
- 8080:80/tcp
|
||
- 4443:443/tcp
|
||
- 853:853/tcp
|
||
- 3000:3000/tcp
|
||
volumes:
|
||
- /docker/adguardhome/confdir:/opt/adguardhome/conf
|
||
- /docker/adguardhome/workdir:/opt/adguardhome/work
|
||
- /docker/swag/config/etc/letsencrypt:/swag-ssl:ro
|
||
```
|
||
|
||
::alert{type="success"}
|
||
✨ __Tip:__ Add the watchtower label to each container to automate updates
|
||
|
||
```yaml
|
||
services:
|
||
adguardhome:
|
||
# ...
|
||
labels:
|
||
- com.centurylinklabs.watchtower.enable=true
|
||
```
|
||
::
|
||
|
||
Deploy the stack.
|
||
|
||
Go to `http://yourserverip:3000` and follow the setup instructions.
|
||
|
||
That’s it! Adguard is deployed.
|
||
|
||
|
||
## Exposing AdGuard with SWAG
|
||
---
|
||
To make AdGuard usable from outside your home network, you need to expose it.
|
||
|
||
::alert{type="info"}
|
||
:::list{type="info"}
|
||
- __Prerequisites:__ We assume you've created a subdomain like `adguard.mydomain.com` in your [DNS zone](/general/dns) with a `CNAME` pointing to `mydomain.com`, and that you’ve already forwarded port `443` from your router to port `443` on your server in your [NAT rules](/general/nat). Also forward port `53` and port `853` to your server. These ports are used to route DNS requests.
|
||
:::
|
||
::
|
||
|
||
::alert{type="warning"}
|
||
:::list{type="warning"}
|
||
- Do not use Cloudflare tunnels to expose AdGuard, and make sure any proxying is disabled.
|
||
:::
|
||
::
|
||
|
||
In Dockge, go to the SWAG stack and edit the compose file to add the AdGuard network:
|
||
|
||
```yaml
|
||
services:
|
||
swag:
|
||
container_name: # ...
|
||
# ...
|
||
networks: # Connect the container to the custom network
|
||
# ...
|
||
- adguard # Name of the network declared in the stack
|
||
|
||
networks: # Define the custom network
|
||
# ...
|
||
adguard: # Name of the network declared in the stack
|
||
name: adguard_default # Actual name of the external network
|
||
external: true # Specifies that this is an external network
|
||
```
|
||
|
||
::alert{type="info"}
|
||
:::list{type="info"}
|
||
- We assume here that the AdGuard network is named `adguard_default`. You can verify the connection is working by visiting the SWAG dashboard at http://yourserverip:81.
|
||
:::
|
||
::
|
||
|
||
Restart the stack by clicking "Deploy" and wait for SWAG to be fully operational.
|
||
|
||
Create and open the file `adguard.subdomain.conf`
|
||
|
||
::alert{type="success"}
|
||
✨ __Tip for terminal haters:__
|
||
You can use [File Browser](/serveex/files/file-browser) to browse and edit files instead of using terminal commands.
|
||
::
|
||
|
||
```shell
|
||
sudo vi /docker/swag/config/nginx/proxy-confs/adguard.subdomain.conf
|
||
```
|
||
|
||
Edit the file by pressing `i` and then pasting the configuration below:
|
||
|
||
```nginx
|
||
## Version 2023/05/31
|
||
# make sure that your adguard container is named adguard
|
||
# make sure that your dns has a cname set for adguard
|
||
|
||
server {
|
||
listen 443 ssl;
|
||
listen [::]:443 ssl;
|
||
|
||
server_name adguard.*;
|
||
|
||
include /config/nginx/ssl.conf;
|
||
|
||
client_max_body_size 0;
|
||
|
||
#if ($lan-ip = yes) { set $geo-whitelist yes; }
|
||
#if ($geo-whitelist = no) { return 404; }
|
||
if ($geo-blacklist = no) { return 404; }
|
||
|
||
# enable for ldap auth (requires ldap-location.conf in the location block)
|
||
#include /config/nginx/ldap-server.conf;
|
||
|
||
# enable for Authelia (requires authelia-location.conf in the location block)
|
||
#include /config/nginx/authelia-server.conf;
|
||
|
||
# enable for Authentik (requires authentik-location.conf in the location block)
|
||
#include /config/nginx/authentik-server.conf;
|
||
|
||
location / {
|
||
# enable the next two lines for http auth
|
||
#auth_basic "Restricted";
|
||
#auth_basic_user_file /config/nginx/.htpasswd;
|
||
|
||
# enable for ldap auth (requires ldap-server.conf in the server block)
|
||
#include /config/nginx/ldap-location.conf;
|
||
|
||
# enable for Authelia (requires authelia-server.conf in the server block)
|
||
#include /config/nginx/authelia-location.conf;
|
||
|
||
# enable for Authentik (requires authentik-server.conf in the server block)
|
||
#include /config/nginx/authentik-location.conf;
|
||
|
||
include /config/nginx/proxy.conf;
|
||
include /config/nginx/resolver.conf;
|
||
set $upstream_app adguard;
|
||
set $upstream_port 3000;
|
||
set $upstream_proto http;
|
||
proxy_pass $upstream_proto://$upstream_app:$upstream_port;
|
||
|
||
}
|
||
|
||
location /control {
|
||
include /config/nginx/proxy.conf;
|
||
include /config/nginx/resolver.conf;
|
||
set $upstream_app adguard;
|
||
set $upstream_port 3000;
|
||
set $upstream_proto http;
|
||
proxy_pass $upstream_proto://$upstream_app:$upstream_port;
|
||
|
||
}
|
||
|
||
location /dns-query {
|
||
# to properly use this please set `allow_unencrypted_doh: true` and `force_https: false` in adguard
|
||
# see https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration#configuration-file
|
||
include /config/nginx/proxy.conf;
|
||
include /config/nginx/resolver.conf;
|
||
set $upstream_app adguard;
|
||
set $upstream_port 3000;
|
||
set $upstream_proto http;
|
||
proxy_pass $upstream_proto://$upstream_app:$upstream_port;
|
||
|
||
}
|
||
}
|
||
```
|
||
|
||
::alert{type="success"}
|
||
✨ __Tip:__
|
||
<br/><br/>
|
||
You can protect this app with Authentik by opening `adguard.subdomain.conf` and removing the `#` in front of `include /config/nginx/authentik-server.conf;`{lang=nginx} and `include /config/nginx/authentik-location.conf;`{lang=nginx}. Don’t forget to [create an application and a provider in Authentik](/serveex/security/authentik/#protéger-une-app-par-reverse-proxy). You’ll need to exclude the URL `https://adguard.mydomain.com/dns-query` from authentication:
|
||
|
||
- Edit the AdGuard provider
|
||
- Under *Advanced Protocol Settings > Authenticated Paths*, enter `^/dns-query`
|
||
::
|
||
|
||
Press `Esc`, then save and exit by typing `:x`
|
||
|
||
And that's it! AdGuard is now exposed!
|
||
|
||
## Configure SSL/TLS Encryption
|
||
---
|
||
Encryption is essential if you want to keep your queries to AdGuard private. Encrypting your queries ensures that no one—not even your ISP—can see your history. It also ensures that only your server can respond to you.
|
||
|
||
To configure encryption:
|
||
|
||
- Go to _Settings_ then _Encryption_.
|
||
- Set the options as follows:
|
||
|
||
|
||
|
||
- Below, in the _Certificates_ section, check _Use file path for certificate_
|
||
- In the input field, enter `/swag-ssl/live/mydomain.com/fullchain.pem`, replacing `mydomain.com` with your actual domain.
|
||
- For _Private Key_, check _Use file path for private key_
|
||
- In the input field, enter `/swag-ssl/live/mydomain.com/privkey.pem`, replacing `mydomain.com` accordingly.
|
||
- Save
|
||
|
||
Done! Your future DNS queries are now protected!
|
||
|
||
## Configure Devices
|
||
---
|
||
You have several options (which you can combine) to configure your devices.
|
||
### Secure the Local Network
|
||
You can secure your local network with AdGuard by configuring your router to direct all DNS queries by default to AdGuard instead of your ISP’s DNS. Note: your router must allow DNS changes (Orange routers do not).
|
||
|
||
This option is usually in the _DHCP_ settings. Make sure to add a fallback DNS server such as:
|
||
|
||
- Cloudflare: `1.1.1.1`
|
||
- Google: `8.8.8.8`
|
||
|
||
Without this, if your server goes down, your devices will lose internet access.
|
||
|
||
::alert{type="info"}
|
||
:::list{type="info"}
|
||
- Some devices may have a separate DNS configured and may not use the router’s DNS.
|
||
:::
|
||
::
|
||
|
||
### Force a Browser to Use AdGuard
|
||
|
||
In your browser, you can configure a DNS to force it to use AdGuard Home.
|
||
In the settings, specify the address `https://adguard.mydomain.com/dns-query`
|
||
|
||
### Configure AdGuard at the System Level on Windows
|
||
|
||
In Windows, you need to configure AdGuard for each network adapter you want to use.
|
||
|
||
- Go to _Home > Network & Internet_, then select the network adapter to modify
|
||
- Click _Edit DNS_ (sometimes under _Hardware Properties_)
|
||
- Choose `Manual`
|
||
- Enable IPv4
|
||
- Enter your server’s public IP (the one accessible from the internet)
|
||
- Enable _DNS over HTTPS (manual template)_
|
||
- Disable _Fallback to plaintext_
|
||
- Save
|
||
|
||
All programs using that network adapter will now be filtered by AdGuard.
|
||
|
||
## Add Filters
|
||
---
|
||
|
||
- Go to the settings and change the filters. |