Skip to content

AGDNS-4106-mv-articles-to-dns-kb-vol.2 #443

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
masterkusok wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

AGDNS-4106-mv-articles-to-dns-kb-vol.2 #443

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dfd2e21
adguard-home: add new articles
masterkusok Jul 9, 2026
564a9d6
adguard-home: imp articles
masterkusok Jul 10, 2026
5216420
adguard-home: imp dhcp article
masterkusok Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 10 additions & 9 deletions docs/adguard-home/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -664,7 +664,7 @@ List of filters. Each filter has the following properties:

### `dhcp` {#dhcp}

Built-in DHCP server configuration. See also the [DHCP] article. It has the following properties:
Built-in DHCP server configuration. See also the [DHCP][DHCPv4] article. It has the following properties:

- `enabled`: DHCP server status.

Expand All @@ -682,15 +682,15 @@ Built-in DHCP server configuration. See also the [DHCP] article. It has the foll

- `icmp_timeout_msec`: Time to wait for an ICMP reply to detect an IP conflict, in milliseconds. If `0`, the feature is disabled.

- `options`: Custom DHCP options. See the [DHCP] article section on these options for more information.
- `options`: Custom DHCP options. See the [DHCP][DHCPv4] article section on these options for more information.

- `dhcpv6`: DHCPv6 settings. It has the following properties:

- `range_start`: the first IP address to be assigned to a client.

- `lease_duration`: same as in v4 above.

- `ra_slaac_only` and `ra_allow_slaac`: send RA packets either forcing the clients to use SLAAC or allowing them to choose. See the [DHCP] article section on these options for more information.
- `ra_slaac_only` and `ra_allow_slaac`: send RA packets either forcing the clients to use SLAAC or allowing them to choose. See the [DHCP][DHCPv6] article section on these options for more information.

- `local_domain_name`: The domain name that AdGuard Home’s DHCP server uses for hostnames of its clients. The default value, which is also set when this value is empty, is `lan`. So, if you have a machine called `myhost` in your network, and AdGuard Home is this network’s DHCP server, the hostname of that machine is `myhost.lan`. DNS queries of type `A` for such hosts are only allowed from locally served networks, such as `10.0.0.0/8`, `192.168.0.0/16`, and so on. Other clients receive an empty `NXDOMAIN` response.

Expand Down Expand Up @@ -826,12 +826,13 @@ Log settings.

Removing an entry from settings file will reset it to the default value. Deleting the file will reset all settings to the default values.

[DDR]: https://www.ietf.org/archive/id/draft-ietf-add-ddr-06.html
[DHCP]: https://adguard-dns.io/kb/adguard-home/dhcp/
[docker-conf]: https://adguard-dns.io/kb/adguard-home/docker/
[hsts]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
[rfc6147]: https://datatracker.ietf.org/doc/html/rfc6147
[tls-names]: https://pkg.go.dev/crypto/tls#pkg-constants
[DDR]: https://www.ietf.org/archive/id/draft-ietf-add-ddr-06.html
[DHCPv4]: https://adguard-dns.io/kb/adguard-home/dhcp/#dhcpv4-options
[DHCPv6]: https://adguard-dns.io/kb/adguard-home/dhcp/#dhcpv6-options
[docker-conf]: https://adguard-dns.io/kb/adguard-home/docker/
[hsts]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
[rfc6147]: https://datatracker.ietf.org/doc/html/rfc6147
[tls-names]: https://pkg.go.dev/crypto/tls#pkg-constants

## Reset web password {#password-reset}

Expand Down
174 changes: 174 additions & 0 deletions docs/adguard-home/dhcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
---
title: DHCP
sidebar_position: 10
---

AdGuard Home can be used as a DHCP server. This page describes how to do that.

## Prerequisites {#prerequisites}

1. Make sure that you run an OS on which AdGuard Home supports DHCP. We currently don’t support DHCP on Windows.

2. Make sure that your machine has a static IP address.

## Configuration {#configuration}

See the DHCP section in the [configuration][dhcp-conf] article for the overview of the DHCP configuration options. There are several configuration parameters for DHCP that can’t be set via the AdGuard Home administrator dashboard. Those are described below.

:::note

By default, AdGuard Home will set itself as the DNS server for the DHCP clients. The default lease time is 24 hours.

:::

[dhcp-conf]: https://adguard-dns.io/kb/adguard-home/configuration/#dhcp

### DHCPv4 options {#dhcpv4-options}
Comment thread
masterkusok marked this conversation as resolved.

The `options` field is used to explicitly specify the values for DHCP options and modify the response. In accordance with *Section 4.3.1* of [RFC 2131][rfc-2131], these options override the default options’ values set by Adguard Home and requested by a client, which means that if you want to set custom DNS server addresses using option `6` (Domain Name Server), you may want also add Adguard Home’s own addresses there. Otherwise, AdGuard Home’s filtering won’t work for the DHCP clients who receive these DNS server addresses.

Any option begins with an option *code* written as decimal integer. See [RFC 2132][rfc-2132] for the actual DHCP option codes and allowed lengths. The code is followed by an option’s *type* and *value*. Currently the following *types* are supported:

- `bool`: Human-readable form of a boolean value, and has the length of 1 octet.

**Example**:

```yaml
'options':
- '19 bool 0' # Disable IP forwarding for hosts.
- '20 bool t' # Enable non-local source routing for hosts.
- '29 bool F' # Disable subnet mask discovery.
- '30 bool true' # Enable mask supplying for supporting hosts.
- '36 bool False' # Make the hosts use RFC 894 for ethernet encapsulation.
```

- `del`: No-value option and is used to unconditionally remove options from the server’s responses (which may lead to weird behaviors, use with caution).

Since the list of options is interpreted sequentially from first to last, the subsequent option may override the previous ones. So this:

```yaml
'options':
- '19 bool T'
- '19 del'
- '20 del'
- '20 bool F'
```

instructs to remove the option `19`, and to set the option `20` to `false`.

- `dur`: Human-readable form of a duration in range [0 – 4294967296 seconds (about 136 days)] and has a length of *4* octets, just like a 32-bit unsigned integer.

**Example**:

```yaml
'options':
- '24 dur 10m'
```

- `hex`: Sequence of hexadecimal numbers of an arbitrary length.

**Example**:

```yaml
'options':
- '25 hex 0044012801FC03EE05D407D211001FE645FA'
```

- `ip`: Accepts an IPv4 address and has a length of *4* octets, just like an IPv4 itself.

**Example**:

```yaml
'options':
- '28 ip 192.168.0.255'
```

- `ips`: Accepts a comma-separated list of IPv4 addresses. It has an arbitrary length, but is always a multiple of *4* octets.

**Example**:

```yaml
'options':
- '6 ips 1.2.3.4,1.2.3.5'
```

- `text`: Accepts an arbitrary UTF-8 encoded string and has a length of encoded text.

**Example:**

```yaml
'options':
- '252 text http://server.domain/proxyconfig.pac'
```

- `u8`: Decimal number in range [0 – 255] and takes *1* octet, just like an unsigned 8-bit integer.

**Example:**

```yaml
'options':
- '23 u8 64'
```

- `u16`: Decimal number in range [0 – 65535] and takes *2* octets, just like an unsigned 16-bit integer.

**Example:**

```yaml
'options':
- '22 u16 576'
```

:::note

Thoroughly check that the option format and value are valid for the chosen type in accordance with [RFC 2132][rfc-2132] or others. AdGuard Home does not perform any option-specific validations.

:::

Currently there is a set of options listed in *Appendix A* of [RFC 2131][rfc-2131] with the default values chosen according to the documents mentioned there:

| Option | Value |
| -------------------------------- | --------------------------------------------- |
| IP Forwarding | Disabled |
| Non-Local Source Routing | Disabled |
| Maximum Datagram Reassembly Size | 576 bytes |
| Default IP Time-to-live | 64 seconds |
| Path MTU Aging Timeout Option | 10 minutes |
| Path MTU Plateau Table | See [Table 7.1 in RFC 1191][rfc-1191-tbl-7.1] |
| Interface MTU | 576 bytes |
| All subnets are local | False |
| Perform Mask Discovery | False |
| Mask Supplier | False |
| Perform Router Discovery | True |
| Router Solicitation Address | 224.0.0.2 |
| Broadcast Address | 255.255.255.255 |
| Use Trailer Encapsulation | False |
| ARP Cache Timeout | 1 minute |
| Ethernet Encapsulation version | RFC 894 |
| Default TCP TTL | 60 seconds |
| TCP Keepalive Interval | 2 hours |
| Put TCP Keepalive Garbage | True |
| Routers | `gateway_ip` from configuration |
| Subnet Mask | `subnet_mask` from configuration |

Some of these values may appear obsolete or may cause issues with some DHCP client implementations among the many existing. In accordance with [RFC 2131][rfc-2131] the options, when not explicitly configured, are only returned if requested by client within the option `55` (Parameter Request List).

### DHCPv6 options {#dhcpv6-options}

The option `dhcp.dhcpv6.ra_slaac_only`, if `true`, sends RA packets forcing the clients to use SLAAC. The DHCPv6 server won’t be started in this case.

The option `dhcp.dhcpv6.ra_allow_slaac`, if `true`, sends RA packets allowing the clients to choose between SLAAC and DHCPv6.

[rfc-1191-tbl-7.1]: https://datatracker.ietf.org/doc/html/rfc1191#section-7.1
[rfc-2131]: https://datatracker.ietf.org/doc/html/rfc2131
[rfc-2132]: https://datatracker.ietf.org/doc/html/rfc2132

## Automatic hosts {#auto-hosts}

Machines in the network can be reached more easily using the hostnames they send in the DHCP requests with a configurable top-level domain (TLD). By default, the TLD is `lan`. For example, if you have a machine called “workstation” in the network, and it sends a DHCP request with option 12 set to `workstation`, you can reach it over HTTP on the host `http://workstation.lan`.

You can also set a custom TLD or domain name using the `dns.local_domain_name` field in the [configuration][dhcp-conf] file.

## Stored leases {#stored-leases}

DHCP leases are stored in `data/leases.json`. The file format is not stable and may change in the future releases.
175 changes: 175 additions & 0 deletions docs/adguard-home/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
---
title: Docker
sidebar_position: 11
---

This page provides specific guidelines for running AdGuard Home inside the Docker container.

## Quick start {#quick-start}

### Pull the Docker image

This command will pull the latest stable version:

```sh
docker pull adguard/adguardhome
```

### Create directories for persistent configuration and data

The image exposes two volumes for data and configuration persistence. So, the following directories must be created on a suitable volume on the host system:

- Data directory, for example `/my/own/workdir`.

- Configuration directory, for example `/my/own/confdir`.

### Create and run the container

Use the following command to create a new container and run AdGuard Home:

```sh
docker run \
-d \
--name adguardhome \
-p 53:53/tcp -p 53:53/udp \
-p 67:67/udp -p 68:68/udp \
-p 80:80/tcp -p 443:443/tcp \
-p 443:443/udp -p 3000:3000/tcp \
-p 853:853/tcp \
-p 853:853/udp \
-p 5443:5443/tcp -p 5443:5443/udp \
-p 6060:6060/tcp \
--restart unless-stopped \
-v /my/own/workdir:/opt/adguardhome/work \
-v /my/own/confdir:/opt/adguardhome/conf \
adguard/adguardhome \
;
```

The AdGuard Home service admin panel can now be accessed via http://127.0.0.1:3000/ from a web browser.

The following port mappings might be needed:

- `-p 53:53/tcp -p 53:53/udp`: Required for plain DNS.

- `-p 67:67/udp -p 68:68/tcp -p 68:68/udp`: Required for DHCP server.

- `-p 80:80/tcp -p 443:443/tcp -p 443:443/udp -p 3000:3000/tcp`: Required for admin panel and [HTTPS/DNS-over-HTTPS][enc] server.

- `-p 853:853/tcp`: Required for running a [DNS-over-TLS][enc] server.

- `-p 853:853/udp`: Required for running a [DNS-over-QUIC][enc] server.

- `-p 5443:5443/tcp -p 5443:5443/udp`: Required for running a [DNSCrypt] server.

- `-p 6060:6060/tcp`: Required for running a pprof debug api.

### Client IPs

To make AdGuard Home see the original client IPs as opposed to something like `172.17.0.1`, the `--network host` argument must be added to the list of options.

### Control the container

AdGuard Home container can be controlled using the following commands:

- Start:

```sh
docker start adguardhome
```

- Stop:

```sh
docker stop adguardhome
```

- Remove:

```sh
docker rm adguardhome
```

[DNSCrypt]: https://adguard-dns.io/kb/adguard-home/encryption/#configure-dnscrypt
[enc]: https://adguard-dns.io/kb/adguard-home/encryption/

## Update to a newer version {#update}

1. Pull the new version from Docker Hub:

```sh
docker pull adguard/adguardhome
```

2. Stop and remove currently running container (assuming the container is named `adguardhome`):

```sh
docker stop adguardhome
docker rm adguardhome
```

3. Create and start the container using the new image using the command from the previous section.

## Running development builds {#unstable}

Unstable development builds might be accessed using `edge` or `beta` tags. In order to use it, simply replace `adguard/adguardhome` with `adguard/adguardhome:edge` or `adguard/adguardhome:beta` in every command from the quick start. For example:

```sh
docker pull adguard/adguardhome:edge
```

## Additional configuration {#configuration}

Upon the first run, a file with the default values named `AdGuardHome.yaml` is created. This file can be modified while the AdGuard Home container is not running. Otherwise, any changes to the file will be lost because the running program will overwrite them.

The settings are stored in the [YAML] format. The documentation describing all configurable parameters and their values is available on [this page][conf].

[YAML]: https://yaml.org
[conf]: https://adguard-dns.io/kb/adguard-home/configuration/

### Health-check

Recommended way to achieve a health check mechanism is to create a new image tailored for the target configuration. Implementations may use the special domain name `healthcheck.adguardhome.test.`, expecting it to resolve into NODATA answer. It imposes restrictions on usage of this particular name, so specifying it within the `blocked_hosts` array under the `dns` section of configuration file will break the healthcheck. The `allowed_clients` and `disallowed_clients` properties should allow the healthcheck client IP as well.

## DHCP server {#dhcp}

To use AdGuard Home’s DHCP server, the `--network host` argument should be passed when creating the container:

```sh
docker run --name adguardhome --network host ...
```

This option instructs Docker to use the host’s network rather than a docker-bridged network. Note that port mapping with `-p` is not necessary in this case.

:::note

The host networking driver only works on Linux hosts, and is not supported on Docker Desktop for Mac, Docker Desktop for Windows, or Docker EE for Windows Server.

:::

## `resolved` daemon {#resolved}

To run AdGuard Home on a system where the `resolved` daemon is started, `DNSStubListener` must be disabled to prevent port bind conflict:

1. Deactivate `DNSStubListener` and update the DNS server address. Create a new file, `/etc/systemd/resolved.conf.d/adguardhome.conf` (creating the `/etc/systemd/resolved.conf.d` directory if needed) and add the following content to it:

```ini
[Resolve]
DNS=127.0.0.1
DNSStubListener=no
```

Specifying `127.0.0.1` as the DNS server address is necessary because otherwise the nameserver will be `127.0.0.53` which doesn’t work without `DNSStubListener`.

2. Activate a new `resolv.conf` file:

```sh
mv /etc/resolv.conf /etc/resolv.conf.backup
ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf
```

3. Stop `DNSStubListener`:

```sh
systemctl reload-or-restart systemd-resolved
```
Loading
Loading