doc: document http module usage with systemd

diff --git a/daemon/bindings/net.rst b/daemon/bindings/net.rst
index b89b2c9ef8ae854ac9dc2b316a35ac1ece918b62..696fe6ed541e0db8cea09a75f1bffa87a2f794d0 100644 (file)
--- a/daemon/bindings/net.rst
+++ b/daemon/bindings/net.rst
@@ -9,7 +9,7 @@ For when listening on ``localhost`` just doesn't cut it.
 
 If you're using our packages with systemd with sockets support (not supported
 on CentOS 7), network interfaces are configured using systemd drop-in files for
-``kresd.socket`` and ``kresd-tls.socket``.
+``kresd.socket``, ``kresd-tls.socket`` and ``kresd-doh.socket``.
 
 To configure kresd to listen on public interface, create a drop-in file:
 
@@ -75,6 +75,28 @@ TLS connections.
    [Socket]
    ListenStream=192.0.2.115:853
 
+.. _kresd-doh-socket-configuration:
+
+To configure socket for DNS-over-HTTPS, make sure you have
+``kresd-doh.socket`` installed (it might be part of a separate
+``knot-resolver-module-http`` package).  Then, you can configure its network
+interfaces as above. Also, don't forget to load http module in configuration
+file, otherwise the socket won't have any function.
+
+For example, to remove the default localhost:44353 and listen on all interfaces
+on port 443, create the following drop-in file for ``kresd-doh.socket``:
+
+.. code-block:: bash
+
+   # /etc/systemd/system/kresd-doh.socket.d/override.conf
+   [Socket]
+   ListenStream=
+   ListenStream=[::]:443
+
+Make sure no other service is using port 443, as that will result in
+unpredictable behaviour. Alternately, you can use port 44353 where a collision
+is unlikely. Also, don't forget to load http module in configuration file.
+
 **Daemon network configuration**
 
 If you don't use systemd with sockets to run kresd, network interfaces are

diff --git a/etc/config/config.cluster.in b/etc/config/config.cluster.in
index 6984aa0920e80870bdb67b0a45ba6296718283d0..3c63b1eb0143b071f2507dd1da206db3bab873e2 100644 (file)
--- a/etc/config/config.cluster.in
+++ b/etc/config/config.cluster.in
@@ -6,6 +6,14 @@
 -- Refer to manual: https://knot-resolver.readthedocs.io/en/stable/daemon.html#configuration
 @config_defaults@
 
+-- For DNS-over-HTTPS and web management when using http module
+-- modules.load('http')
+-- http.config({
+--     cert = '/etc/knot-resolver/mycert.crt',
+--     key = '/etc/knot-resolver/mykey.key',
+--     tls = true,
+-- })
+
 -- To disable DNSSEC validation, uncomment the following line (not recommended)
 -- trust_anchors.remove('.')
 

diff --git a/etc/config/config.isp.in b/etc/config/config.isp.in
index 4c29db19aa312d373d61dd5e362fcd7b52978098..fed2f0ecdf6b53913e0fe49c76ecfc37edaa119d 100644 (file)
--- a/etc/config/config.isp.in
+++ b/etc/config/config.isp.in
@@ -3,6 +3,14 @@
 -- Refer to manual: https://knot-resolver.readthedocs.io/en/stable/daemon.html#configuration
 @config_defaults@
 
+-- For DNS-over-HTTPS and web management when using http module
+-- modules.load('http')
+-- http.config({
+--     cert = '/etc/knot-resolver/mycert.crt',
+--     key = '/etc/knot-resolver/mykey.key',
+--     tls = true,
+-- })
+
 -- To disable DNSSEC validation, uncomment the following line (not recommended)
 -- trust_anchors.remove('.')
 

diff --git a/etc/config/config.personal.in b/etc/config/config.personal.in
index 6d9844e020fec97b41fcf7f6567b1093be8bf2be..87589e7864f8175c693148d4bae70d9c0f674e89 100644 (file)
--- a/etc/config/config.personal.in
+++ b/etc/config/config.personal.in
@@ -2,6 +2,14 @@
 -- Refer to manual: http://knot-resolver.readthedocs.org/en/stable/daemon.html#configuration
 @config_defaults@
 
+-- For DNS-over-HTTPS and web management when using http module
+-- modules.load('http')
+-- http.config({
+--     cert = '/etc/knot-resolver/mycert.crt',
+--     key = '/etc/knot-resolver/mykey.key',
+--     tls = true,
+-- })
+
 -- To disable DNSSEC validation, uncomment the following line (not recommended)
 -- trust_anchors.remove('.')
 

diff --git a/etc/config/config.splitview.in b/etc/config/config.splitview.in
index 60da665d79c4b8ce7684f9e91b14e8f19d65c3cc..46363719161ad62cbdbcfae83dd057aeea4e3926 100644 (file)
--- a/etc/config/config.splitview.in
+++ b/etc/config/config.splitview.in
@@ -3,6 +3,14 @@
 -- Refer to manual: https://knot-resolver.readthedocs.io/en/stable/daemon.html#configuration
 @config_defaults@
 
+-- For DNS-over-HTTPS and web management when using http module
+-- modules.load('http')
+-- http.config({
+--     cert = '/etc/knot-resolver/mycert.crt',
+--     key = '/etc/knot-resolver/mykey.key',
+--     tls = true,
+-- })
+
 -- To disable DNSSEC validation, uncomment the following line (not recommended)
 -- trust_anchors.remove('.')
 

diff --git a/etc/config/meson.build b/etc/config/meson.build
index 4f160ff1ddf02efd50ec0ecb9edfe3d53c49bf27..e7d28e219c6ce4e7eb216d9657de37ac2664884f 100644 (file)
--- a/etc/config/meson.build
+++ b/etc/config/meson.build
@@ -12,6 +12,12 @@ net.listen('127.0.0.1', 853)
 net.listen('::1')
 net.listen('::1', 853)
 
+-- Extra interfaces for http module
+-- net.listen('127.0.0.1', 44353, { kind = 'doh' })
+-- net.listen('::1', 44353, { kind = 'doh' })
+-- net.listen('127.0.0.1', 8453, { kind = 'webmgmt' })
+-- net.listen('::1', 8453, { kind = 'webmgmt' })
+
 -- Drop root privileges
 user('@0@', '@1@')'''.format(user, group)
 endif

diff --git a/systemd/kresd.systemd.7.in b/systemd/kresd.systemd.7.in
index 758341864ceb6dab1a24ff2f399aa5ce7e2d04ef..9dc49dd1e5b3de5b7f8a8bde5f551056154cba08 100644 (file)
--- a/systemd/kresd.systemd.7.in
+++ b/systemd/kresd.systemd.7.in
@@ -104,6 +104,28 @@ compatible with IPv4 syntax in \fIview:addr()\fR when using the view module.
 For possible workarounds, see
 https://gitlab.labs.nic.cz/knot/knot-resolver/issues/445
 
+To configure socket for DNS-over-HTTPS, make sure you have
+\fBkresd-doh.socket\fR installed (it might be part of a separate
+knot-resolver-module-http package).  Then, you can configure its network
+interfaces as above. Also, don't forget to load http module in configuration
+file, otherwise the socket won't have any function.
+
+For example, to remove the default localhost:44353 and listen on all interfaces
+on port 443, create the following drop-in file for \fBkresd-doh.socket\fR:
+
+.nf
+.RS 4n
+# /etc/systemd/system/kresd-doh.socket.d/override.conf
+[Socket]
+ListenStream=
+ListenStream=[::]:443
+.RE
+.fi
+
+Make sure no other service is using port 443, as that will result in
+unpredictable behaviour. Alternately, you can use port 44353 where a collision
+is unlikely.
+
 For more detailed socket configuration, see \fBsystemd.socket\fR(5).
 
 .B Concurrent daemons