Hickory DNS resolver (proto)

This extension has the qualified name envoy.network.dns_resolver.hickory

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension is intended to be robust against both untrusted downstream and upstream traffic.

Tip

This extension extends and can be used with the following extension category:

This extension must be configured with one of the following type URLs:

extensions.network.dns_resolver.hickory.v3.DnsOverTlsConfig

[extensions.network.dns_resolver.hickory.v3.DnsOverTlsConfig proto]

Configuration for DNS-over-TLS (DoT) servers.

{
  "servers": [],
  "tls_server_name": ...
}
servers

(repeated config.core.v3.Address) The list of DNS-over-TLS server addresses. The port should typically be 853.

tls_server_name

(string, REQUIRED) The SNI hostname to use for TLS verification. Required when servers are specified.

extensions.network.dns_resolver.hickory.v3.DnsOverHttpsConfig

[extensions.network.dns_resolver.hickory.v3.DnsOverHttpsConfig proto]

Configuration for DNS-over-HTTPS (DoH) servers.

{
  "server_urls": []
}
server_urls

(repeated string) The list of DNS-over-HTTPS endpoint URLs (e.g., https://dns.google/dns-query).

extensions.network.dns_resolver.hickory.v3.HickoryDnsResolverConfig

[extensions.network.dns_resolver.hickory.v3.HickoryDnsResolverConfig proto]

Configuration for the Hickory DNS resolver. This resolver uses the Hickory DNS library, a pure Rust DNS implementation, for DNS resolution. It supports standard DNS (UDP/TCP), DNS-over-TLS (DoT), DNS-over-HTTPS (DoH), and DNSSEC validation.

The resolver runs asynchronously on its own Tokio runtime threads, separate from Envoy’s event loop threads. Results are delivered back to the calling dispatcher thread.

{
  "resolvers": [],
  "dns_over_tls": {...},
  "dns_over_https": {...},
  "enable_dnssec": ...,
  "cache_size": {...},
  "num_resolver_threads": {...},
  "use_system_config": {...},
  "query_timeout": {...},
  "query_tries": {...}
}
resolvers

(repeated config.core.v3.Address) A list of DNS resolver addresses for standard UDP/TCP resolution. If not specified and use_system_config is not explicitly set to false, the system configuration (/etc/resolv.conf on Unix) will be used.

dns_over_tls

(extensions.network.dns_resolver.hickory.v3.DnsOverTlsConfig) Configuration for DNS-over-TLS (DoT). When specified, queries will be sent over TLS to the configured servers.

dns_over_https

(extensions.network.dns_resolver.hickory.v3.DnsOverHttpsConfig) Configuration for DNS-over-HTTPS (DoH). When specified, queries will be sent over HTTPS to the configured endpoints.

enable_dnssec

(bool) Enables DNSSEC validation for DNS responses. When enabled, the resolver will validate DNSSEC signatures and reject responses that fail validation.

Defaults to false.

cache_size

(UInt32Value) Maximum number of entries in the DNS response cache. The cache uses an LRU eviction policy and supports negative caching (caching of NXDOMAIN/NODATA responses).

Defaults to 1024.

num_resolver_threads

(UInt32Value) Number of threads in the Tokio runtime used for asynchronous DNS resolution. Each resolver instance runs its own Tokio runtime.

Defaults to 2. Maximum is 16.

use_system_config

(BoolValue) If true, read the system DNS configuration (/etc/resolv.conf on Unix) for name server addresses and search domains. When resolvers are also specified, they take precedence over the system configuration.

If not specified, defaults to true when no resolvers, dns_over_tls, or dns_over_https are configured.

query_timeout

(Duration) Timeout for each individual DNS query attempt.

Defaults to 5 seconds.

query_tries

(UInt32Value) Maximum number of query attempts before the resolver gives up. Each attempt may use a different name server.

Defaults to 3.