erldns_listeners (erldns v10.0.0-rc4)

View Source

DNS listeners configuration.

In order to configure, add to the application environment:

{erldns, [
    {listeners, [
        #{name => Name, transport => Protocol, ip => IP, port => Port, parallel_factor => PFactor}
    ]}
]}

See the type config/0 for details.

Telemetry events

Emits the following telemetry events:

[erldns, request, start]

  • Measurements:
    monotonic_time := integer()
request_size := non_neg_integer()
  • Metadata:
    transport := udp | tcp

[erldns, request, stop]

  • Measurements:
    monotonic_time := integer()
duration := non_neg_integer()
response_size := non_neg_integer()
  • Metadata:
    transport := udp | tcp
dnssec := boolean()

[erldns, request, error]

  • Measurements:
    count := non_neg_integer()
  • Metadata:
    transport := udp | tcp
kind => exit | error | throw
reason => term()
stacktrace => [term()]

[erldns, request, timeout]

  • Measurements:
    count := non_neg_integer()
  • Metadata:
    transport := udp | tcp

[erldns, request, dropped]

  • Measurements:
    count := non_neg_integer()
  • Metadata:
    transport := udp | tcp

[erldns, request, delayed]

  • Measurements:
    count := non_neg_integer()
  • Metadata:
    transport := udp | tcp

Summary

Types

config()

Configuration map for a listener.

name()

Name of the listener, a required parameter.

parallel_factor()

A multiplying factor for parallelisation.

stats()

Statistics about each listener.

transport()

Transport protocol. Default is standard which creates both UDP and TCP listeners.

Functions

get_stats()

Get statistics about all listeners.

reset_queues()

Reset all queues by restarting all listeners.

Types

config()

-type config() ::
          #{name := name(),
            transport => transport(),
            ip => inet:ip_address() | string() | any,
            port => inet:port_number(),
            parallel_factor => parallel_factor(),
            opts => #{atom() => term()}}.

Configuration map for a listener.

It can contain the following keys:

  • Name is any desired name in the form of an atom,
  • IP is any, in which case it will listen on all interfaces, or a valid ip address in tuple or string format. Default is any.
  • Port is a valid port number. Default is 53.
  • Transport is the transport protocol: udp, tcp, tls, or standard (creates both UDP and TCP). Default is standard.
  • Opts is a map of transport-specific options:
    • For TCP/TLS listeners:
      • ingress_request_timeout (optional): Timeout in milliseconds for receiving a complete request packet. Defaults to 500ms.
      • max_concurrent_queries (optional): Maximum number of parallel request workers per connection. Defaults to 50 workers.
      • idle_timeout_ms (optional): Timeout in milliseconds for idle connections (no data in buffer). Defaults to 2s.
      • request_timeout_ms (optional): Timeout in milliseconds for individual request processing. If a request exceeds this timeout, it will be killed and a SERVFAIL response will be sent to the client. Defaults to 1000ms.
      • max_connections (optional): Maximum number of concurrent TCP/TLS connections. When this limit is reached, new connections trigger load shedding. Defaults to 1000.
      • tcp_opts (optional): List of TCP socket options (e.g., [{nodelay, true}]). These are passed directly to gen_tcp and merged with the default socket options.
    • For TLS listeners (when transport => tls):
      • tls_opts (required): List of SSL/TLS options as expected by the Erlang ssl library. These options are appended to the socket_opts list and passed to ranch_ssl. Common options include:
        • {certfile, Path} - Path to the server certificate file (required)
        • {keyfile, Path} - Path to the private key file (required)
        • {versions, [tlsv1.2, tlsv1.3]} - Allowed TLS versions
        • {alpn_preferred_protocols, [<<"dot">>]} - ALPN protocols
        • {reuse_sessions, true} - Enable session reuse
        • See ssl module documentation for the complete list of SSL options.
    • For UDP listeners:
      • ingress_request_timeout (optional): Timeout in milliseconds for receiving a complete request packet. Defaults to 500ms.
      • udp_opts (optional): List of UDP socket options (e.g., [{recbuf, 65536}]). These are passed directly to gen_udp and merged with the default socket options.
  • ParallelFactor is a multiplying factor for parallelisation. Default is 1.

Example TCP listener:

#{
    name => my_tcp_listener,
    transport => tcp,
    port => 8053,
    opts => #{
        ingress_request_timeout => 1000,
        max_concurrent_queries => 100,
        tcp_opts => [{nodelay, true}, {keepalive, true}]
    }
}

Example TLS listener:

#{
    name => my_tls_listener,
    transport => tls,
    port => 853,
    opts => #{
        ingress_request_timeout => 1000,
        tls_opts => [
            {certfile, "priv/server.crt"},
            {keyfile, "priv/server.key"},
            {versions, ['tlsv1.2', 'tlsv1.3']},
            {alpn_preferred_protocols, [<<"dot">>]},
            {reuse_sessions, true}
        ]
    }
}

name()

-type name() :: atom().

Name of the listener, a required parameter.

parallel_factor()

-type parallel_factor() :: 1..512.

A multiplying factor for parallelisation.

The number of schedulers is multiplied by this factor when creating worker pools. By default, it is 1. The number of TCP and UDP acceptors will be of this size, while the number of UDP workers will be 4x and the maximum number of TCP workers will be 1024x. Note that the UDP pool is static, while the TCP pool is dynamic. See wpool and ranch respectively for details.

stats()

-type stats() :: #{{name(), tls | tcp | udp} => #{queue_length := non_neg_integer()}}.

Statistics about each listener.

transport()

-type transport() :: udp | tcp | tls | standard.

Transport protocol. Default is standard which creates both UDP and TCP listeners.

Functions

get_stats()

-spec get_stats() -> stats().

Get statistics about all listeners.

reset_queues()

-spec reset_queues() -> boolean().

Reset all queues by restarting all listeners.