continuwuity/docs/guides/dns.mdx

# DNS Tuning (recommended)

For federation, Matrix homeservers conduct an enormous amount of DNS requests, sometimes up to thousands of queries per minute. Normal DNS resolvers are simply not designed for this load, and running Continuwuity with them will likely result in various [DNS and federation errors](../troubleshooting#dns-issues).

To solve this issue, it is strongly recommended to self-host a high-quality, external caching DNS resolver for Continuwuity. This guide will use [Unbound][unbound] as the recommended example, but the general principle applies to any resolver.

[unbound]: https://wiki.archlinux.org/title/Unbound

## Overview

For generic deployments, install your resolver of choice and configure your host system's `/etc/resolv.conf` to point to it. The resolver should ideally reside on the same host as Continuwuity.

```txt title="/etc/resolv.conf"
nameserver 127.0.0.1
```

**Avoid using `systemd-resolved`** as it does **not** perform very well under high load, and we have identified its DNS caching to not be very effective.

### For Docker users

By default, Docker bridge networks uses a poorly performing resolver to intercept and respond to container hostnames. **This resolver should also be avoided**. Instead, mount a custom `/etc/resolv.conf` file into the container, and hardcode a resolver address to bypass Docker's.

It is recommended to run a dedicated resolver container for Continuwuity, as to separate from the host's resolver setup. To do this, create a custom bridge network and IP range, and explicitly define an IP address for the resolver container.

<details>
<summary>Example Docker deployment with unbound</summary>

```yaml title="docker-compose.yml"
networks:
  # re-use the `proxy` network, as shown in the Docker deployment docs
  # (https://continuwuity.org/deploying/docker#choose-your-reverse-proxy)
  # and configure it with a custom subnet
  proxy:
    ipam:
      driver: default
      config:
        - subnet: "10.10.10.0/24"

services:
  homeserver:
    # ...
    volume:
      - ./continuwuity-resolv.conf:/etc/resolv.conf:ro
    networks:
      - proxy

  unbound:
    # ...
    networks:
      proxy:
        ipv4_address: 10.10.10.20
```

```txt title="continuwuity-resolv.conf"
nameserver 10.10.10.20
```

</details>

:::warning Breaking resolution with container hostnames

After you mount a custom `/etc/resolv.conf`, you won't be able to connect to other containers using their hostnames, such as for [appservices](../appservices.mdx) in the same Docker network. To work around this, force your appservice to use a static IP address, and refer to its static IP during registration.

<details>
<summary>Example Docker deployment with an appservice</summary>

```yaml title="docker-compose.yml"
# ... other parts of compose file ...

  appservice:
    # ...
    networks:
      proxy:
        ipv4_address: 10.10.10.30
```

~~~txt
!admin appservices register

```
id: appservice-name
url: http://10.10.10.30:29318
# rest of the registration file
```

~~~

</details>

:::

### For IPv4-only users

If you don't have IPv6 connectivity, change `ip_lookup_strategy` to `1` in Continuwuity's configuration in order to onlyresolve IPv4 addresses and remove unnecessary IPv6 queries.

```toml title="continuwuity.toml"
[global]
# 1 - Ipv4Only (Only query for A records, no AAAA/IPv6)
ip_lookup_strategy = 1
```

## Unbound

[Unbound][unbound] is the recommended resolver to run with Continuwuity. For Docker users, the `docker.io/madnuttah/unbound` image ([Github repo][madnuttah-unbound-repo]) can be used.

After installation, you can tune `/etc/unbound/unbound.conf` values according to your needs. While Continuwuity cannot recommend a "works-for-everyone" Unbound DNS setup guide, the official [Unbound tuning guide][unbound-tuning-guide] and the [Unbound Arch Linux wiki page][unbound-arch-linux] may be of interest.

Some values that are commonly tuned include:

- Increase `rrset-cache-size` and `msg-cache-size` to something much higher than the default `4M`, such as `64M`.

- Increase `discard-timeout` to something like `4800` to wait longer for upstream resolvers, as recursion can take a long time to respond to some domains. Continuwuity defaults to `dns_timeout = 10` seconds, so dropping requests early would lead to unnecessary retries and/or failures.

### Using a forwarder (optional)

Unbound employs **recursive resolution** by default, contacting many nameservers around the world in the process. While this is generally viable for most users, sometimes these recursive queries can be too slow to fully resolve. As an alternative, you may consider **forwarding** your queries to public resolvers, and benefit from faster responses from their caches.

However, do note that most popular upstreams (such as Google DNS or Quad9) employ IP ratelimiting, so a generous Unbound cache is still needed to avoid making too many queries.

If you want to use forwarders, configure it as follows:

<details>

<summary>unbound.conf</summary>

```
# Use cloudflare public resolvers as an example
forward-zone:
    name: "."
    forward-addr: 1.0.0.1@53
    forward-addr: 1.1.1.1@53
    # Also use IPv6 ones if you're dual-stack
    # forward-addr: 2606:4700:4700::1001@53
    # forward-addr: 2606:4700:4700::1111@53

# alternatively, use DNS-over-TLS for forwarders.
# this will encrypt traffic between you and the forwarder,
# but takes more time due to TLS overhead.
# forward-zone:
    # name: "."
    # forward-tls-upstream: yes
    # forward-addr: 1.0.0.1@853#cloudflare-dns.com
    # forward-addr: 1.1.1.1@853#cloudflare-dns.com
    # forward-addr: 2606:4700:4700::1001@853#cloudflare-dns.com
    # forward-addr: 2606:4700:4700::1111@853#cloudflare-dns.com
```

</details>

[madnuttah-unbound-repo]: https://github.com/madnuttah/unbound-docker/
[unbound-tuning-guide]: https://unbound.docs.nlnetlabs.nl/en/latest/topics/core/performance.html
[unbound-arch-linux]: https://wiki.archlinux.org/title/Unbound

## Other resolvers

### dnsproxy

[Dnsproxy][dnsproxy] and its sister product [AdGuard Home][adguard-home] are known to work with Continuwuity and has an official Docker image. They have support for DNS-over-HTTPS as well as DNS-over-QUIC, but not recursion.

To best utilise dnsproxy, you should enable proper caching with `--cache` and set `--cache-size` to something bigger, like `64000000`.

[dnsproxy]: https://github.com/AdguardTeam/dnsproxy
[adguard-home]: https://github.com/AdguardTeam/AdGuardHome

### dnsmasq

[dnsmasq][arch-linux-dnsmasq] can possibly work with Continuwuity, though it only supports forwarding rather than recursion. Increase the `cache-size` to something like `30000` for better caching performance.

However, `dnsmasq` does not support TCP fallback which can be problematic when receiving large DNS responses such as from large SRV records. If you still want to use dnsmasq, make sure you disable `dns_tcp_fallback` in Continuwuity config.

[arch-linux-dnsmasq]: https://wiki.archlinux.org/title/Dnsmasq

### Technitium DNS

[Technitium DNS Server][technitium] supports recursion as well as a myriad of forwarding protocols, allows saving cache to disk natively, and does work well with Continuwuity. Its out-of-the-box configs however ratelimits single-IP requests by a lot, and hence must be changed.

You may consult this [community guide][technitium-continuwuity] for more details on setting up and fine-tuning a dedicated Technitium instance for Continuwuity.

[technitium]: https://github.com/TechnitiumSoftware/DnsServer
[technitium-continuwuity]: https://muoi.me/~stratself/articles/technitium-continuwuity/

## Testing

As a rough stress test, you can run `!admin query resolver flush-cache -a` or `!admin server clear-caches` to clear your destinations cache - this will then trigger a netburst of DNS queries. If your resolver can handle this load without issue, then it should be ready for regular Continuwuity activity.

To test connectivity against a specific server, use `!admin debug ping <SERVER_NAME>` and `!admin debug resolve-true-destination <SERVER_NAME>`.

Note that it is expected that not all servers will be resolved, as some of them may be temporarily offline, have broken DNS and/or discovery configuration, or have been decommissioned.

## Further steps

It is recommended to set **`dns_cache_entries = 0`** inside Continuwuity to fully rely on the external resolver. While Continuwuity does have an internal cache, it can run into reliability issues if you're federating with many domains.

Additionally, you can also make the following improvements:

- Consider employing **persistent cache to disk**, so your resolver can still run without hassle after a restart. Unbound, via [Cache DB module][unbound-cachedb], can use Redis as a storage backend for this feature.

- Consider [enabling **Serve Stale**][unbound-serve-stale] functionality to serve expired data beyond DNS TTLs. Since most Matrix homeservers have static IPs, this should still allow federating with them when upstream resolvers have timed out. For dnsproxy, this corresponds to its [optimistic caching options][dnsproxy-usage].

- If you still experience DNS performance issues, another step could be to **disable DNSSEC** (which is computationally expensive) at a cost of slightly decreased security. On Unbound this is done by commenting out `trust-anchors` config options and removing the `validator` module.

- Some users have reported that setting `query_over_tcp_only = true` in Continuwuity has improved DNS reliability at a slight performance cost due to TCP overhead. Generally this is not needed if your resolver and homeserver is on the same machine.

[unbound-cachedb]: https://unbound.docs.nlnetlabs.nl/en/latest/manpages/unbound.conf.html#cache-db-module-options
[unbound-serve-stale]: https://wiki.archlinux.org/title/Unbound#Serving_expired_records
[dnsproxy-usage]: https://github.com/AdguardTeam/dnsproxy#usage