UNWIND.CONF(5) | File Formats Manual | UNWIND.CONF(5)

# NAME

`unwind.conf` — validating DNS resolver configuration file

# DESCRIPTION

The unwind(8) daemon is a validating DNS resolver.

The `unwind.conf` config file is divided into the following main sections:

Macros
  Definitions of variables that can be used later, simplifying the configuration file.
Global configuration
  Global settings for unwind(8).

Additional configuration files can be included with the `include` keyword.

## Macros

A macro is defined with a command of the form name=value. The macro name can contain letters, digits, and underscores and cannot be a reserved word (for example, `forwarder`, `port`, or `DoT`). Within unquoted arguments, the string $name is later expanded to value.

For example:

    fwd1=192.0.2.53
    fwd2=192.0.2.153
    forwarder { $fwd1 $fwd2 }

## Global configuration

`block list` file [`log`]
  A file containing domains to block, one per line. If a domain from this list is queried, `unwind` answers with a return code of `REFUSED`. With `log` blocked queries are logged. The list supports limited wildcard syntax: domains starting with . (dot) are treated as any subdomains on that zone.
`forwarder` {address [`port` number] [[`authentication name` name] `DoT`] ...}
  A list of addresses of DNS name servers to forward queries to. `port` defaults to 53. If `DoT` is specified, use DNS over TLS when sending queries to the server at address. The default `port` is 853. name validates the certificate of the DNS over TLS server.
`preference` {type ...}
  A list of DNS name server types to specify the order in which name servers are picked when measured round-trip time medians are equal. Additionally, the first mentioned type gets a time bonus. Validating name servers are always picked over non-validating name servers. DNS name server types are, in default order of preference:
  `DoT`
    DNS over TLS name servers configured in `unwind.conf`.
  `oDoT-forwarder`
    Name servers configured in `unwind.conf`. `unwind` tries to opportunistically use DNS over TLS.
  `forwarder`
    Name servers configured in `unwind.conf`.
  `recursor`
    `unwind` itself recursively resolves names.
  `oDoT-autoconf`
    Name servers learned from autoconfiguration. A list of sources for proposals learned through autoconfiguration is documented in resolvd(8). `unwind` tries to opportunistically use DNS over TLS.
  `autoconf`
    Name servers learned from autoconfiguration.
  `stub`
    Name servers learned from autoconfiguration, queried using the libc functions (see asr_run(3)). Will never validate. Useful when running behind broken middle boxes that do not like edns0. DNS answers from stub name servers are not cached.
`force` [`accept bogus`] type {name ...}
  Force resolving of name and its subdomains by the given resolver type. The type must be listed in the `preference` list to be used. If `accept bogus` is specified, validation is not enforced.

# FILES

/etc/unwind.conf
  The default unwind(8) configuration file.

# EXAMPLES

Block requests for domains in /etc/blocklist and log each blocked request:

    block list "/etc/blocklist" log

Define a DNS over TLS (DoT) forwarder and make it the preferred resolver:

    forwarder { 192.168.1.250 port 8080 authentication name "resolver.local" DoT }
    preference { DoT }

Where a domain requires a specific nameserver and it may only exist in a nameserver available on the local network, force unwind(8) to use a specific resolver type:

    force autoconf { domain.local }

# SEE ALSO

rc.conf.local(8), unwind(8), unwindctl(8)

# HISTORY

The `unwind.conf` file format first appeared in OpenBSD 6.5.

July 8, 2025 | Debian