doc: usecases: network interfaces added

diff --git a/doc/index.rst b/doc/index.rst
index 3907525e9e44f03024b8262f65b8c108ca005048..1d46659289095249d53204b0e900c5b38121d30c 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -21,10 +21,11 @@ and it provides a state-machine like API for extensions.
 
 
 .. toctree::
-   :caption: Scenarios (Use Cases)
-   :name: scenarios-chapter
+   :caption: Common Use Cases
+   :name: usecases-chapter
    :maxdepth: 1
 
+   usecase-network-interfaces
    usecase-internal-resolver
    usecase-isp-resolver
    usecase-personal-resolver

diff --git a/doc/usecase-network-interfaces.rst b/doc/usecase-network-interfaces.rst
new file mode 100644 (file)
index 0000000..657fb65
--- /dev/null
+++ b/doc/usecase-network-interfaces.rst
@@ -0,0 +1,42 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _usecase-network-interfaces:
+
+*******************************
+Listening on network interfaces
+*******************************
+
+The first thing you will probably need to configure are the network interfaces to listen to.
+
+The following configuration instructs Knot Resolver to receive standard unencrypted DNS queries on IP addresses `192.0.2.1` and `2001:db8::1`.
+Encrypted DNS queries are accepted using DNS-over-TLS protocol on all IP addresses configured on network interface `eth0`, TCP port 853.
+
+.. tabs::
+
+    .. group-tab:: |yaml|
+
+        .. code-block:: yaml
+
+            network:
+              listen:
+                - interface: ['192.0.2.1', '2001:db8::1'] # unencrypted DNS on port 53 is default
+                - interface: 'eth0'
+                  port: 853
+                  kind: 'dot'
+
+    .. group-tab:: |lua|
+
+        Network interfaces to listen on and supported protocols are configured using :func:`net.listen()` function.
+
+        .. code-block:: lua
+
+            -- unencrypted DNS on port 53 is default
+            net.listen('192.0.2.1')
+            net.listen('2001:db8::1')
+            net.listen(net.eth0, 853, { kind = 'tls' })
+
+.. warning::
+
+    On machines with multiple IP addresses on the same interface 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 refuse such a response.
\ No newline at end of file