diff options
Diffstat (limited to 'daemon/bindings/net_server.rst')
| -rw-r--r-- | daemon/bindings/net_server.rst | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/daemon/bindings/net_server.rst b/daemon/bindings/net_server.rst new file mode 100644 index 0000000..53e0efe --- /dev/null +++ b/daemon/bindings/net_server.rst @@ -0,0 +1,166 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +Addresses and services +---------------------- + +Addresses, ports, protocols, and API calls available for clients communicating +with resolver are configured using :func:`net.listen`. + +First you need to decide what service should be available on given IP address ++ port combination. + +.. csv-table:: + :header: "Protocol/service", "net.listen *kind*" + + "DNS (unencrypted UDP+TCP, :rfc:`1034`)","``dns``" + "DNS (unencrypted UDP, :ref:`using XDP Linux API <dns-over-xdp>`)","``xdp``" + ":ref:`dns-over-tls`","``tls``" + ":ref:`dns-over-https`","``doh2``" + ":ref:`Web management <mod-http-built-in-services>`","``webmgmt``" + ":ref:`Control socket <control-sockets>`","``control``" + ":ref:`mod-http-doh`","``doh``" + +.. 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/``. + +.. function:: net.listen(addresses, [port = 53, { kind = 'dns', freebind = false }]) + + :return: ``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. + +.. csv-table:: + :header: "**Network protocol**", "**Configuration command**" + + "DNS (UDP+TCP, :rfc:`1034`)","``net.listen('192.0.2.123', 53)``" + "DNS (UDP, :ref:`using XDP <dns-over-xdp>`)","``net.listen('192.0.2.123', 53, { kind = 'xdp' })``" + ":ref:`dns-over-tls`","``net.listen('192.0.2.123', 853, { kind = 'tls' })``" + ":ref:`dns-over-https`","``net.listen('192.0.2.123', 443, { kind = 'doh2' })``" + ":ref:`Web management <mod-http-built-in-services>`","``net.listen('192.0.2.123', 8453, { kind = 'webmgmt' })``" + ":ref:`Control socket <control-sockets>`","``net.listen('/tmp/kres.control', nil, { kind = 'control' })``" + + +Examples: + + .. code-block:: lua + + 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 :ref:`runtime-cfg`. + +.. function:: net.close(address, [port]) + + :return: boolean (at least one endpoint closed) + + Close all endpoints listening on the specified address, optionally restricted by port as well. + + +.. function:: net.list() + + :return: Table of bound interfaces. + + Example output: + + .. code-block:: none + + [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 + } + } + +.. function:: net.interfaces() + + :return: Table of available interfaces and their addresses. + + Example output: + + .. code-block:: none + + [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`` + +.. function:: 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. + + .. code-block:: lua + + > 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. + +.. _`dnsproxy module`: https://www.knot-dns.cz/docs/2.7/html/modules.html#dnsproxy-tiny-dns-proxy + + |