# Addresses and services

Addresses, ports, protocols, and API calls available for clients communicating with resolver are configured using `net.listen()`.

First you need to decide what service should be available on given IP address + port combination.

Protocol/service | net.listen kind
--- | ---
DNS (unencrypted UDP+TCP, RFC 1034) | `dns`
DNS (unencrypted UDP, using XDP Linux API) | `xdp`
DNS-over-TLS (DoT) | `tls`
DNS-over-HTTPS (DoH) | `doh2`
Web management | `webmgmt`
Control socket | `control`
Legacy DNS-over-HTTPS (DoH) | `doh_legacy`

Note

By default, unencrypted DNS and DNS-over-TLS are configured to listen on localhost.

Control sockets are created either in `/run/knot-resolver/control/` (when using systemd) or `$PWD/control/`.

net.listen(addresses[, port = 53, { kind = 'dns', freebind = false }])
  Returns

    `true` if port is bound, an error otherwise

  Listen on addresses; port and flags are optional. The addresses can be specified as a string or device. Port 853 implies `kind = 'tls'` but it is always better to be explicit. Freebind allows binding to a non-local or not yet available address.

Network protocol | Configuration command
--- | ---
DNS (UDP+TCP, RFC 1034) | `net.listen('192.0.2.123', 53)`
DNS (UDP, using XDP) | `net.listen('192.0.2.123', 53, { kind = 'xdp' })`
DNS-over-TLS (DoT) | `net.listen('192.0.2.123', 853, { kind = 'tls' })`
DNS-over-HTTPS (DoH) | `net.listen('192.0.2.123', 443, { kind = 'doh2' })`
Web management | `net.listen('192.0.2.123', 8453, { kind = 'webmgmt' })`
Control socket | `net.listen('/tmp/kres.control', nil, { kind = 'control' })`

Examples:

>     net.listen('::1')
>     net.listen(net.lo, 53)
>     net.listen(net.eth0, 853, { kind = 'tls' })
>     net.listen('192.0.2.1', 53, { freebind = true })
>     net.listen({'127.0.0.1', '::1'}, 53, { kind = 'dns' })
>     net.listen('::', 443, { kind = 'doh2' })
>     net.listen('::', 8453, { kind = 'webmgmt' }) -- see http module
>     net.listen('/tmp/kresd-socket', nil, { kind = 'webmgmt' }) -- http module supports AF_UNIX
>     net.listen('eth0', 53, { kind = 'xdp' })
>     net.listen('192.0.2.123', 53, { kind = 'xdp', nic_queue = 0 })

Warning

On machines with multiple IP addresses avoid listening on wildcards `0.0.0.0` or `::`. Knot Resolver could answer from different IP addresses if the network address ranges overlap, and clients would probably refuse such a response.

## Features for scripting

Following configuration functions are useful mainly for scripting or Run-time reconfiguration.

net.close(address[, port])
  Returns

    boolean (at least one endpoint closed)

  Close all endpoints listening on the specified address, optionally restricted by port as well.

net.list()
  Returns

    Table of bound interfaces.

  Example output:

      [1] => {
          [kind] => tls
          [transport] => {
              [family] => inet4
              [ip] => 127.0.0.1
              [port] => 853
              [protocol] => tcp
          }
      }
      [2] => {
          [kind] => dns
          [transport] => {
              [family] => inet6
              [ip] => ::1
              [port] => 53
              [protocol] => udp
          }
      }
      [3] => {
          [kind] => dns
          [transport] => {
              [family] => inet6
              [ip] => ::1
              [port] => 53
              [protocol] => tcp
          }
      }
      [4] => {
          [kind] => xdp
          [transport] => {
              [family] => inet4+inet6
              [interface] => eth2
              [nic_queue] => 0
              [port] => 53
              [protocol] => udp
          }
      }

net.interfaces()
  Returns

    Table of available interfaces and their addresses.

  Example output:

      [lo0] => {
          [addr] => {
              [1] => ::1
              [2] => 127.0.0.1
          }
          [mac] => 00:00:00:00:00:00
      }
      [eth0] => {
          [addr] => {
              [1] => 192.168.0.1
          }
          [mac] => de:ad:be:ef:aa:bb
      }

  Tip

  You can use `net.<iface>` as a shortcut for specific interface, e.g. `net.eth0`

net.tcp_pipeline([len])

  Get/set per-client TCP pipeline limit, i.e. the number of outstanding queries that a single client connection can make in parallel. Default is 100.

      > net.tcp_pipeline()
      100
      > net.tcp_pipeline(50)
      50

  Warning

  Please note that too large limit may have negative impact on performance and can lead to increased number of SERVFAIL answers.