1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
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
|
