From: Aleš Mrázek <ales.mrazek@nic.cz>
Date: Thu, 18 Aug 2022 13:13:27 +0000 (+0200)
Subject: doc: usecases: network interfaces added
X-Git-Tag: v6.0.0a1~26^2~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9c2700f8fb358f59ea8edd27519b0bfbf3201ee6;p=thirdparty%2Fknot-resolver.git

doc: usecases: network interfaces added
---

diff --git a/doc/index.rst b/doc/index.rst
index 3907525e9..1d4665928 100644
--- 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
index 000000000..657fb6526
--- /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