c_ares

Resolver backed by the c-ares DNS library.

The wrapper still owns cache behavior and protective timeouts. The remaining keys on this page configure the underlying c-ares client.

The following common keys are supported:

• graceful_stop_wait

• protective_query_timeout

• positive_min_ttl

• positive_max_ttl

• negative_min_ttl

server

optional, type: str | seq

Name servers to use instead of those configured in /etc/resolv.conf.

If the value is a string, it may contain one or more sockaddr str values separated by whitespace.

If the value is a sequence, each element must be a sockaddr str.

The default port 53 is used when no port is specified.

Servers from different address families may be configured together.

If omitted, the resolver uses the system configuration from /etc/resolv.conf.

each_timeout

optional, type: u64, unit: ms

The number of milliseconds each name server is given to respond to a query on the first try. After the first try, the timeout algorithm becomes more complicated, but scales linearly with the value of timeout.

default: 2000

Changed in version 1.7.27: change default value from 5000 to 2000 to match default values set in c-ares 1.20.1

each_tries

optional, type: int

Number of attempts made to contact each name server before giving up.

default: 3

Changed in version 1.7.27: change default value from 2 to 3 to match default values set in c-ares 1.20.1

max_timeout

optional, type: u64, unit: ms

Upper bound on the timeout between sequential retry attempts. Retry timeouts increase from the base timeout value, and this setting caps the result.

notes: This will only have effect if link or build with c-ares 1.22.

default: 0, which is not explicitly set

Added in version 1.7.35.

udp_max_quires

optional, type: u32

Maximum number of UDP queries sent from a single ephemeral port to one DNS server before a new ephemeral port is allocated.

notes: This will only have effect if link or build with c-ares 1.20.

default: 0, which is unlimited

Added in version 1.7.35.

round_robin

optional, type: bool

If set to true, nameservers are selected in round-robin order for each resolution.

default: false

socket_send_buffer_size

optional, type: u32

Socket send-buffer size.

default: not set, which should be the value of /proc/sys/net/core/wmem_default

socket_recv_buffer_size

optional, type: u32

Socket receive-buffer size.

default: not set, which should be the value of /proc/sys/net/core/rmem_default

bind_ipv4

optional, type: ipv4 addr str

IPv4 bind IP used when creating sockets for the resolver.

bind_ipv6

optional, type: ipv6 addr str

IPv6 bind IP used when creating sockets for the resolver.

Example

server:
  - 8.8.8.8
  - 1.1.1.1:53
each_timeout: 2000
each_tries: 3
round_robin: true