DNS Configuration Reference

DNS resolver configuration for the Elide HTTP server.

Controls how the server resolves hostnames for outbound connections (e.g., upstream proxying, fetch requests). The resolver uses a non-blocking UDP-based DNS client, avoiding blocking on the main thread.

Resolution chain

Lookups proceed through these stages in order:

1. IP literal — if the input is already an IP address, no DNS is needed. 2. Hosts file — /etc/hosts lookup (when useHostsFile is enabled). 3. In-memory cache — TTL-aware cache of previous results. 4. UDP DNS query — non-blocking query to configured nameservers. 5. getaddrinfo fallback — blocking call on a background thread (used only when the UDP query times out or fails).

Example

pkl

dns {
  nameservers { "1.1.1.1"; "8.8.8.8" }
  useHostsFile = true
  cacheTtl = 300.s
  timeout = 5.s
}

> This page is auto-generated from the PKL schema. See the guide for usage examples.

`DnsConfig`

DNS resolver configuration.

All fields have sensible defaults. A minimal (empty) configuration reads nameservers from /etc/resolv.conf, enables the hosts file, and caches results using the TTL from DNS responses. Override individual fields to customize resolver behavior.

Field	Type	Default	Description
`nameservers`	Listing	(empty)	Custom nameserver addresses in `IP` or `IP:port` format.
`useHostsFile`	Boolean	`true`	Enable `/etc/hosts` lookups.
`hostsFilePath`	String	`"/etc/hosts"`	Path to the hosts file.
`cacheTtl`	Duration	`0.s`	Cache TTL override for all DNS results.
`maxCacheEntries`	UInt	`4096`	Maximum number of entries in the DNS result cache.
`timeout`	Duration	`5.s`	Timeout for a single DNS query before falling back to `getaddrinfo`.
`searchDomains`	Listing	(empty)	Search domains appended to unqualified hostnames (names without dots).

`nameservers`

Custom nameserver addresses in IP or IP:port format.

When empty (default), nameservers are read from /etc/resolv.conf. When specified, /etc/resolv.conf is ignored entirely. Port defaults to 53 if not specified. Both IPv4 and IPv6 addresses are supported.

Examples: "8.8.8.8", "1.1.1.1:53", "[2606:4700:4700::1111]"

`useHostsFile`

Enable /etc/hosts lookups.

When true (default), the hosts file is read once at startup and hostnames found there bypass DNS queries entirely. Disable this if you want all resolution to go through DNS nameservers.

`hostsFilePath`

Path to the hosts file.

Only used when useHostsFile is true. Override this for custom hosts files or non-standard system layouts. Default: /etc/hosts.

`cacheTtl`

Cache TTL override for all DNS results.

When set to a positive duration, all cached DNS results use this TTL regardless of the TTL in the DNS response. When 0.s (default), the TTL from the DNS response is honored. Set to a short duration (e.g., 30.s) to force more frequent re-resolution.

`maxCacheEntries`

Maximum number of entries in the DNS result cache.

When the cache is full, the entry with the earliest expiry is evicted. Default: 4096. Set to 0 for unlimited (not recommended in production due to unbounded memory growth).

`timeout`

Timeout for a single DNS query before falling back to getaddrinfo.

If no DNS response arrives within this duration, resolution falls back to a blocking getaddrinfo call on a background thread. Default: 5 seconds.

`searchDomains`

Search domains appended to unqualified hostnames (names without dots).

For example, with searchDomains { "example.com" }, a query for "myhost" will also try "myhost.example.com". When empty (default), unqualified names are queried as-is.

---